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 the email scope. Will always be None for bot users.

is_mfa_enabled: bool[source]#

Whether the user’s account has multi-factor authentication enabled.

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 the email scope.

locale: str | hikari.locales.Locale | None[source]#

The user’s set locale.

This is not provided in the READY event.

premium_type: PremiumType | int | None[source]#

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:
contenthikari.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 a str.

If this is a hikari.embeds.Embed and no embed nor embeds 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 no attachment and no attachments kwargs are provided.

Other Parameters:
attachmenthikari.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 or str 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 as hikari.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 hikari.files.Bytes is passed, or a str

    that contains a valid data URI is passed, then this is uploaded with a randomized file name if not provided.

  • 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 of concurrent.futures.Executor that is being used for the application (default is a thread pool which supports this behaviour).

attachmentshikari.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.

componenthikari.undefined.UndefinedOr[hikari.api.special_endpoints.ComponentBuilder]

If provided, builder object of the component to include in this message.

componentshikari.undefined.UndefinedOr[typing.Sequence[hikari.api.special_endpoints.ComponentBuilder]]

If provided, a sequence of the component builder objects to include in this message.

embedhikari.undefined.UndefinedOr[hikari.embeds.Embed]

If provided, the message embed.

embedshikari.undefined.UndefinedOr[typing.Sequence[hikari.embeds.Embed]]

If provided, the message embeds.

ttshikari.undefined.UndefinedOr[bool]

If provided, whether the message will be read out by a screen reader using Discord’s TTS (text-to-speech) system.

replyhikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]]

If provided, the message to reply to.

reply_must_existhikari.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_everyonehikari.undefined.UndefinedOr[bool]

If provided, whether the message should parse @everyone/@here mentions.

mentions_replyhikari.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_mentionshikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser], bool]]

If provided, and True, all user mentions will be detected. If provided, and False, all user mentions will be ignored if appearing in the message body. Alternatively this may be a collection of hikari.snowflakes.Snowflake, or hikari.users.PartialUser derivatives to enforce mentioning specific users.

role_mentionshikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.guilds.PartialRole], bool]]

If provided, and True, all role mentions will be detected. If provided, and False, all role mentions will be ignored if appearing in the message body. Alternatively this may be a collection of hikari.snowflakes.Snowflake, or hikari.guilds.PartialRole derivatives to enforce mentioning specific roles.

flagshikari.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 and SUPPRESS_EMBEDS.

Returns:
hikari.messages.Message

The created message.

Raises:
ValueError

If more than 100 unique objects/entities are passed for role_mentions or user_mentions.

TypeError

If both attachment and attachments 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>'
abstract property username: hikari.undefined.UndefinedOr[str][source]#

Username for the user.

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:
contenthikari.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 a str.

If this is a hikari.embeds.Embed and no embed nor embeds 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 no attachment and no attachments kwargs are provided.

Other Parameters:
attachmenthikari.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 or str 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 as hikari.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 hikari.files.Bytes is passed, or a str

    that contains a valid data URI is passed, then this is uploaded with a randomized file name if not provided.

  • 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 of concurrent.futures.Executor that is being used for the application (default is a thread pool which supports this behaviour).

attachmentshikari.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.

componenthikari.undefined.UndefinedOr[hikari.api.special_endpoints.ComponentBuilder]

If provided, builder object of the component to include in this message.

componentshikari.undefined.UndefinedOr[typing.Sequence[hikari.api.special_endpoints.ComponentBuilder]]

If provided, a sequence of the component builder objects to include in this message.

embedhikari.undefined.UndefinedOr[hikari.embeds.Embed]

If provided, the message embed.

embedshikari.undefined.UndefinedOr[typing.Sequence[hikari.embeds.Embed]]

If provided, the message embeds.

ttshikari.undefined.UndefinedOr[bool]

If provided, whether the message will be read out by a screen reader using Discord’s TTS (text-to-speech) system.

replyhikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]]

If provided, the message to reply to.

reply_must_existhikari.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_everyonehikari.undefined.UndefinedOr[bool]

If provided, whether the message should parse @everyone/@here mentions.

mentions_replyhikari.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_mentionshikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser], bool]]

If provided, and True, all user mentions will be detected. If provided, and False, all user mentions will be ignored if appearing in the message body. Alternatively this may be a collection of hikari.snowflakes.Snowflake, or hikari.users.PartialUser derivatives to enforce mentioning specific users.

role_mentionshikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.guilds.PartialRole], bool]]

If provided, and True, all role mentions will be detected. If provided, and False, all role mentions will be ignored if appearing in the message body. Alternatively this may be a collection of hikari.snowflakes.Snowflake, or hikari.guilds.PartialRole derivatives to enforce mentioning specific roles.

flagshikari.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 and SUPPRESS_EMBEDS.

Returns:
hikari.messages.Message

The created message.

Raises:
ValueError

If more than 100 unique objects/entities are passed for role_mentions or user_mentions.

TypeError

If both attachment and attachments 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.

NITRO = 2[source]#

Premium including all perks (e.g. 2 server boosts).

NITRO_CLASSIC = 1[source]#

Premium including basic perks like animated emojis and avatars.

NONE = 0[source]#

No premium.

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 use default_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.

abstract property discriminator: str[source]#

Discriminator for the user.

property display_avatar_url: hikari.files.URL[source]#

Display avatar URL for this user.

abstract property flags: UserFlag[source]#

Flag bits that are set for the user.

abstract property is_bot: bool[source]#

Whether this user is a bot account.

abstract property is_system: 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>'
abstract property username: str[source]#

Username for the user.

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 the default_avatar_url attribute instead to fetch the displayed URL.

Parameters:
exttyping.Optional[str]

The ext to use for this URL, defaults to png or gif. Supports png, jpeg, jpg, webp and gif (when animated). Will be ignored for default avatars which can only be png.

If None, then the correct default extension is determined based on whether the icon is animated or not.

sizeint

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.

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:
exttyping.Optional[str]

The ext to use for this URL, defaults to png or gif. Supports png, jpeg, jpg, webp and gif (when animated).

If None, then the correct default extension is determined based on whether the banner is animated or not.

sizeint

The size to set for the URL, defaults to 4096. Can be any power of two between 16 and 4096.

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.

ACTIVE_DEVELOPER[source]#

User is an active bot developer.

BOT_HTTP_INTERACTIONS[source]#

Bot uses only HTTP interactions and is shown in the active member list.

BUG_HUNTER_LEVEL_1[source]#

Bug Hunter Level 1.

BUG_HUNTER_LEVEL_2[source]#

Bug Hunter Level 2.

DISCORD_CERTIFIED_MODERATOR[source]#

Discord Certified Moderator.

DISCORD_EMPLOYEE[source]#

Discord Employee.

EARLY_SUPPORTER[source]#

Early Supporter.

EARLY_VERIFIED_DEVELOPER[source]#

Early verified Bot Developer.

Only applies to users that verified their account before 20th August 2019.

HYPESQUAD_BALANCE[source]#

House of Balance.

HYPESQUAD_BRAVERY[source]#

House of Bravery.

HYPESQUAD_BRILLIANCE[source]#

House of Brilliance.

HYPESQUAD_EVENTS[source]#

HypeSquad Events.

NONE = 0[source]#

None.

PARTNERED_SERVER_OWNER[source]#

Owner of a partnered Discord server.

TEAM_USER[source]#

Team user.

VERIFIED_BOT[source]#

Verified Bot.