Users¶
This section documents everything related to users.
Discord Models¶
User¶
- asynccreate_dm
- asyncfetch_message
- defhistory
- defmentioned_in
- asyncpins
- asyncsend
- asynctrigger_typing
- deftyping
- class disnake.User[source]¶
Represents a Discord user.
- x == y
Checks if two users are equal.
- x != y
Checks if two users are not equal.
- hash(x)
Return the user’s hash.
- str(x)
Returns the user’s username (with discriminator, if not migrated to new system yet).
- discriminator¶
The user’s discriminator.
Note
This is being phased out by Discord; the username system is moving away from
username#discriminator
to users having a globally unique username. The value of a single zero ("0"
) indicates that the user has been migrated to the new system. See the help article for details.- Type:
- global_name¶
The user’s global display name, if set. This takes precedence over
name
when shown.New in version 2.9.
- Type:
Optional[
str
]
- async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)[source]¶
Returns an
AsyncIterator
that enables receiving the destination’s message history.You must have
Permissions.read_message_history
permission to use this.Examples
Usage
counter = 0 async for message in channel.history(limit=200): if message.author == client.user: counter += 1
Flattening into a list:
messages = await channel.history(limit=123).flatten() # messages is now a list of Message...
All parameters are optional.
- Parameters:
limit (Optional[
int
]) – The number of messages to retrieve. IfNone
, retrieves every message in the channel. Note, however, that this would make it a slow operation.before (Optional[Union[
abc.Snowflake
,datetime.datetime
]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.after (Optional[Union[
abc.Snowflake
,datetime.datetime
]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.around (Optional[Union[
abc.Snowflake
,datetime.datetime
]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.oldest_first (Optional[
bool
]) – If set toTrue
, return messages in oldest->newest order. Defaults toTrue
ifafter
is specified, otherwiseFalse
.
- Raises:
Forbidden – You do not have permissions to get channel message history.
HTTPException – The request to get message history failed.
- Yields:
Message
– The message with the message data parsed.
- async with typing()[source]¶
Returns a context manager that allows you to type for an indefinite period of time.
This is useful for denoting long computations in your bot.
Note
This is both a regular context manager and an async context manager. This means that both
with
andasync with
work with this.Example Usage:
async with channel.typing(): # simulate something heavy await asyncio.sleep(10) await channel.send('done!')
- property dm_channel[source]¶
Returns the channel associated with this user if it exists.
If this returns
None
, you can create a DM channel by calling thecreate_dm()
coroutine function.- Type:
Optional[
DMChannel
]
- property mutual_guilds[source]¶
The guilds that the user shares with the client.
Note
This will only return mutual guilds within the client’s internal cache.
New in version 1.7.
- Type:
List[
Guild
]
- property accent_color[source]¶
Returns the user’s accent color, if applicable.
There is an alias for this named
accent_colour
.New in version 2.0.
Note
This information is only available via
Client.fetch_user()
.- Type:
Optional[
Colour
]
- property accent_colour[source]¶
Returns the user’s accent colour, if applicable.
There is an alias for this named
accent_color
.New in version 2.0.
Note
This information is only available via
Client.fetch_user()
.- Type:
Optional[
Colour
]
- property avatar[source]¶
Returns an
Asset
for the avatar the user has.If the user does not have a traditional avatar,
None
is returned. If you want the avatar that a user has displayed, considerdisplay_avatar
.- Type:
Optional[
Asset
]
- property banner[source]¶
Returns the user’s banner asset, if available.
New in version 2.0.
Note
This information is only available via
Client.fetch_user()
.- Type:
Optional[
Asset
]
- property color[source]¶
A property that returns a color denoting the rendered color for the user. This always returns
Colour.default()
.There is an alias for this named
colour
.- Type:
- property colour[source]¶
A property that returns a colour denoting the rendered colour for the user. This always returns
Colour.default()
.There is an alias for this named
color
.- Type:
- await create_dm()[source]¶
This function is a coroutine.
Creates a
DMChannel
with this user.This should be rarely called, as this is done transparently for most people.
- Returns:
The channel that was created.
- Return type:
- property created_at[source]¶
Returns the user’s creation time in UTC.
This is when the user’s Discord account was created.
- Type:
- property default_avatar[source]¶
Returns the default avatar for a given user.
Changed in version 2.9: Added handling for users migrated to the new username system without discriminators.
- Type:
- property display_avatar[source]¶
Returns the user’s display avatar.
For regular users this is just their default avatar or uploaded avatar.
New in version 2.0.
- Type:
- property display_name[source]¶
Returns the user’s display name.
This is their
global name
if set, or theirusername
otherwise.Changed in version 2.9: Added
global_name
.- Type:
- await fetch_message(id, /)[source]¶
This function is a coroutine.
Retrieves a single
Message
from the destination.- Parameters:
id (
int
) – The message ID to look for.- Raises:
NotFound – The specified message was not found.
Forbidden – You do not have the permissions required to get a message.
HTTPException – Retrieving the message failed.
- Returns:
The message asked for.
- Return type:
- await pins()[source]¶
This function is a coroutine.
Retrieves all messages that are currently pinned in the channel.
Note
Due to a limitation with the Discord API, the
Message
objects returned by this method do not contain completeMessage.reactions
data.- Raises:
HTTPException – Retrieving the pinned messages failed.
- Returns:
The messages that are currently pinned.
- Return type:
List[
Message
]
- await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, suppress_embeds=None, flags=None, allowed_mentions=None, reference=None, mention_author=None, view=None, components=None)[source]¶
This function is a coroutine.
Sends a message to the destination with the content given.
The content must be a type that can convert to a string through
str(content)
.At least one of
content
,embed
/embeds
,file
/files
,stickers
,components
, orview
must be provided.To upload a single file, the
file
parameter should be used with a singleFile
object. To upload multiple files, thefiles
parameter should be used with alist
ofFile
objects. Specifying both parameters will lead to an exception.To upload a single embed, the
embed
parameter should be used with a singleEmbed
object. To upload multiple embeds, theembeds
parameter should be used with alist
ofEmbed
objects. Specifying both parameters will lead to an exception.Changed in version 2.6: Raises
TypeError
orValueError
instead ofInvalidArgument
.- Parameters:
content (Optional[
str
]) – The content of the message to send.tts (
bool
) – Whether the message should be sent using text-to-speech.embed (
Embed
) – The rich embed for the content to send. This cannot be mixed with theembeds
parameter.embeds (List[
Embed
]) –A list of embeds to send with the content. Must be a maximum of 10. This cannot be mixed with the
embed
parameter.New in version 2.0.
file (
File
) – The file to upload. This cannot be mixed with thefiles
parameter.files (List[
File
]) – A list of files to upload. Must be a maximum of 10. This cannot be mixed with thefile
parameter.stickers (Sequence[Union[
GuildSticker
,StandardSticker
,StickerItem
]]) –A list of stickers to upload. Must be a maximum of 3.
New in version 2.0.
nonce (Union[
str
,int
]) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.delete_after (
float
) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.allowed_mentions (
AllowedMentions
) –Controls the mentions being processed in this message. If this is passed, then the object is merged with
Client.allowed_mentions
. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set inClient.allowed_mentions
. If no object is passed at all then the defaults given byClient.allowed_mentions
are used instead.New in version 1.4.
reference (Union[
Message
,MessageReference
,PartialMessage
]) –A reference to the
Message
to which you are replying, this can be created usingMessage.to_reference()
or passed directly as aMessage
. You can control whether this mentions the author of the referenced message using theAllowedMentions.replied_user
attribute ofallowed_mentions
or by settingmention_author
.New in version 1.6.
mention_author (Optional[
bool
]) –If set, overrides the
AllowedMentions.replied_user
attribute ofallowed_mentions
.New in version 1.6.
view (
ui.View
) –A Discord UI View to add to the message. This cannot be mixed with
components
.New in version 2.0.
components (Union[
disnake.ui.ActionRow
,disnake.ui.WrappedComponent
, List[Union[disnake.ui.ActionRow
,disnake.ui.WrappedComponent
, List[disnake.ui.WrappedComponent
]]]]) –A list of components to include in the message. This cannot be mixed with
view
.New in version 2.4.
suppress_embeds (
bool
) –Whether to suppress embeds for the message. This hides all the embeds from the UI if set to
True
.New in version 2.5.
flags (
MessageFlags
) –The flags to set for this message. Only
suppress_embeds
andsuppress_notifications
are supported.If parameter
suppress_embeds
is provided, that will override the setting ofMessageFlags.suppress_embeds
.New in version 2.9.
- Raises:
HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
TypeError – Specified both
file
andfiles
, or you specified bothembed
andembeds
, or you specified bothview
andcomponents
, or thereference
object is not aMessage
,MessageReference
orPartialMessage
.ValueError – The
files
orembeds
list is too large.
- Returns:
The message that was sent.
- Return type:
Data Classes¶
PublicUserFlags¶
- active_developer
- bug_hunter
- bug_hunter_level_2
- discord_certified_moderator
- early_supporter
- early_verified_bot_developer
- http_interactions_bot
- hypesquad
- hypesquad_balance
- hypesquad_bravery
- hypesquad_brilliance
- moderator_programs_alumni
- partner
- spammer
- staff
- system
- team_user
- value
- verified_bot
- verified_bot_developer
- defall
- class disnake.PublicUserFlags[source]¶
Wraps up the Discord User Public flags.
- x == y
Checks if two PublicUserFlags instances are equal.
- x != y
Checks if two PublicUserFlags instances are not equal.
- x <= y
Checks if a PublicUserFlags instance is a subset of another PublicUserFlags instance.
New in version 2.6.
- x >= y
Checks if a PublicUserFlags instance is a superset of another PublicUserFlags instance.
New in version 2.6.
- x < y
Checks if a PublicUserFlags instance is a strict subset of another PublicUserFlags instance.
New in version 2.6.
- x > y
Checks if a PublicUserFlags instance is a strict superset of another PublicUserFlags instance.
New in version 2.6.
- x | y, x |= y
Returns a new PublicUserFlags instance with all enabled flags from both x and y. (Using
|=
will update in place).New in version 2.6.
- x & y, x &= y
Returns a new PublicUserFlags instance with only flags enabled on both x and y. (Using
&=
will update in place).New in version 2.6.
- x ^ y, x ^= y
Returns a new PublicUserFlags instance with only flags enabled on one of x or y, but not both. (Using
^=
will update in place).New in version 2.6.
- ~x
Returns a new PublicUserFlags instance with all flags from x inverted.
New in version 2.6.
- hash(x)
Return the flag’s hash.
- iter(x)
Returns an iterator of
(name, value)
pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.
Additionally supported are a few operations on class attributes.
- PublicUserFlags.y | PublicUserFlags.z, PublicUserFlags(y=True) | PublicUserFlags.z
Returns a PublicUserFlags instance with all provided flags enabled.
New in version 2.6.
- ~PublicUserFlags.y
Returns a PublicUserFlags instance with all flags except
y
inverted from their default value.New in version 2.6.
New in version 1.4.
- value¶
The raw value. This value is a bit array field of a 53-bit integer representing the currently available flags. You should query flags via the properties rather than using this raw value.
- Type:
- early_verified_bot_developer¶
An alias for
verified_bot_developer
.New in version 1.5.
- Type:
- moderator_programs_alumni¶
Returns
True
if the user is a Discord Moderator Programs Alumni.New in version 2.8.
- Type:
- discord_certified_moderator¶
An alias for
moderator_programs_alumni
.New in version 2.0.
- Type:
- http_interactions_bot¶
Returns
True
if the user is a bot that only uses HTTP interactions.New in version 2.3.
- Type:
MemberFlags¶
- class disnake.MemberFlags[source]¶
Wraps up Discord Member flags.
- x == y
Checks if two MemberFlags instances are equal.
- x != y
Checks if two MemberFlags instances are not equal.
- x <= y
Checks if an MemberFlags instance is a subset of another MemberFlags instance.
- x >= y
Checks if an MemberFlags instance is a superset of another MemberFlags instance.
- x < y
Checks if an MemberFlags instance is a strict subset of another MemberFlags instance.
- x > y
Checks if an MemberFlags instance is a strict superset of another MemberFlags instance.
- x | y, x |= y
Returns a new MemberFlags instance with all enabled flags from both x and y. (Using
|=
will update in place).
- x & y, x &= y
Returns a new MemberFlags instance with only flags enabled on both x and y. (Using
&=
will update in place).
- x ^ y, x ^= y
Returns a new MemberFlags instance with only flags enabled on one of x or y, but not both. (Using
^=
will update in place).
- ~x
Returns a new MemberFlags instance with all flags from x inverted.
- hash(x)
Returns the flag’s hash.
- iter(x)
Returns an iterator of
(name, value)
pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.
Additionally supported are a few operations on class attributes.
- MemberFlags.y | MemberFlags.z, MemberFlags(y=True) | MemberFlags.z
Returns a MemberFlags instance with all provided flags enabled.
- ~MemberFlags.y
Returns a MemberFlags instance with all flags except
y
inverted from their default value.
New in version 2.8.
- value¶
The raw value. You should query flags via the properties rather than using this raw value.
- Type:
- bypasses_verification¶
Returns
True
if the member is able to bypass guild verification requirements.- Type:
Enumerations¶
UserFlags¶
- class disnake.UserFlags[source]¶
Represents Discord User flags.
- staff¶
The user is a Discord Employee.
- partner¶
The user is a Discord Partner.
- hypesquad¶
The user is a HypeSquad Events member.
- bug_hunter¶
The user is a Bug Hunter.
- mfa_sms¶
The user has SMS recovery for Multi Factor Authentication enabled.
The user has dismissed the Discord Nitro promotion.
- hypesquad_bravery¶
The user is a HypeSquad Bravery member.
- hypesquad_brilliance¶
The user is a HypeSquad Brilliance member.
- hypesquad_balance¶
The user is a HypeSquad Balance member.
- early_supporter¶
The user is an Early Supporter.
- team_user¶
The user is a Team User.
- system¶
The user is a system user (i.e. represents Discord officially).
- has_unread_urgent_messages¶
The user has an unread system message.
- bug_hunter_level_2¶
The user is a Bug Hunter Level 2.
- verified_bot¶
The user is a Verified Bot.
- verified_bot_developer¶
The user is an Early Verified Bot Developer.
- discord_certified_moderator¶
The user is a Discord Certified Moderator.
- http_interactions_bot¶
The user is a bot that only uses HTTP interactions.
New in version 2.3.
- spammer¶
The user is marked as a spammer.
New in version 2.3.
- active_developer¶
The user is an Active Developer.
New in version 2.8.
DefaultAvatar¶
- class disnake.DefaultAvatar[source]¶
Represents the default avatar of a Discord
User
.- blurple¶
Represents the default avatar with the color blurple. See also
Colour.blurple
- grey¶
Represents the default avatar with the color grey. See also
Colour.greyple
- green¶
Represents the default avatar with the color green. See also
Colour.green
- orange¶
Represents the default avatar with the color orange. See also
Colour.orange
- red¶
Represents the default avatar with the color red. See also
Colour.red
- fuchsia¶
Represents the default avatar with the color fuchsia. See also
Colour.fuchsia
New in version 2.9.