hikari.permissions

Bitfield of permissions.

View Source

# -*- coding: utf-8 -*-
# cython: language_level=3
# Copyright (c) 2020 Nekokatt
# Copyright (c) 2021-present davfsa
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
"""Bitfield of permissions."""

from __future__ import annotations

__all__: typing.Sequence[str] = ("Permissions",)

import functools
import operator
import typing

from hikari.internal import enums


@typing.final
class Permissions(enums.Flag):
    """Represents the permissions available in a given channel or guild.

    This enum is an `enum.IntFlag`. This means that you can **combine multiple
    permissions together** into one value using the bitwise-OR operator (`|`).

        my_perms = Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD

        your_perms = (
            Permissions.CREATE_INSTANT_INVITE
            | Permissions.KICK_MEMBERS
            | Permissions.BAN_MEMBERS
            | Permissions.MANAGE_GUILD
        )

    You can **check if a permission is present** in a set of combined
    permissions by using the bitwise-AND operator (`&`). This will return
    the int-value of the permission if it is present, or `0` if not present.

        my_perms = Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD

        if my_perms & Permissions.MANAGE_CHANNELS:
            if my_perms & Permissions.MANAGE_GUILD:
                print("I have the permission to both manage the guild and the channels in it!")
            else:
                print("I have the permission to manage channels!")
        else:
            print("I don't have the permission to manage channels!")

        # Or you could simplify it:

        if my_perms & (Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD):
            print("I have the permission to both manage the guild and the channels in it!")
        elif my_perms & Permissions.MANAGE_CHANNELS:
            print("I have the permission to manage channels!")
        else:
            print("I don't have the permission to manage channels!")

    If you need to **check that a permission is not present**, you can use the
    bitwise-XOR operator (`^`) to check. If the permission is not present, it
    will return a non-zero value, otherwise if it is present, it will return `0`.

        my_perms = Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD

        if my_perms ^ Permissions.MANAGE_CHANNELS:
            print("Please give me the MANAGE_CHANNELS permission!")

    Lastly, if you need all the permissions set except the permission you want,
    you can use the inversion operator (`~`) to do that.

        # All permissions except ADMINISTRATOR.
        my_perms = ~Permissions.ADMINISTRATOR

    """

    NONE = 0
    """Empty permission."""

    CREATE_INSTANT_INVITE = 1 << 0
    """Allows creation of instant invites."""

    KICK_MEMBERS = 1 << 1
    """Allows kicking members.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    BAN_MEMBERS = 1 << 2
    """Allows banning members.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    ADMINISTRATOR = 1 << 3
    """Allows all permissions and bypasses channel permission overwrites.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    MANAGE_CHANNELS = 1 << 4
    """Allows management and editing of channels.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    MANAGE_GUILD = 1 << 5
    """Allows management and editing of the guild.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    ADD_REACTIONS = 1 << 6
    """Allows for the addition of reactions to messages."""

    VIEW_AUDIT_LOG = 1 << 7
    """Allows for viewing of audit logs."""

    PRIORITY_SPEAKER = 1 << 8
    """Allows for using priority speaker in a voice channel."""

    STREAM = 1 << 9
    """Allows the user to go live."""

    VIEW_CHANNEL = 1 << 10
    """Allows guild members to view a channel, which includes reading messages in text channels."""

    SEND_MESSAGES = 1 << 11
    """Allows for sending messages in a channel."""

    SEND_TTS_MESSAGES = 1 << 12
    """Allows for sending of `/tts` messages."""

    MANAGE_MESSAGES = 1 << 13
    """Allows for deletion of other users messages.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    EMBED_LINKS = 1 << 14
    """Links sent by users with this permission will be auto-embedded."""

    ATTACH_FILES = 1 << 15
    """Allows for uploading images and files."""

    READ_MESSAGE_HISTORY = 1 << 16
    """Allows for reading of message history."""

    MENTION_ROLES = 1 << 17
    """Allows for using the `@everyone` tag to notify all users in a channel,
    and the `@here` tag to notify all online users in a channel, and the
    `@role` tag (even if the role is not mentionable) to notify all users with
    that role in a channel.
    """

    USE_EXTERNAL_EMOJIS = 1 << 18
    """Allows the usage of custom emojis from other guilds."""

    VIEW_GUILD_INSIGHTS = 1 << 19
    """Allows the user to view guild insights for eligible guilds."""

    CONNECT = 1 << 20
    """Allows for joining of a voice channel."""

    SPEAK = 1 << 21
    """Allows for speaking in a voice channel."""

    MUTE_MEMBERS = 1 << 22
    """Allows for muting members in a voice channel."""

    DEAFEN_MEMBERS = 1 << 23
    """Allows for deafening of members in a voice channel."""

    MOVE_MEMBERS = 1 << 24
    """Allows for moving of members between voice channels."""

    USE_VOICE_ACTIVITY = 1 << 25
    """Allows for using voice-activity-detection in a voice channel."""

    CHANGE_NICKNAME = 1 << 26
    """Allows for modification of own nickname."""

    MANAGE_NICKNAMES = 1 << 27
    """Allows for modification of other users nicknames."""

    MANAGE_ROLES = 1 << 28
    """Allows management and editing of roles.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    MANAGE_WEBHOOKS = 1 << 29
    """Allows management and editing of webhooks.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    MANAGE_EMOJIS_AND_STICKERS = 1 << 30
    """Allows management and editing of emojis and stickers.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    USE_APPLICATION_COMMANDS = 1 << 31
    """Allows for using the application commands of guild integrations within a text channel."""

    REQUEST_TO_SPEAK = 1 << 32
    """Allows for requesting to speak in stage channels.

    .. warning::
        This permissions is currently defined as being "under active
        development" by Discord meaning that "it may be changed or removed"
        without warning.
    """

    MANAGE_THREADS = 1 << 34
    """Allows for deleting and archiving threads, and viewing all private threads.

     .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    CREATE_PUBLIC_THREADS = 1 << 35
    """Allows for creating threads."""

    CREATE_PRIVATE_THREADS = 1 << 36
    """Allows for creating private threads."""

    USE_EXTERNAL_STICKERS = 1 << 37
    """Allows the usage of custom stickers from other servers."""

    SEND_MESSAGES_IN_THREADS = 1 << 38
    """Allows for sending messages in threads."""

    START_EMBEDDED_ACTIVITIES = 1 << 39
    """Allows for launching activities (applications with the `EMBEDDED` flag) in a voice channel."""

    MODERATE_MEMBERS = 1 << 40
    """Allows for timing out members."""

    @classmethod
    def all_permissions(cls) -> Permissions:
        """Get an instance of `Permissions` with all the known permissions.

        Returns
        -------
        Permissions
            A permissions instance with all the known permissions.
        """
        return functools.reduce(operator.ior, Permissions)

@typing.final

class Permissions(builtins.int, hikari.internal.enums.Flag):

View Source

@typing.final
class Permissions(enums.Flag):
    """Represents the permissions available in a given channel or guild.

    This enum is an `enum.IntFlag`. This means that you can **combine multiple
    permissions together** into one value using the bitwise-OR operator (`|`).

        my_perms = Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD

        your_perms = (
            Permissions.CREATE_INSTANT_INVITE
            | Permissions.KICK_MEMBERS
            | Permissions.BAN_MEMBERS
            | Permissions.MANAGE_GUILD
        )

    You can **check if a permission is present** in a set of combined
    permissions by using the bitwise-AND operator (`&`). This will return
    the int-value of the permission if it is present, or `0` if not present.

        my_perms = Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD

        if my_perms & Permissions.MANAGE_CHANNELS:
            if my_perms & Permissions.MANAGE_GUILD:
                print("I have the permission to both manage the guild and the channels in it!")
            else:
                print("I have the permission to manage channels!")
        else:
            print("I don't have the permission to manage channels!")

        # Or you could simplify it:

        if my_perms & (Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD):
            print("I have the permission to both manage the guild and the channels in it!")
        elif my_perms & Permissions.MANAGE_CHANNELS:
            print("I have the permission to manage channels!")
        else:
            print("I don't have the permission to manage channels!")

    If you need to **check that a permission is not present**, you can use the
    bitwise-XOR operator (`^`) to check. If the permission is not present, it
    will return a non-zero value, otherwise if it is present, it will return `0`.

        my_perms = Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD

        if my_perms ^ Permissions.MANAGE_CHANNELS:
            print("Please give me the MANAGE_CHANNELS permission!")

    Lastly, if you need all the permissions set except the permission you want,
    you can use the inversion operator (`~`) to do that.

        # All permissions except ADMINISTRATOR.
        my_perms = ~Permissions.ADMINISTRATOR

    """

    NONE = 0
    """Empty permission."""

    CREATE_INSTANT_INVITE = 1 << 0
    """Allows creation of instant invites."""

    KICK_MEMBERS = 1 << 1
    """Allows kicking members.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    BAN_MEMBERS = 1 << 2
    """Allows banning members.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    ADMINISTRATOR = 1 << 3
    """Allows all permissions and bypasses channel permission overwrites.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    MANAGE_CHANNELS = 1 << 4
    """Allows management and editing of channels.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    MANAGE_GUILD = 1 << 5
    """Allows management and editing of the guild.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    ADD_REACTIONS = 1 << 6
    """Allows for the addition of reactions to messages."""

    VIEW_AUDIT_LOG = 1 << 7
    """Allows for viewing of audit logs."""

    PRIORITY_SPEAKER = 1 << 8
    """Allows for using priority speaker in a voice channel."""

    STREAM = 1 << 9
    """Allows the user to go live."""

    VIEW_CHANNEL = 1 << 10
    """Allows guild members to view a channel, which includes reading messages in text channels."""

    SEND_MESSAGES = 1 << 11
    """Allows for sending messages in a channel."""

    SEND_TTS_MESSAGES = 1 << 12
    """Allows for sending of `/tts` messages."""

    MANAGE_MESSAGES = 1 << 13
    """Allows for deletion of other users messages.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    EMBED_LINKS = 1 << 14
    """Links sent by users with this permission will be auto-embedded."""

    ATTACH_FILES = 1 << 15
    """Allows for uploading images and files."""

    READ_MESSAGE_HISTORY = 1 << 16
    """Allows for reading of message history."""

    MENTION_ROLES = 1 << 17
    """Allows for using the `@everyone` tag to notify all users in a channel,
    and the `@here` tag to notify all online users in a channel, and the
    `@role` tag (even if the role is not mentionable) to notify all users with
    that role in a channel.
    """

    USE_EXTERNAL_EMOJIS = 1 << 18
    """Allows the usage of custom emojis from other guilds."""

    VIEW_GUILD_INSIGHTS = 1 << 19
    """Allows the user to view guild insights for eligible guilds."""

    CONNECT = 1 << 20
    """Allows for joining of a voice channel."""

    SPEAK = 1 << 21
    """Allows for speaking in a voice channel."""

    MUTE_MEMBERS = 1 << 22
    """Allows for muting members in a voice channel."""

    DEAFEN_MEMBERS = 1 << 23
    """Allows for deafening of members in a voice channel."""

    MOVE_MEMBERS = 1 << 24
    """Allows for moving of members between voice channels."""

    USE_VOICE_ACTIVITY = 1 << 25
    """Allows for using voice-activity-detection in a voice channel."""

    CHANGE_NICKNAME = 1 << 26
    """Allows for modification of own nickname."""

    MANAGE_NICKNAMES = 1 << 27
    """Allows for modification of other users nicknames."""

    MANAGE_ROLES = 1 << 28
    """Allows management and editing of roles.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    MANAGE_WEBHOOKS = 1 << 29
    """Allows management and editing of webhooks.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    MANAGE_EMOJIS_AND_STICKERS = 1 << 30
    """Allows management and editing of emojis and stickers.

    .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    USE_APPLICATION_COMMANDS = 1 << 31
    """Allows for using the application commands of guild integrations within a text channel."""

    REQUEST_TO_SPEAK = 1 << 32
    """Allows for requesting to speak in stage channels.

    .. warning::
        This permissions is currently defined as being "under active
        development" by Discord meaning that "it may be changed or removed"
        without warning.
    """

    MANAGE_THREADS = 1 << 34
    """Allows for deleting and archiving threads, and viewing all private threads.

     .. note::
        In guilds with server-wide 2FA enabled this permission can only be used
        by users who have two-factor authentication enabled on their account
        (or their owner's account in the case of bot users) and the guild owner.
    """

    CREATE_PUBLIC_THREADS = 1 << 35
    """Allows for creating threads."""

    CREATE_PRIVATE_THREADS = 1 << 36
    """Allows for creating private threads."""

    USE_EXTERNAL_STICKERS = 1 << 37
    """Allows the usage of custom stickers from other servers."""

    SEND_MESSAGES_IN_THREADS = 1 << 38
    """Allows for sending messages in threads."""

    START_EMBEDDED_ACTIVITIES = 1 << 39
    """Allows for launching activities (applications with the `EMBEDDED` flag) in a voice channel."""

    MODERATE_MEMBERS = 1 << 40
    """Allows for timing out members."""

    @classmethod
    def all_permissions(cls) -> Permissions:
        """Get an instance of `Permissions` with all the known permissions.

        Returns
        -------
        Permissions
            A permissions instance with all the known permissions.
        """
        return functools.reduce(operator.ior, Permissions)

Represents the permissions available in a given channel or guild.

This enum is an enum.IntFlag. This means that you can combine multiple permissions together into one value using the bitwise-OR operator (|).

my_perms = Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD

your_perms = (
    Permissions.CREATE_INSTANT_INVITE
    | Permissions.KICK_MEMBERS
    | Permissions.BAN_MEMBERS
    | Permissions.MANAGE_GUILD
)

You can check if a permission is present in a set of combined permissions by using the bitwise-AND operator (&). This will return the int-value of the permission if it is present, or 0 if not present.

my_perms = Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD

if my_perms & Permissions.MANAGE_CHANNELS:
    if my_perms & Permissions.MANAGE_GUILD:
        print("I have the permission to both manage the guild and the channels in it!")
    else:
        print("I have the permission to manage channels!")
else:
    print("I don't have the permission to manage channels!")

# Or you could simplify it:

if my_perms & (Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD):
    print("I have the permission to both manage the guild and the channels in it!")
elif my_perms & Permissions.MANAGE_CHANNELS:
    print("I have the permission to manage channels!")
else:
    print("I don't have the permission to manage channels!")

If you need to check that a permission is not present, you can use the bitwise-XOR operator (^) to check. If the permission is not present, it will return a non-zero value, otherwise if it is present, it will return 0.

my_perms = Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD

if my_perms ^ Permissions.MANAGE_CHANNELS:
    print("Please give me the MANAGE_CHANNELS permission!")

Lastly, if you need all the permissions set except the permission you want, you can use the inversion operator (~) to do that.

# All permissions except ADMINISTRATOR.
my_perms = ~Permissions.ADMINISTRATOR

Variables and properties

# ADD_REACTIONS

Allows for the addition of reactions to messages.

# ADMINISTRATOR

Allows all permissions and bypasses channel permission overwrites.

Note: In guilds with server-wide 2FA enabled this permission can only be used by users who have two-factor authentication enabled on their account (or their owner's account in the case of bot users) and the guild owner.

# ATTACH_FILES

Allows for uploading images and files.

# BAN_MEMBERS

Allows banning members.

# CHANGE_NICKNAME

Allows for modification of own nickname.

# CONNECT

Allows for joining of a voice channel.

# CREATE_INSTANT_INVITE

Allows creation of instant invites.

# CREATE_PRIVATE_THREADS

Allows for creating private threads.

# CREATE_PUBLIC_THREADS

Allows for creating threads.

# DEAFEN_MEMBERS

Allows for deafening of members in a voice channel.

# EMBED_LINKS

Links sent by users with this permission will be auto-embedded.

# KICK_MEMBERS

Allows kicking members.

# MANAGE_CHANNELS

Allows management and editing of channels.

# MANAGE_EMOJIS_AND_STICKERS

Allows management and editing of emojis and stickers.

# MANAGE_GUILD

Allows management and editing of the guild.

# MANAGE_MESSAGES

Allows for deletion of other users messages.

# MANAGE_NICKNAMES

Allows for modification of other users nicknames.

# MANAGE_ROLES

Allows management and editing of roles.

# MANAGE_THREADS

Allows for deleting and archiving threads, and viewing all private threads.

# MANAGE_WEBHOOKS

Allows management and editing of webhooks.

# MENTION_ROLES

Allows for using the @everyone tag to notify all users in a channel, and the @here tag to notify all online users in a channel, and the @role tag (even if the role is not mentionable) to notify all users with that role in a channel.

# MODERATE_MEMBERS

Allows for timing out members.

# MOVE_MEMBERS

Allows for moving of members between voice channels.

# MUTE_MEMBERS

Allows for muting members in a voice channel.

# NONE

Empty permission.

# PRIORITY_SPEAKER

Allows for using priority speaker in a voice channel.

# READ_MESSAGE_HISTORY

Allows for reading of message history.

# REQUEST_TO_SPEAK

Allows for requesting to speak in stage channels.

Warning: This permissions is currently defined as being "under active development" by Discord meaning that "it may be changed or removed" without warning.

# SEND_MESSAGES

Allows for sending messages in a channel.

# SEND_MESSAGES_IN_THREADS

Allows for sending messages in threads.

# SEND_TTS_MESSAGES

Allows for sending of /tts messages.

# SPEAK

Allows for speaking in a voice channel.

# START_EMBEDDED_ACTIVITIES

Allows for launching activities (applications with the EMBEDDED flag) in a voice channel.

# STREAM

Allows the user to go live.

# USE_APPLICATION_COMMANDS

Allows for using the application commands of guild integrations within a text channel.

# USE_EXTERNAL_EMOJIS

Allows the usage of custom emojis from other guilds.

# USE_EXTERNAL_STICKERS

Allows the usage of custom stickers from other servers.

# USE_VOICE_ACTIVITY

Allows for using voice-activity-detection in a voice channel.

# VIEW_AUDIT_LOG

Allows for viewing of audit logs.

# VIEW_CHANNEL

Allows guild members to view a channel, which includes reading messages in text channels.

# VIEW_GUILD_INSIGHTS

Allows the user to view guild insights for eligible guilds.

# denominator

the denominator of a rational number in lowest terms

# imag

the imaginary part of a complex number

# name: str

Return the name of the flag combination as a str.

# numerator

the numerator of a rational number in lowest terms

# real

the real part of a complex number

# value: int

Return the int value of the flag.

Methods

# def __init__(cls, value: int = 0):

View Source

    def __call__(cls, value: int = 0) -> typing.Any:
        """Cast a value to the flag enum, returning the raw value that was passed if values not found."""
        # We want to handle value invariantly to avoid issues brought in by different behaviours from sub-classed ints
        # and floats. This also ensures that .__int__ only returns an invariant int.
        value = int(value)
        try:
            return cls._value_to_member_map_[value]
        except KeyError:
            # We only need this ability here usually, so overloading operators
            # is an overkill and would add more overhead.

            if value < 0:
                # Convert to a positive value instead.
                return cls.__everything__ - ~value

            temp_members = cls._temp_members_
            # For huge enums, don't ever cache anything. We could consume masses of memory otherwise
            # (e.g. Permissions)
            try:
                # Try to get a cached value.
                return temp_members[value]
            except KeyError:
                # If we can't find the value, just return what got casted in by generating a pseudomember
                # and caching it. We can't use weakref because int is not weak referenceable, annoyingly.
                pseudomember = cls.__new__(cls, value)
                pseudomember._name_ = None
                pseudomember._value_ = value
                temp_members[value] = pseudomember
                if len(temp_members) > _MAX_CACHED_MEMBERS:
                    temp_members.popitem()

                return pseudomember

Cast a value to the flag enum, returning the raw value that was passed if values not found.

# def all(self: ~_T, *flags: ~_T) -> bool:

View Source

    def all(self: _T, *flags: _T) -> bool:
        """Check if all of the given flags are part of this value.

        Returns
        -------
        bool
            `True` if any of the given flags are part of this value.
            Otherwise, return `False`.
        """
        return all((flag & self) == flag for flag in flags)

Check if all of the given flags are part of this value.

Returns

bool: True if any of the given flags are part of this value. Otherwise, return False.

@classmethod

def all_permissions(cls) -> hikari.permissions.Permissions:

View Source

    @classmethod
    def all_permissions(cls) -> Permissions:
        """Get an instance of `Permissions` with all the known permissions.

        Returns
        -------
        Permissions
            A permissions instance with all the known permissions.
        """
        return functools.reduce(operator.ior, Permissions)

Get an instance of Permissions with all the known permissions.

Returns

Permissions: A permissions instance with all the known permissions.

# def any(self: ~_T, *flags: ~_T) -> bool:

View Source

    def any(self: _T, *flags: _T) -> bool:
        """Check if any of the given flags are part of this value.

        Returns
        -------
        bool
            `True` if any of the given flags are part of this value.
            Otherwise, return `False`.
        """
        return any((flag & self) == flag for flag in flags)

Check if any of the given flags are part of this value.

Returns

bool: True if any of the given flags are part of this value. Otherwise, return False.

# def as_integer_ratio(self, /):

Return integer ratio.

Return a pair of integers, whose ratio is exactly equal to the original int and with a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)

# def bit_length(self, /):

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6

# def conjugate(unknown):

Returns self, the complex conjugate of any int.

# def difference(self: ~_T, other: Union[~_T, int]) -> ~_T:

View Source

    def difference(self: _T, other: typing.Union[_T, int]) -> _T:
        """Perform a set difference with the other set.

        This will return all flags in this set that are not in the other value.

        Equivalent to using the subtraction `-` operator.
        """
        return self.__class__(self & ~int(other))

Perform a set difference with the other set.

This will return all flags in this set that are not in the other value.

Equivalent to using the subtraction - operator.

# def from_bytes(type, /, bytes, byteorder, *, signed=False):

Return the integer represented by the given array of bytes.

bytes Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol. byteorder The byte order used to represent the integer. If byteorder is 'big', the most significant byte is at the beginning of the byte array. If byteorder is 'little', the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder' as the byte order value. signed Indicates whether two's complement is used to represent the integer.

# def intersection(self: ~_T, other: Union[~_T, int]) -> ~_T:

View Source

    def intersection(self: _T, other: typing.Union[_T, int]) -> _T:
        """Return a combination of flags that are set for both given values.

        Equivalent to using the "AND" `&` operator.
        """
        return self.__class__(self._value_ & int(other))

Return a combination of flags that are set for both given values.

Equivalent to using the "AND" & operator.

# def invert(self: ~_T) -> ~_T:

View Source

    def invert(self: _T) -> _T:
        """Return a set of all flags not in the current set."""
        return self.__class__(self.__class__.__everything__._value_ & ~self._value_)

Return a set of all flags not in the current set.

# def is_disjoint(self: ~_T, other: Union[~_T, int]) -> bool:

View Source

    def is_disjoint(self: _T, other: typing.Union[_T, int]) -> bool:
        """Return whether two sets have a intersection or not.

        If the two sets have an intersection, then this returns
        `False`. If no common flag values exist between them, then
        this returns `True`.
        """
        return not (self & other)

Return whether two sets have a intersection or not.

If the two sets have an intersection, then this returns False. If no common flag values exist between them, then this returns True.

# def is_subset(self: ~_T, other: Union[~_T, int]) -> bool:

View Source

    def is_subset(self: _T, other: typing.Union[_T, int]) -> bool:
        """Return whether another set contains this set or not.

        Equivalent to using the "in" operator.
        """
        return (self & other) == other

Return whether another set contains this set or not.

Equivalent to using the "in" operator.

# def is_superset(self: ~_T, other: Union[~_T, int]) -> bool:

View Source

    def is_superset(self: _T, other: typing.Union[_T, int]) -> bool:
        """Return whether this set contains another set or not."""
        return (self & other) == self

Return whether this set contains another set or not.

# def isdisjoint(self: ~_T, other: Union[~_T, int]) -> bool:

View Source

    def is_disjoint(self: _T, other: typing.Union[_T, int]) -> bool:
        """Return whether two sets have a intersection or not.

        If the two sets have an intersection, then this returns
        `False`. If no common flag values exist between them, then
        this returns `True`.
        """
        return not (self & other)

Return whether two sets have a intersection or not.

If the two sets have an intersection, then this returns False. If no common flag values exist between them, then this returns True.

# def issubset(self: ~_T, other: Union[~_T, int]) -> bool:

View Source

    def is_subset(self: _T, other: typing.Union[_T, int]) -> bool:
        """Return whether another set contains this set or not.

        Equivalent to using the "in" operator.
        """
        return (self & other) == other

Return whether another set contains this set or not.

Equivalent to using the "in" operator.

# def issuperset(self: ~_T, other: Union[~_T, int]) -> bool:

View Source

    def is_superset(self: _T, other: typing.Union[_T, int]) -> bool:
        """Return whether this set contains another set or not."""
        return (self & other) == self

Return whether this set contains another set or not.

# def none(self: ~_T, *flags: ~_T) -> bool:

View Source

    def none(self: _T, *flags: _T) -> bool:
        """Check if none of the given flags are part of this value.

        .. note::
            This is essentially the opposite of `Flag.any`.

        Returns
        -------
        bool
            `True` if none of the given flags are part of this value.
            Otherwise, return `False`.
        """
        return not self.any(*flags)

Check if none of the given flags are part of this value.

Note: This is essentially the opposite of Flag.any.

Returns

bool: True if none of the given flags are part of this value. Otherwise, return False.

# def split(self: ~_T) -> Sequence[~_T]:

View Source

    def split(self: _T) -> typing.Sequence[_T]:
        """Return a list of all defined atomic values for this flag.

        Any unrecognised bits will be omitted for brevity.

        The result will be a name-sorted `typing.Sequence` of each member
        """
        return sorted(
            (member for member in self.__class__._powers_of_2_to_member_map_.values() if member.value & self),
            # Assumption: powers of 2 already have a cached value.
            key=lambda m: m._name_,
        )

Return a list of all defined atomic values for this flag.

Any unrecognised bits will be omitted for brevity.

The result will be a name-sorted typing.Sequence of each member

# def symmetric_difference(self: ~_T, other: Union[~_T, int]) -> ~_T:

View Source

    def symmetric_difference(self: _T, other: typing.Union[_T, int]) -> _T:
        """Return a set with the symmetric differences of two flag sets.

        Equivalent to using the "XOR" `^` operator.

        For `a ^ b`, this can be considered the same as `(a - b) | (b - a)`.
        """
        return self.__class__(self._value_ ^ int(other))

Return a set with the symmetric differences of two flag sets.

Equivalent to using the "XOR" ^ operator.

For a ^ b, this can be considered the same as (a - b) | (b - a).

# def symmetricdifference(self: ~_T, other: Union[~_T, int]) -> ~_T:

View Source

    def symmetric_difference(self: _T, other: typing.Union[_T, int]) -> _T:
        """Return a set with the symmetric differences of two flag sets.

        Equivalent to using the "XOR" `^` operator.

        For `a ^ b`, this can be considered the same as `(a - b) | (b - a)`.
        """
        return self.__class__(self._value_ ^ int(other))

Return a set with the symmetric differences of two flag sets.

Equivalent to using the "XOR" ^ operator.

For a ^ b, this can be considered the same as (a - b) | (b - a).

# def to_bytes(self, /, length, byteorder, *, signed=False):

Return an array of bytes representing an integer.

length Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes. byteorder The byte order used to represent the integer. If byteorder is 'big', the most significant byte is at the beginning of the byte array. If byteorder is 'little', the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder' as the byte order value. signed Determines whether two's complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

# def union(self: ~_T, other: Union[~_T, int]) -> ~_T:

View Source

    def union(self: _T, other: typing.Union[_T, int]) -> _T:
        """Return a combination of all flags in this set and the other set.

        Equivalent to using the "OR" `~` operator.
        """
        return self.__class__(self._value_ | int(other))

Return a combination of all flags in this set and the other set.

Equivalent to using the "OR" ~ operator.