Role

Represents a Discord guild's role.

Attributes

color : Color

The role's color. If the color equals to Color(0), then it is ignored meanwhile calculating towards a user's display color.

flags : RoleFlag

The role flags.

guild_id : int

The role's guild's identifier.

icon_hash : int

The guild's icon's hash in uint128.

Mutually exclusive with .unicode_emoji

icon_type : IconType

The guild's icon's type.

Mutually exclusive with .unicode_emoji

id : int

The unique identifier number of the role.

manager_metadata : RoleManagerMetadataBase

If the role is managed, then it's manager's metadata.

manager_type : RoleManagerType

If the role is managed, defines by what it is.

mentionable : bool

Whether the role can be mentioned.

name : str

The name of the role. Can be empty string, if the role has no known name.

permissions : Permission

The permissions of the users having the role.

position : int

The role's position.

separated : bool

Users show up in separated groups by their highest separated role.

unicode_emoji : None, Emoji

Unicode emoji icon of the role.

Mutually exclusive with .icon_hash and .icon_type.

Properties

created_at

When the entity was created.

Returns

created_at : datetime

guild

Returns the role's guild.

Returns

guild : None, Guild

icon

Returns the respective icon.

Returns

icon : Icon

icon_url

Returns the role's icon's image's url. If the role has no icon, then returns None.

This function is a shared property of Role-s.

Returns

url : None, str

managed

Returns whether the role is managed.

Returns

managed: bool

manager

Returns the entity's identifier to which the role is managed by.

Returns

manager : None, ClientUserBase, Integration

manager_id

Returns the entity's identifier to which the role is managed by.

Returns

manager_id : int

mention

The role's mention.

Returns

mention : str

partial

Returns whether the role is partial.

Partial roles have .guild set as None.

Returns

partial : bool

users

Returns the users who have the role.

Returns

users : list of ClientUserBase

Methods

new(...)

Creates a new partial role from the given fields.

Parameter	Type	Description
color	`int`, `Color`	The role's color.
flags	`RoleFlag`, `int`	The role's flags.
icon	`None`, `Icon`, `str`, `bytes-like`	The role's icon. Mutually exclusive with the `unicode_emoji` parameter.
manager	`None`, `tuple`(`RoleManagerType`, `RoleManagerMetadataBase`)	The role's manager.
mentionable	`bool`	Whether the role can be mentioned.
name	`str`	The role's name.
permissions	`int`, `Permission`	The permissions of the users having the role.
position	`int`	The role's position.
separated	`bool`	Users show up in separated groups by their highest `separated` role.
unicode_emoji	`None`, `Emoji`	The role's icon as an unicode emoji. Mutually exclusive with the `icon` parameter.

Returns

self : instance<cls>

Raises

TypeError

Value of invalid type given.

ValueError

Value of invalid value given.
icon and unicode_emoji are mutually exclusive.

copy()

Copies the role returning a new partial one.

Returns

new : instance<cls>

copy_with(...)

Copies the role with modifying its defined fields, returning a new partial one.

Parameter	Type	Description
color	`Color`, `int`	The role's color.
flags	`RoleFlag`, `int`	The role's flags.
icon	`None`, `Icon`, `str`, `bytes-like`	The role's icon. Mutually exclusive with the `unicode_emoji` parameter.
manager	`None`, `tuple`(`RoleManagerType`, `RoleManagerMetadataBase`)	The role's manager.
mentionable	`bool`	Whether the role can be mentioned.
name	`str`	The role's name.
permissions	`int`, `Permission`	The permissions of the users having the role.
position	`int`	The role's position.
separated	`bool`	Users show up in separated groups by their highest `separated` role.
unicode_emoji	`None`, `Emoji`	The role's icon as an unicode emoji. Mutually exclusive with the `icon` parameter.

Returns

new : instance<type<self>>

Raises

TypeError

Value of invalid type given.

ValueError

Value of invalid value given.
icon and unicode_emoji are mutually exclusive.

from_data(data, ...)

Creates a role from the given data at the given guild. If the role already exists and is not partial, then returns it. However it is partial, then updates it as well.

Parameter	Type	Default	Description
data	`dict` of (`str`, `object`) items		Role data received from Discord.
guild_id	`int`	`0`	The owner guild's identifier.
strong_cache	`bool`	`True`	Whether the instance should be put into its strong cache.

Returns

role : Role

icon_url_as(...)

Returns the role's icon's image's url. If the role has no icon, then returns None.

This function is a shared method of Role-s.

Parameter	Type	Optional	Default	Description
ext	`None`, `str`		`None`	The extension of the image's url. Can be any of: `'jpg'`, `'jpeg'`, `'png'`, `'webp'`, `'gif'`.
size	`None`, `int`		`None`	The preferred minimal size of the image's url.

Returns

url : None, str

Raises

ValueError

If ext, size was not passed as any of the expected values.

is_default()

Returns whether the role is the default role at it's respective guild.

Returns

is_default : bool

precreate(role_id, ...)

Precreates a role by creating a partial one with the given parameters. When the role is loaded, then the precreated one will be picked up. However if the role is precreated when it already exists, then the existing one is picked up and is updated by the given parameters only if it is partial.

Parameter	Type	Description
role_id	`int`, `str`	The role's id.
guild_id	`int`, `Guild`	The role's guild or its identifier.
**keyword_parameters	keyword parameters	Additional predefined attributes for the role.
color	`Color`, `int`	The role's color.
flags	`RoleFlag`, `int`	The role's flags.
icon	`None`, `Icon`, `str`	The role's icon. Mutually exclusive with the `unicode_emoji` parameter.
manager	`None`, `tuple`(`RoleManagerType`, `RoleManagerMetadataBase`)	The role's manager.
manager_metadata	`None`, `RoleManagerMetadataBase`	The role's manager's metadata.
manager_type	`RoleManagerType`	TIf the role is managed, defines by what it is.
mentionable	`bool`	Whether the role can be mentioned.
name	`str`	The name of the role.
separated	`bool`	Users show up in separated groups by their highest `separated` role.
permissions	`int`, `Permission`	The permissions of the users having the role.
position	`int`	The permissions of the users having the role.
unicode_emoji	`None`, `Emoji`	The role's icon as an unicode emoji. Mutually exclusive with the `icon`, `icon_type` and `icon_hash` parameters.

Returns

role : Role

Raises

TypeError

If any parameter's type is bad or if unexpected parameter is passed.

ValueError

If an parameter's type is good, but it's value is unacceptable.

to_data(...)

Converts the role into a json serializable object.

Parameter	Type	Optional	Keyword only	Default	Description
defaults	`bool`			`False`	Whether default field values should be included.
include_internals	`bool`			`False`	Whether internal fields should be included.

Returns

data : dict of (str, object) items

_clear_cache_permission()

Clears the role's guild's permission cache.

_create_empty(role_id, guild_id)

Creates an empty role with the given identifier.

Parameter	Type	Description
role_id	`int`	The role's identifier.
guild_id	`int`	The role's guild's identifier.

Returns

self : Role

The created role.

_delete()

Removes the role's references.

Called when the role is deleted.

_difference_update_attributes(data)

Updates the role with the given data and returns it's overwritten attributes as a dict with a attribute-name- old-value relation.

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	Role data received from Discord.

Returns

old_attributes : dict of (str, object) items

All item in the returned dict is optional.

Returned Data Structure

Keys	Values
color	`Color`
flags	`RoleFlag`
icon	`Icon`
managed	`bool`
mentionable	`bool`
name	`str`
permissions	`Permission`
position	`int`
separated	`bool`
unicode_emoji	`None`, `Emoji`

_get_hash_partial()

Returns the role's hash value. This function is called when the role is partial.

Returns

hash_value : int

_is_equal_partial(other)

Returns whether the role is equal to the given one. This function is called when one or both the roles are partial.

Parameter	Type	Description
other	`instance<type<self>>`	The other role to compare self to.

Returns

is_equal : bool

_set_attributes(data)

Sets the role's attributes from the given data.

.id and .guild_id fields should be already set,

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	Received role data.

_update_attributes(data)

Updates the role with the given data with overwriting it's old attributes.

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	Role data received from Discord.

eq()

Returns whether the two roles are equal.

format(code)

Formats the role in a format string.

Parameter	Type	Description
code	`str`	The option on based the result will be formatted.

Returns

role : str

Examples

>>>> from hata import Role, now_as_id
>>>> role = Role.precreate(now_as_id(), name = 'admiral-general')
>>>> role
<Role name = 'admiral-general', id = 725333995067277312>
>>>> # no code stands for `role.name`.
>>>> f'{role}'
'admiral-general'
>>>> # 'm' stands for mention.
>>>> f'{role:m}'
'<@&725333995067277312>'
>>>> # 'c' stands for created at.
>>>> f'{role:c}'
'2020.06.24-12:58:20'

ge()

Returns whether this role's position is higher or equal to the other's.

getattr()

Drops a rich attribute error.

gt()

Returns whether this role's position is higher than the other's.

hash()

Returns the role's hash value.

le()

Returns whether this role's position is less or equal to the other's.

lt()

Returns whether this role's position is less than the other's.

ne()

Returns whether the two roles are equal.

repr()

Returns the role's representation.

Role

Attributes

Properties

created_at

Returns

guild

Returns

icon

Returns

icon_url

Returns

managed

Returns

manager

Returns

manager_id

Returns

mention

Returns

partial

Returns

users

Returns

Methods

__new__(...)

Returns

Raises

copy()

Returns

copy_with(...)

Returns

Raises

from_data(data, ...)

Returns

icon_url_as(...)

Returns

Raises

is_default()

Returns

precreate(role_id, ...)

Returns

Raises

to_data(...)

Returns

_clear_cache_permission()

_create_empty(role_id, guild_id)

Returns

_delete()

_difference_update_attributes(data)

Returns

Returned Data Structure

_get_hash_partial()

Returns

_is_equal_partial(other)

Returns

_set_attributes(data)

_update_attributes(data)

__eq__()

__format__(code)

Returns

Examples

__ge__()

__getattr__()

__gt__()

__hash__()

__le__()

__lt__()

__ne__()

__repr__()

new(...)

eq()

format(code)

ge()

getattr()

gt()

hash()

le()

lt()

ne()

repr()