Role

attrs class Role (DiscordObject)

Attr attributes:

Name	Type	Description
id	int	Discord unique snowflake ID

Source code in naff/models/discord/role.py

@define()
@total_ordering
class Role(DiscordObject):
    _sentinel = object()

    name: str = field(repr=True)
    color: "Color" = field(converter=Color)
    hoist: bool = field(default=False)
    position: int = field(repr=True)
    permissions: "Permissions" = field(converter=Permissions)
    managed: bool = field(default=False)
    mentionable: bool = field(default=True)
    premium_subscriber: bool = field(default=_sentinel, converter=partial(sentinel_converter, sentinel=_sentinel))
    _icon: Optional[Asset] = field(default=None)
    _unicode_emoji: Optional[PartialEmoji] = field(default=None, converter=optional_c(PartialEmoji.from_str))
    _guild_id: "Snowflake_Type" = field()
    _bot_id: Optional["Snowflake_Type"] = field(default=None)
    _integration_id: Optional["Snowflake_Type"] = field(default=None)  # todo integration object?

    def __lt__(self: "Role", other: "Role") -> bool:
        if not isinstance(self, Role) or not isinstance(other, Role):
            return NotImplemented

        if self._guild_id != other._guild_id:
            raise RuntimeError("Unable to compare Roles from different guilds.")

        if self.id == self._guild_id:  # everyone role
            # everyone role is on the bottom, so check if the other role is, well, not it
            # because then it must be higher than it
            return other.id != self.id

        if self.position < other.position:
            return True

        if self.position == other.position:
            # if two roles have the same position, which can happen thanks to discord, then
            # we can thankfully use their ids to determine which one is lower
            return self.id < other.id

        return False

    @classmethod
    def _process_dict(cls, data: Dict[str, Any], client: "Client") -> Dict[str, Any]:
        data.update(data.pop("tags", {}))

        if icon_hash := data.get("icon"):
            data["icon"] = Asset.from_path_hash(client, f"role-icons/{data['id']}/{{}}", icon_hash)

        return data

    async def fetch_bot(self) -> Optional["Member"]:
        """
        Fetch the bot associated with this role if any.

        Returns:
            Member object if any

        """
        if self._bot_id is None:
            return None
        return await self._client.cache.fetch_member(self._guild_id, self._bot_id)

    def get_bot(self) -> Optional["Member"]:
        """
        Get the bot associated with this role if any.

        Returns:
            Member object if any

        """
        if self._bot_id is None:
            return None
        return self._client.cache.get_member(self._guild_id, self._bot_id)

    @property
    def guild(self) -> "Guild":
        """The guild object this role is from."""
        return self._client.cache.get_guild(self._guild_id)

    @property
    def default(self) -> bool:
        """Is this the `@everyone` role."""
        return self.id == self._guild_id

    @property
    def bot_managed(self) -> bool:
        """Is this role owned/managed by a bot."""
        return self._bot_id is not None

    @property
    def mention(self) -> str:
        """Returns a string that would mention the role."""
        return f"<@&{self.id}>" if self.id != self._guild_id else "@everyone"

    @property
    def integration(self) -> bool:
        """Is this role owned/managed by an integration."""
        return self._integration_id is not None

    @property
    def members(self) -> list["Member"]:
        """List of members with this role"""
        return [member for member in self.guild.members if member.has_role(self)]

    @property
    def icon(self) -> Optional[Asset | PartialEmoji]:
        """
        The icon of this role

        Note:
            You have to use this method instead of the `_icon` attribute, because the first does account for unicode emojis
        """
        return self._icon or self._unicode_emoji

    @property
    def is_assignable(self) -> bool:
        """
        Can this role be assigned or removed by this bot?

        Note:
            This does not account for permissions, only the role hierarchy

        """
        return (self.default or self.guild.me.top_role > self) and not self.managed

    async def delete(self, reason: str = None) -> None:
        """
        Delete this role.

        Args:
            reason: An optional reason for this deletion

        """
        await self._client.http.delete_guild_role(self._guild_id, self.id, reason)

    async def edit(
        self,
        name: Absent[str] = MISSING,
        permissions: Absent[str] = MISSING,
        color: Absent[Union[int, Color]] = MISSING,
        hoist: Absent[bool] = MISSING,
        mentionable: Absent[bool] = MISSING,
    ) -> "Role":
        """
        Edit this role, all arguments are optional.

        Args:
            name: name of the role
            permissions: New permissions to use
            color: The color of the role
            hoist: whether the role should be displayed separately in the sidebar
            mentionable: whether the role should be mentionable

        Returns:
            Role with updated information

        """
        if isinstance(color, Color):
            color = color.value

        payload = dict_filter(
            {"name": name, "permissions": permissions, "color": color, "hoist": hoist, "mentionable": mentionable}
        )

        r_data = await self._client.http.modify_guild_role(self._guild_id, self.id, payload)
        r_data["guild_id"] = self._guild_id
        return self.from_dict(r_data, self._client)

inherited method update_from_dict(self, data)

Updates object attribute(s) with new json data received from discord api.

Parameters:

Name	Type	Description	Default
data		The json data received from discord api.	required

Returns:

Type	Description
~T	The updated object class instance.

Source code in naff/models/discord/role.py

def update_from_dict(self, data) -> T:
    data = self._process_dict(data, self._client)
    for key, value in self._filter_kwargs(data, self._get_keys()).items():
        # todo improve
        setattr(self, key, value)

    return self

inherited property readonly created_at: models.Timestamp

Returns a timestamp representing the date-time this discord object was created.

:Returns:

async method fetch_bot(self)

Fetch the bot associated with this role if any.

Returns:

Type	Description
Optional[Member]	Member object if any

Source code in naff/models/discord/role.py

async def fetch_bot(self) -> Optional["Member"]:
    """
    Fetch the bot associated with this role if any.

    Returns:
        Member object if any

    """
    if self._bot_id is None:
        return None
    return await self._client.cache.fetch_member(self._guild_id, self._bot_id)

method get_bot(self)

Get the bot associated with this role if any.

Returns:

Type	Description
Optional[Member]	Member object if any

Source code in naff/models/discord/role.py

def get_bot(self) -> Optional["Member"]:
    """
    Get the bot associated with this role if any.

    Returns:
        Member object if any

    """
    if self._bot_id is None:
        return None
    return self._client.cache.get_member(self._guild_id, self._bot_id)

inherited method to_dict(self)

Exports object into dictionary representation, ready to be sent to discord api.

Returns:

Type	Description
Dict[str, Any]	The exported dictionary.

Source code in naff/models/discord/role.py

def to_dict(self) -> Dict[str, Any]:
    """
    Exports object into dictionary representation, ready to be sent to discord api.

    Returns:
        The exported dictionary.

    """
    self._check_object()
    return serializer.to_dict(self)

property readonly guild: Guild

The guild object this role is from.

property readonly default: bool

Is this the @everyone role.

property readonly bot_managed: bool

Is this role owned/managed by a bot.

property readonly mention: str

Returns a string that would mention the role.

property readonly integration: bool

Is this role owned/managed by an integration.

property readonly members: list

List of members with this role

property readonly icon: Union[naff.models.discord.asset.Asset, naff.models.discord.emoji.PartialEmoji]

The icon of this role

Note

You have to use this method instead of the _icon attribute, because the first does account for unicode emojis

property readonly is_assignable: bool

Can this role be assigned or removed by this bot?

Note

This does not account for permissions, only the role hierarchy

async method delete(self, reason)

Delete this role.

Parameters:

Name	Type	Description	Default
reason	str	An optional reason for this deletion	None

Source code in naff/models/discord/role.py

async def delete(self, reason: str = None) -> None:
    """
    Delete this role.

    Args:
        reason: An optional reason for this deletion

    """
    await self._client.http.delete_guild_role(self._guild_id, self.id, reason)

async method edit(self, name, permissions, color, hoist, mentionable)

Edit this role, all arguments are optional.

Parameters:

Name	Type	Description	Default
name	Union[str, naff.client.const.Missing]	name of the role	Missing
permissions	Union[str, naff.client.const.Missing]	New permissions to use	Missing
color	Union[int, naff.models.discord.color.Color, naff.client.const.Missing]	The color of the role	Missing
hoist	Union[bool, naff.client.const.Missing]	whether the role should be displayed separately in the sidebar	Missing
mentionable	Union[bool, naff.client.const.Missing]	whether the role should be mentionable	Missing

Returns:

Type	Description
Role	Role with updated information

Source code in naff/models/discord/role.py

async def edit(
    self,
    name: Absent[str] = MISSING,
    permissions: Absent[str] = MISSING,
    color: Absent[Union[int, Color]] = MISSING,
    hoist: Absent[bool] = MISSING,
    mentionable: Absent[bool] = MISSING,
) -> "Role":
    """
    Edit this role, all arguments are optional.

    Args:
        name: name of the role
        permissions: New permissions to use
        color: The color of the role
        hoist: whether the role should be displayed separately in the sidebar
        mentionable: whether the role should be mentionable

    Returns:
        Role with updated information

    """
    if isinstance(color, Color):
        color = color.value

    payload = dict_filter(
        {"name": name, "permissions": permissions, "color": color, "hoist": hoist, "mentionable": mentionable}
    )

    r_data = await self._client.http.modify_guild_role(self._guild_id, self.id, payload)
    r_data["guild_id"] = self._guild_id
    return self.from_dict(r_data, self._client)