Roles

This section documents everything related to roles - a way of granting (or limiting) access to certain information/actions for a group of users.

Discord Models

Role

Attributes
Methods
class disnake.Role[source]

Represents a Discord role in a Guild.

x == y

Checks if two roles are equal.

x != y

Checks if two roles are not equal.

x > y

Checks if a role is higher than another in the hierarchy.

x < y

Checks if a role is lower than another in the hierarchy.

x >= y

Checks if a role is higher or equal to another in the hierarchy.

x <= y

Checks if a role is lower or equal to another in the hierarchy.

hash(x)

Return the role’s hash.

str(x)

Returns the role’s name.

id

The ID of the role.

Type:

int

name

The name of the role.

Type:

str

guild

The guild the role belongs to.

Type:

Guild

hoist

Indicates if the role will be displayed separately from other members.

Type:

bool

position

The position of the role. This number is usually positive. The bottom role has a position of 0.

Warning

Multiple roles can have the same position number. As a consequence of this, comparing via role position is prone to subtle bugs if checking for role hierarchy. The recommended and correct way to compare for roles in the hierarchy is using the comparison operators on the role objects themselves.

Type:

int

managed

Indicates if the role is managed by the guild through some form of integrations such as Twitch.

Type:

bool

mentionable

Indicates if the role can be mentioned by users.

Type:

bool

tags

The role tags associated with this role.

Type:

Optional[RoleTags]

is_default()[source]

Checks if the role is the default role.

Return type:

bool

is_bot_managed()[source]

Whether the role is associated with a bot.

New in version 1.6.

Return type:

bool

is_premium_subscriber()[source]

Whether the role is the premium subscriber, AKA “boost”, role for the guild.

New in version 1.6.

Return type:

bool

is_linked_role()[source]

Whether the role is a linked role for the guild.

New in version 2.8.

Return type:

bool

is_integration()[source]

Whether the role is managed by an integration.

New in version 1.6.

Return type:

bool

is_available_for_purchase()[source]

Whether the role is a subscription role and available for purchase.

New in version 2.9.

Return type:

bool

is_subscription()[source]

Whether the role is associated with a role subscription.

New in version 2.9.

Return type:

bool

is_assignable()[source]

Whether the role is able to be assigned or removed by the bot.

New in version 2.0.

Return type:

bool

property permissions[source]

Returns the role’s permissions.

Type:

Permissions

property colour[source]

Returns the role colour. An alias exists under color.

Type:

Colour

property color[source]

Returns the role color. An alias exists under colour.

Type:

Colour

property icon[source]

Returns the role’s icon asset, if available.

New in version 2.0.

Type:

Optional[Asset]

property emoji[source]

Returns the role’s emoji, if available.

New in version 2.0.

Type:

Optional[PartialEmoji]

property flags[source]

Returns the role’s flags.

New in version 2.10.

Type:

RoleFlags

property created_at[source]

Returns the role’s creation time in UTC.

Type:

datetime.datetime

property mention[source]

Returns a string that allows you to mention a role.

Type:

str

property members[source]

Returns all the members with this role.

Type:

List[Member]

await edit(*, name=..., permissions=..., colour=..., color=..., hoist=..., icon=..., emoji=..., mentionable=..., position=..., reason=...)[source]

This function is a coroutine.

Edits the role.

You must have the manage_roles permission to use this.

All fields are optional.

Changed in version 1.4: Can now pass int to colour keyword-only parameter.

Changed in version 2.0: Edits are no longer in-place, the newly edited role is returned instead.

Changed in version 2.6: Raises TypeError or ValueError instead of InvalidArgument.

Parameters:

  • name (str) – The new role name to change to.

  • permissions (Permissions) – The new permissions to change to.

  • colour (Union[Colour, int]) – The new colour to change to. (aliased to color as well)

  • hoist (bool) – Indicates if the role should be shown separately in the member list.

  • icon (Optional[Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]]) –

    The role’s new icon image (if the guild has the ROLE_ICONS feature).

    Changed in version 2.5: Now accepts various resource types in addition to bytes.

  • emoji (Optional[str]) – The role’s new unicode emoji.

  • mentionable (bool) – Indicates if the role should be mentionable by others.

  • position (int) – The new role’s position. This must be below your top role’s position or it will fail.

  • reason (Optional[str]) – The reason for editing this role. Shows up on the audit log.

Raises:

  • NotFound – The icon asset couldn’t be found.

  • Forbidden – You do not have permissions to change the role.

  • HTTPException – Editing the role failed.

  • TypeError – The default role was asked to be moved or the icon asset is a lottie sticker (see Sticker.read())

  • ValueError – An invalid position was provided.

Returns:

The newly edited role.

Return type:

Role

await delete(*, reason=None)[source]

This function is a coroutine.

Deletes the role.

You must have the manage_roles permission to use this.

Parameters:

reason (Optional[str]) – The reason for deleting this role. Shows up on the audit log.

Raises:

RoleTags

Attributes
Methods
class disnake.RoleTags[source]

Represents tags on a role.

A role tag is a piece of extra information attached to a managed role that gives it context for the reason the role is managed.

While this can be accessed, a useful interface is also provided in the Role and Guild classes as well.

New in version 1.6.

bot_id

The bot’s user ID that manages this role.

Type:

Optional[int]

integration_id

The integration ID that manages the role.

Roles with this ID matching the guild’s guild_subscription integration are considered subscription roles.

Type:

Optional[int]

subscription_listing_id

The ID of this role’s subscription listing, if applicable.

New in version 2.9.

Type:

Optional[int]

is_bot_managed()[source]

Whether the role is associated with a bot.

Return type:

bool

is_integration()[source]

Whether the role is managed by an integration.

Return type:

bool

is_premium_subscriber()[source]

Whether the role is the premium subscriber, AKA “boost”, role for the guild.

Return type:

bool

is_linked_role()[source]

Whether the role is a linked role for the guild.

New in version 2.8.

Return type:

bool

is_available_for_purchase()[source]

Whether the role is a subscription role and available for purchase.

New in version 2.9.

Return type:

bool

is_subscription()[source]

Whether the role is associated with a role subscription.

New in version 2.9.

Return type:

bool

Data Classes

RoleFlags

Attributes
class disnake.RoleFlags[source]

Wraps up Discord Role flags.

x == y

Checks if two RoleFlags instances are equal.

x != y

Checks if two RoleFlags instances are not equal.

x <= y

Checks if an RoleFlags instance is a subset of another RoleFlags instance.

x >= y

Checks if an RoleFlags instance is a superset of another RoleFlags instance.

x < y

Checks if an RoleFlags instance is a strict subset of another RoleFlags instance.

x > y

Checks if an RoleFlags instance is a strict superset of another RoleFlags instance.

x | y, x |= y

Returns a new RoleFlags instance with all enabled flags from both x and y. (Using |= will update in place).

x & y, x &= y

Returns a new RoleFlags instance with only flags enabled on both x and y. (Using &= will update in place).

x ^ y, x ^= y

Returns a new RoleFlags instance with only flags enabled on one of x or y, but not both. (Using ^= will update in place).

~x

Returns a new RoleFlags 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.

RoleFlags.y | RoleFlags.z, RoleFlags(y=True) | RoleFlags.z

Returns a RoleFlags instance with all provided flags enabled.

~RoleFlags.y

Returns a RoleFlags instance with all flags except y inverted from their default value.

New in version 2.10.

value

The raw value. You should query flags via the properties rather than using this raw value.

Type:

int

in_prompt

Returns True if the role can be selected by members in an onboarding prompt.

Type:

bool

Events