hikari.users#
Application and entities that are used to describe Users on Discord.
Module Contents#
- class hikari.users.OwnUser[source]#
Bases:
UserImpl
Represents a user with extended OAuth2 information.
- email: str | None[source]#
The user’s set email.
Will be
None
if retrieved through OAuth2 flow without theemail
scope. Will always beNone
for bot users.
- is_verified: bool | None[source]#
Whether the email for this user’s account has been verified.
Will be
None
if retrieved through the OAuth2 flow without theemail
scope.
- locale: str | hikari.locales.Locale | None[source]#
The user’s set locale.
This is not provided in the
READY
event.
The type of Nitro Subscription this user account had.
This will always be
None
for bots.
- async fetch_dm_channel()[source]#
Fetch the DM channel for this user.
- Returns:
hikari.channels.DMChannel
The requested channel.
- Raises:
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.NotFoundError
If the user is not found.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than
max_rate_limit
when making a request.hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
- async fetch_self()[source]#
Get this user’s up-to-date object.
- Returns:
hikari.users.OwnUser
The requested user object.
- Raises:
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than
max_rate_limit
when making a request.hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
- async send(content=undefined.UNDEFINED, *, attachment=undefined.UNDEFINED, attachments=undefined.UNDEFINED, component=undefined.UNDEFINED, components=undefined.UNDEFINED, embed=undefined.UNDEFINED, embeds=undefined.UNDEFINED, nonce=undefined.UNDEFINED, tts=undefined.UNDEFINED, reply=undefined.UNDEFINED, reply_must_exist=undefined.UNDEFINED, mentions_everyone=undefined.UNDEFINED, mentions_reply=undefined.UNDEFINED, user_mentions=undefined.UNDEFINED, role_mentions=undefined.UNDEFINED, flags=undefined.UNDEFINED)[source]#
Send a message to this user in DM’s.
- Parameters:
- content
hikari.undefined.UndefinedOr
[typing.Any
] If provided, the message contents. If
hikari.undefined.UNDEFINED
, then nothing will be sent in the content. Any other value here will be cast to astr
.If this is a
hikari.embeds.Embed
and noembed
norembeds
kwarg is provided, then this will instead update the embed. This allows for simpler syntax when sending an embed alone.Likewise, if this is a
hikari.files.Resource
, then the content is instead treated as an attachment if noattachment
and noattachments
kwargs are provided.
- content
- Other Parameters:
- attachment
hikari.undefined.UndefinedOr
[hikari.files.Resourceish
] If provided, the message attachment. This can be a resource, or string of a path on your computer or a URL.
Attachments can be passed as many different things, to aid in convenience.
- If a
pathlib.PurePath
orstr
to a valid URL, the resource at the given URL will be streamed to Discord when sending the message. Subclasses of
hikari.files.WebResource
such ashikari.files.URL
,hikari.messages.Attachment
,hikari.emojis.Emoji
,EmbedResource
, etc will also be uploaded this way. This will use bit-inception, so only a small percentage of the resource will remain in memory at any one time, thus aiding in scalability.
- If a
- If a
hikari.files.Bytes
is passed, or astr
that contains a valid data URI is passed, then this is uploaded with a randomized file name if not provided.
- If a
- If a
hikari.files.File
,pathlib.PurePath
or str
that is an absolute or relative path to a file on your file system is passed, then this resource is uploaded as an attachment using non-blocking code internally and streamed using bit-inception where possible. This depends on the type ofconcurrent.futures.Executor
that is being used for the application (default is a thread pool which supports this behaviour).
- If a
- attachments
hikari.undefined.UndefinedOr
[typing.Sequence
[hikari.files.Resourceish
]] If provided, the message attachments. These can be resources, or strings consisting of paths on your computer or URLs.
- component
hikari.undefined.UndefinedOr
[hikari.api.special_endpoints.ComponentBuilder
] If provided, builder object of the component to include in this message.
- components
hikari.undefined.UndefinedOr
[typing.Sequence
[hikari.api.special_endpoints.ComponentBuilder
]] If provided, a sequence of the component builder objects to include in this message.
- embed
hikari.undefined.UndefinedOr
[hikari.embeds.Embed
] If provided, the message embed.
- embeds
hikari.undefined.UndefinedOr
[typing.Sequence
[hikari.embeds.Embed
]] If provided, the message embeds.
- tts
hikari.undefined.UndefinedOr
[bool] If provided, whether the message will be read out by a screen reader using Discord’s TTS (text-to-speech) system.
- reply
hikari.undefined.UndefinedOr
[hikari.snowflakes.SnowflakeishOr
[hikari.messages.PartialMessage
]] If provided, the message to reply to.
- reply_must_exist
hikari.undefined.UndefinedOr
[bool] If provided, whether to error if the message being replied to does not exist instead of sending as a normal (non-reply) message. Defaults to
True
.This will not do anything if not being used with
reply
.- mentions_everyone
hikari.undefined.UndefinedOr
[bool] If provided, whether the message should parse @everyone/@here mentions.
- mentions_reply
hikari.undefined.UndefinedOr
[bool] If provided, whether to mention the author of the message that is being replied to.
This will not do anything if not being used with
reply
.- user_mentions
hikari.undefined.UndefinedOr
[typing.Union
[hikari.snowflakes.SnowflakeishSequence
[hikari.users.PartialUser
], bool]] If provided, and
True
, all user mentions will be detected. If provided, andFalse
, all user mentions will be ignored if appearing in the message body. Alternatively this may be a collection ofhikari.snowflakes.Snowflake
, orhikari.users.PartialUser
derivatives to enforce mentioning specific users.- role_mentions
hikari.undefined.UndefinedOr
[typing.Union
[hikari.snowflakes.SnowflakeishSequence
[hikari.guilds.PartialRole
], bool]] If provided, and
True
, all role mentions will be detected. If provided, andFalse
, all role mentions will be ignored if appearing in the message body. Alternatively this may be a collection ofhikari.snowflakes.Snowflake
, orhikari.guilds.PartialRole
derivatives to enforce mentioning specific roles.- flags
hikari.undefined.UndefinedOr
[hikari.messages.MessageFlag
] If provided, optional flags to set on the message. If
hikari.undefined.UNDEFINED
, then nothing is changed.Note that some flags may not be able to be set. Currently the only flags that can be set are
NONE
andSUPPRESS_EMBEDS
.
- attachment
- Returns:
hikari.messages.Message
The created message.
- Raises:
ValueError
If more than 100 unique objects/entities are passed for
role_mentions
oruser_mentions
.TypeError
If both
attachment
andattachments
are specified.hikari.errors.BadRequestError
This may be raised in several discrete situations, such as messages being empty with no attachments or embeds; messages with more than 2000 characters in them, embeds that exceed one of the many embed limits; too many attachments; attachments that are too large; invalid image URLs in embeds;
reply
not found or not in the same channel; too many components.hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.ForbiddenError
If you are missing the
SEND_MESSAGES
in the channel or the person you are trying to message has the DM’s disabled.hikari.errors.NotFoundError
If the user is not found.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than
max_rate_limit
when making a request.hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
- class hikari.users.PartialUser[source]#
Bases:
hikari.snowflakes.Unique
,abc.ABC
A partial interface for a user.
Fields may or may not be present, and should be explicitly checked before using them to ensure they are not
hikari.undefined.UNDEFINED
.This is used for endpoints and events that only expose partial user information.
For full user info, consider calling the
fetch_self
method to perform an API call.- abstract property accent_color: hikari.undefined.UndefinedNoneOr[hikari.colors.Color][source]#
Custom banner color for the user if set, else
None
.The official client will decide the default color if not set.
- property accent_colour: hikari.undefined.UndefinedNoneOr[hikari.colors.Color][source]#
Alias for the
accent_color
field.
- abstract property app: hikari.traits.RESTAware[source]#
Client application that models may use for procedures.
- abstract property avatar_hash: hikari.undefined.UndefinedNoneOr[str][source]#
Avatar hash for the user, if they have one, otherwise
None
.
- abstract property banner_hash: hikari.undefined.UndefinedNoneOr[str][source]#
Banner hash for the user, if they have one, otherwise
None
.
- abstract property discriminator: hikari.undefined.UndefinedOr[str][source]#
Discriminator for the user.
- abstract property flags: hikari.undefined.UndefinedOr[UserFlag][source]#
Flag bits that are set for the user.
- abstract property is_bot: hikari.undefined.UndefinedOr[bool][source]#
Whether this user is a bot account.
- abstract property is_system: hikari.undefined.UndefinedOr[bool][source]#
Whether this user is a system account.
- abstract property mention: str[source]#
Return a raw mention string for the given user.
Examples
>>> some_user.mention '<@123456789123456789>'
- async fetch_dm_channel()[source]#
Fetch the DM channel for this user.
- Returns:
hikari.channels.DMChannel
The requested channel.
- Raises:
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.NotFoundError
If the user is not found.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than
max_rate_limit
when making a request.hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
- async fetch_self()[source]#
Get this user’s up-to-date object by performing an API call.
- Returns:
hikari.users.User
The requested user object.
- Raises:
hikari.errors.NotFoundError
If the user is not found.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than
max_rate_limit
when making a request.hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
- async send(content=undefined.UNDEFINED, *, attachment=undefined.UNDEFINED, attachments=undefined.UNDEFINED, component=undefined.UNDEFINED, components=undefined.UNDEFINED, embed=undefined.UNDEFINED, embeds=undefined.UNDEFINED, tts=undefined.UNDEFINED, reply=undefined.UNDEFINED, reply_must_exist=undefined.UNDEFINED, mentions_everyone=undefined.UNDEFINED, mentions_reply=undefined.UNDEFINED, user_mentions=undefined.UNDEFINED, role_mentions=undefined.UNDEFINED, flags=undefined.UNDEFINED)[source]#
Send a message to this user in DM’s.
- Parameters:
- content
hikari.undefined.UndefinedOr
[typing.Any
] If provided, the message contents. If
hikari.undefined.UNDEFINED
, then nothing will be sent in the content. Any other value here will be cast to astr
.If this is a
hikari.embeds.Embed
and noembed
norembeds
kwarg is provided, then this will instead update the embed. This allows for simpler syntax when sending an embed alone.Likewise, if this is a
hikari.files.Resource
, then the content is instead treated as an attachment if noattachment
and noattachments
kwargs are provided.
- content
- Other Parameters:
- attachment
hikari.undefined.UndefinedOr
[hikari.files.Resourceish
] If provided, the message attachment. This can be a resource, or string of a path on your computer or a URL.
Attachments can be passed as many different things, to aid in convenience.
- If a
pathlib.PurePath
orstr
to a valid URL, the resource at the given URL will be streamed to Discord when sending the message. Subclasses of
hikari.files.WebResource
such ashikari.files.URL
,hikari.messages.Attachment
,hikari.emojis.Emoji
,EmbedResource
, etc will also be uploaded this way. This will use bit-inception, so only a small percentage of the resource will remain in memory at any one time, thus aiding in scalability.
- If a
- If a
hikari.files.Bytes
is passed, or astr
that contains a valid data URI is passed, then this is uploaded with a randomized file name if not provided.
- If a
- If a
hikari.files.File
,pathlib.PurePath
or str
that is an absolute or relative path to a file on your file system is passed, then this resource is uploaded as an attachment using non-blocking code internally and streamed using bit-inception where possible. This depends on the type ofconcurrent.futures.Executor
that is being used for the application (default is a thread pool which supports this behaviour).
- If a
- attachments
hikari.undefined.UndefinedOr
[typing.Sequence
[hikari.files.Resourceish
]] If provided, the message attachments. These can be resources, or strings consisting of paths on your computer or URLs.
- component
hikari.undefined.UndefinedOr
[hikari.api.special_endpoints.ComponentBuilder
] If provided, builder object of the component to include in this message.
- components
hikari.undefined.UndefinedOr
[typing.Sequence
[hikari.api.special_endpoints.ComponentBuilder
]] If provided, a sequence of the component builder objects to include in this message.
- embed
hikari.undefined.UndefinedOr
[hikari.embeds.Embed
] If provided, the message embed.
- embeds
hikari.undefined.UndefinedOr
[typing.Sequence
[hikari.embeds.Embed
]] If provided, the message embeds.
- tts
hikari.undefined.UndefinedOr
[bool] If provided, whether the message will be read out by a screen reader using Discord’s TTS (text-to-speech) system.
- reply
hikari.undefined.UndefinedOr
[hikari.snowflakes.SnowflakeishOr
[hikari.messages.PartialMessage
]] If provided, the message to reply to.
- reply_must_exist
hikari.undefined.UndefinedOr
[bool] If provided, whether to error if the message being replied to does not exist instead of sending as a normal (non-reply) message. Defaults to
True
.This will not do anything if not being used with
reply
.- mentions_everyone
hikari.undefined.UndefinedOr
[bool] If provided, whether the message should parse @everyone/@here mentions.
- mentions_reply
hikari.undefined.UndefinedOr
[bool] If provided, whether to mention the author of the message that is being replied to.
This will not do anything if not being used with
reply
.- user_mentions
hikari.undefined.UndefinedOr
[typing.Union
[hikari.snowflakes.SnowflakeishSequence
[hikari.users.PartialUser
], bool]] If provided, and
True
, all user mentions will be detected. If provided, andFalse
, all user mentions will be ignored if appearing in the message body. Alternatively this may be a collection ofhikari.snowflakes.Snowflake
, orhikari.users.PartialUser
derivatives to enforce mentioning specific users.- role_mentions
hikari.undefined.UndefinedOr
[typing.Union
[hikari.snowflakes.SnowflakeishSequence
[hikari.guilds.PartialRole
], bool]] If provided, and
True
, all role mentions will be detected. If provided, andFalse
, all role mentions will be ignored if appearing in the message body. Alternatively this may be a collection ofhikari.snowflakes.Snowflake
, orhikari.guilds.PartialRole
derivatives to enforce mentioning specific roles.- flags
hikari.undefined.UndefinedOr
[hikari.messages.MessageFlag
] If provided, optional flags to set on the message. If
hikari.undefined.UNDEFINED
, then nothing is changed.Note that some flags may not be able to be set. Currently the only flags that can be set are
NONE
andSUPPRESS_EMBEDS
.
- attachment
- Returns:
hikari.messages.Message
The created message.
- Raises:
ValueError
If more than 100 unique objects/entities are passed for
role_mentions
oruser_mentions
.TypeError
If both
attachment
andattachments
are specified.hikari.errors.BadRequestError
This may be raised in several discrete situations, such as messages being empty with no attachments or embeds; messages with more than 2000 characters in them, embeds that exceed one of the many embed limits; too many attachments; attachments that are too large; invalid image URLs in embeds;
reply
not found or not in the same channel; too many components.hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.ForbiddenError
If you are missing the
SEND_MESSAGES
in the channel or the person you are trying to message has the DM’s disabled.hikari.errors.NotFoundError
If the user is not found.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than
max_rate_limit
when making a request.hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
- class hikari.users.PremiumType[source]#
Bases:
int
,hikari.internal.enums.Enum
The types of Nitro.
- class hikari.users.User[source]#
Bases:
PartialUser
,abc.ABC
Interface for any user-like object.
This does not include partial users, as they may not be fully formed.
- abstract property accent_color: hikari.colors.Color | None[source]#
The custom banner color for the user, if set else
None
.The official client will decide the default color if not set.
- property accent_colour: hikari.colors.Color | None[source]#
Alias for the
accent_color
field.
- abstract property app: hikari.traits.RESTAware[source]#
Client application that models may use for procedures.
- abstract property avatar_hash: str | None[source]#
Avatar hash for the user, if they have one, otherwise
None
.
- property avatar_url: hikari.files.URL | None[source]#
Avatar URL for the user, if they have one set.
May be
None
if no custom avatar is set. In this case, you should usedefault_avatar_url
instead.
- abstract property banner_hash: str | None[source]#
Banner hash for the user, if they have one, otherwise
None
.
- property banner_url: hikari.files.URL | None[source]#
Banner URL for the user, if they have one set.
May be
None
if no custom banner is set.
- property default_avatar_url: hikari.files.URL[source]#
Default avatar URL for this user.
- property display_avatar_url: hikari.files.URL[source]#
Display avatar URL for this user.
- abstract property mention: str[source]#
Return a raw mention string for the given user.
Examples
>>> some_user.mention '<@123456789123456789>'
- make_avatar_url(*, ext=None, size=4096)[source]#
Generate the avatar URL for this user, if set.
If no custom avatar is set, this returns
None
. You can then use thedefault_avatar_url
attribute instead to fetch the displayed URL.- Parameters:
- ext
typing.Optional
[str
] The ext to use for this URL, defaults to
png
orgif
. Supportspng
,jpeg
,jpg
,webp
andgif
(when animated). Will be ignored for default avatars which can only bepng
.If
None
, then the correct default extension is determined based on whether the icon is animated or not.- size
int
The size to set for the URL, defaults to
4096
. Can be any power of two between 16 and 4096. Will be ignored for default avatars.
- ext
- Returns:
typing.Optional
[hikari.files.URL
]The URL to the avatar, or
None
if not present.
- Raises:
ValueError
If
size
is not a power of two or not between 16 and 4096.
- make_banner_url(*, ext=None, size=4096)[source]#
Generate the banner URL for this user, if set.
If no custom banner is set, this returns
None
.- Parameters:
- ext
typing.Optional
[str
] The ext to use for this URL, defaults to
png
orgif
. Supportspng
,jpeg
,jpg
,webp
andgif
(when animated).If
None
, then the correct default extension is determined based on whether the banner is animated or not.- size
int
The size to set for the URL, defaults to
4096
. Can be any power of two between 16 and 4096.
- ext
- Returns:
typing.Optional
[hikari.files.URL
]The URL to the banner, or
None
if not present.
- Raises:
ValueError
If
size
is not a power of two or not between 16 and 4096.
- class hikari.users.UserFlag[source]#
Bases:
hikari.internal.enums.Flag
The known user flags that represent account badges.
- BOT_HTTP_INTERACTIONS[source]#
Bot uses only HTTP interactions and is shown in the active member list.