Events pertaining to manipulation of roles within guilds.

This module

Expand source code
Browse git
# -*- 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.
"""Events pertaining to manipulation of roles within guilds."""
from __future__ import annotations

__all__: typing.Sequence[str] = ("RoleEvent", "RoleCreateEvent", "RoleUpdateEvent", "RoleDeleteEvent")

import abc
import typing

import attr

from hikari import intents
from hikari.events import base_events
from hikari.events import shard_events
from hikari.internal import attr_extensions

if typing.TYPE_CHECKING:
    from hikari import guilds
    from hikari import snowflakes
    from hikari import traits
    from hikari.api import shard as gateway_shard


@base_events.requires_intents(intents.Intents.GUILDS)
class RoleEvent(shard_events.ShardEvent, abc.ABC):
    """Event base for any event that involves guild roles."""

    __slots__: typing.Sequence[str] = ()

    @property
    @abc.abstractmethod
    def guild_id(self) -> snowflakes.Snowflake:
        """ID of the guild that this event relates to.

        Returns
        -------
        hikari.snowflakes.Snowflake
            The ID of the guild that relates to this event.
        """

    @property
    @abc.abstractmethod
    def role_id(self) -> snowflakes.Snowflake:
        """ID of the role that this event relates to.

        Returns
        -------
        hikari.snowflakes.Snowflake
            The ID of the role that relates to this event.
        """


@attr_extensions.with_copy
@attr.define(kw_only=True, weakref_slot=False)
@base_events.requires_intents(intents.Intents.GUILDS)
class RoleCreateEvent(RoleEvent):
    """Event fired when a role is created."""

    shard: gateway_shard.GatewayShard = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring from ShardEvent>>.

    role: guilds.Role = attr.field()
    """Role that was created.

    Returns
    -------
    hikari.guilds.Role
        The created role.
    """

    @property
    def app(self) -> traits.RESTAware:
        # <<inherited docstring from Event>>.
        return self.role.app

    @property
    def guild_id(self) -> snowflakes.Snowflake:
        # <<inherited docstring from RoleEvent>>.
        return self.role.guild_id

    @property
    def role_id(self) -> snowflakes.Snowflake:
        # <<inherited docstring from RoleEvent>>.
        return self.role.id


@attr_extensions.with_copy
@attr.define(kw_only=True, weakref_slot=False)
@base_events.requires_intents(intents.Intents.GUILDS)
class RoleUpdateEvent(RoleEvent):
    """Event fired when a role is updated."""

    shard: gateway_shard.GatewayShard = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring from ShardEvent>>.

    old_role: typing.Optional[guilds.Role] = attr.field()
    """The old role object.

    This will be `builtins.None` if the role missing from the cache.
    """

    role: guilds.Role = attr.field()
    """Role that was updated.

    Returns
    -------
    hikari.guilds.Role
        The created role.
    """

    @property
    def app(self) -> traits.RESTAware:
        # <<inherited docstring from Event>>.
        return self.role.app

    @property
    def guild_id(self) -> snowflakes.Snowflake:
        # <<inherited docstring from RoleEvent>>.
        return self.role.guild_id

    @property
    def role_id(self) -> snowflakes.Snowflake:
        # <<inherited docstring from RoleEvent>>.
        return self.role.id


@attr_extensions.with_copy
@attr.define(kw_only=True, weakref_slot=False)
@base_events.requires_intents(intents.Intents.GUILDS)
class RoleDeleteEvent(RoleEvent):
    """Event fired when a role is deleted."""

    app: traits.RESTAware = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring from Event>>.

    shard: gateway_shard.GatewayShard = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring from ShardEvent>>.

    guild_id: snowflakes.Snowflake = attr.field()
    # <<inherited docstring from RoleEvent>>.

    role_id: snowflakes.Snowflake = attr.field()
    # <<inherited docstring from RoleEvent>>.

    old_role: typing.Optional[guilds.Role] = attr.field()
    """The old role object.

    This will be `builtins.None` if the role was missing from the cache.
    """

Classes

dataclass RoleCreateEvent

class RoleCreateEvent (
    *,
    shard: gateway_shard.GatewayShard,
    role: guilds.Role,
): ...

Event fired when a role is created.

This requires one of the following combinations of intents in order to be dispatched:

Method generated by attrs for class RoleCreateEvent.

Expand source code
Browse git
class RoleCreateEvent(RoleEvent):
    """Event fired when a role is created."""

    shard: gateway_shard.GatewayShard = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring from ShardEvent>>.

    role: guilds.Role = attr.field()
    """Role that was created.

    Returns
    -------
    hikari.guilds.Role
        The created role.
    """

    @property
    def app(self) -> traits.RESTAware:
        # <<inherited docstring from Event>>.
        return self.role.app

    @property
    def guild_id(self) -> snowflakes.Snowflake:
        # <<inherited docstring from RoleEvent>>.
        return self.role.guild_id

    @property
    def role_id(self) -> snowflakes.Snowflake:
        # <<inherited docstring from RoleEvent>>.
        return self.role.id
Method resolution order
dataclass RoleCreateEvent
That's this class!
abstract class RoleEvent

Event base for any event that involves guild roles …

abstract class ShardEvent

Base class for any event that was shard-specific.

abstract class Event

Base event type that all Hikari events should subclass.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
property apptraits.RESTAware

App instance for this application.

Returns

RESTAware
The REST-aware app trait.
property guild_idsnowflakes.Snowflake

ID of the guild that this event relates to.

Returns

Snowflake
The ID of the guild that relates to this event.
property roleguilds.Role

Role that was created.

Returns

Role
The created role.
property role_idsnowflakes.Snowflake

ID of the role that this event relates to.

Returns

Snowflake
The ID of the role that relates to this event.
property shardgateway_shard.GatewayShard

Shard that received this event.

Returns

GatewayShard
The shard that triggered the event.
Methods
def bitmask() -> int: ...

Inherited from: RoleEvent.bitmask

Bitmask for this event.

def dispatches() -> Sequence[Type[Event]]: ...

Inherited from: RoleEvent.dispatches

Sequence of the event classes this event is dispatched as.

dataclass RoleDeleteEvent

class RoleDeleteEvent (
    *,
    app: traits.RESTAware,
    shard: gateway_shard.GatewayShard,
    guild_id: snowflakes.Snowflake,
    role_id: snowflakes.Snowflake,
    old_role: Optional[guilds.Role],
): ...

Event fired when a role is deleted.

This requires one of the following combinations of intents in order to be dispatched:

Method generated by attrs for class RoleDeleteEvent.

Expand source code
Browse git
class RoleDeleteEvent(RoleEvent):
    """Event fired when a role is deleted."""

    app: traits.RESTAware = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring from Event>>.

    shard: gateway_shard.GatewayShard = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring from ShardEvent>>.

    guild_id: snowflakes.Snowflake = attr.field()
    # <<inherited docstring from RoleEvent>>.

    role_id: snowflakes.Snowflake = attr.field()
    # <<inherited docstring from RoleEvent>>.

    old_role: typing.Optional[guilds.Role] = attr.field()
    """The old role object.

    This will be `builtins.None` if the role was missing from the cache.
    """
Method resolution order
dataclass RoleDeleteEvent
That's this class!
abstract class RoleEvent

Event base for any event that involves guild roles …

abstract class ShardEvent

Base class for any event that was shard-specific.

abstract class Event

Base event type that all Hikari events should subclass.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
property apptraits.RESTAware

App instance for this application.

Returns

RESTAware
The REST-aware app trait.
property guild_idsnowflakes.Snowflake

ID of the guild that this event relates to.

Returns

Snowflake
The ID of the guild that relates to this event.
property old_roleOptional[guilds.Role]

The old role object.

This will be None if the role was missing from the cache.

property role_idsnowflakes.Snowflake

ID of the role that this event relates to.

Returns

Snowflake
The ID of the role that relates to this event.
property shardgateway_shard.GatewayShard

Shard that received this event.

Returns

GatewayShard
The shard that triggered the event.
Methods
def bitmask() -> int: ...

Inherited from: RoleEvent.bitmask

Bitmask for this event.

def dispatches() -> Sequence[Type[Event]]: ...

Inherited from: RoleEvent.dispatches

Sequence of the event classes this event is dispatched as.

class RoleEvent

class RoleEvent: ...

Event base for any event that involves guild roles.

This requires one of the following combinations of intents in order to be dispatched:

Expand source code
Browse git
class RoleEvent(shard_events.ShardEvent, abc.ABC):
    """Event base for any event that involves guild roles."""

    __slots__: typing.Sequence[str] = ()

    @property
    @abc.abstractmethod
    def guild_id(self) -> snowflakes.Snowflake:
        """ID of the guild that this event relates to.

        Returns
        -------
        hikari.snowflakes.Snowflake
            The ID of the guild that relates to this event.
        """

    @property
    @abc.abstractmethod
    def role_id(self) -> snowflakes.Snowflake:
        """ID of the role that this event relates to.

        Returns
        -------
        hikari.snowflakes.Snowflake
            The ID of the role that relates to this event.
        """
Subclasses
dataclass RoleCreateEvent

Event fired when a role is created …

dataclass RoleDeleteEvent

Event fired when a role is deleted …

dataclass RoleUpdateEvent

Event fired when a role is updated …

Method resolution order
abstract class RoleEvent
That's this class!
abstract class ShardEvent

Base class for any event that was shard-specific.

abstract class Event

Base event type that all Hikari events should subclass.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
abstract property appRESTAware

App instance for this application.

Returns

RESTAware
The REST-aware app trait.
abstract property guild_idsnowflakes.Snowflake

ID of the guild that this event relates to.

Returns

Snowflake
The ID of the guild that relates to this event.
abstract property role_idsnowflakes.Snowflake

ID of the role that this event relates to.

Returns

Snowflake
The ID of the role that relates to this event.
abstract property shardgateway_shard.GatewayShard

Shard that received this event.

Returns

GatewayShard
The shard that triggered the event.
Methods
def bitmask() -> int: ...

Inherited from: ShardEvent.bitmask

Bitmask for this event.

def dispatches() -> Sequence[Type[Event]]: ...

Inherited from: ShardEvent.dispatches

Sequence of the event classes this event is dispatched as.

dataclass RoleUpdateEvent

class RoleUpdateEvent (
    *,
    shard: gateway_shard.GatewayShard,
    old_role: Optional[guilds.Role],
    role: guilds.Role,
): ...

Event fired when a role is updated.

This requires one of the following combinations of intents in order to be dispatched:

Method generated by attrs for class RoleUpdateEvent.

Expand source code
Browse git
class RoleUpdateEvent(RoleEvent):
    """Event fired when a role is updated."""

    shard: gateway_shard.GatewayShard = attr.field(metadata={attr_extensions.SKIP_DEEP_COPY: True})
    # <<inherited docstring from ShardEvent>>.

    old_role: typing.Optional[guilds.Role] = attr.field()
    """The old role object.

    This will be `builtins.None` if the role missing from the cache.
    """

    role: guilds.Role = attr.field()
    """Role that was updated.

    Returns
    -------
    hikari.guilds.Role
        The created role.
    """

    @property
    def app(self) -> traits.RESTAware:
        # <<inherited docstring from Event>>.
        return self.role.app

    @property
    def guild_id(self) -> snowflakes.Snowflake:
        # <<inherited docstring from RoleEvent>>.
        return self.role.guild_id

    @property
    def role_id(self) -> snowflakes.Snowflake:
        # <<inherited docstring from RoleEvent>>.
        return self.role.id
Method resolution order
dataclass RoleUpdateEvent
That's this class!
abstract class RoleEvent

Event base for any event that involves guild roles …

abstract class ShardEvent

Base class for any event that was shard-specific.

abstract class Event

Base event type that all Hikari events should subclass.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
property apptraits.RESTAware

App instance for this application.

Returns

RESTAware
The REST-aware app trait.
property guild_idsnowflakes.Snowflake

ID of the guild that this event relates to.

Returns

Snowflake
The ID of the guild that relates to this event.
property old_roleOptional[guilds.Role]

The old role object.

This will be None if the role missing from the cache.

property roleguilds.Role

Role that was updated.

Returns

Role
The created role.
property role_idsnowflakes.Snowflake

ID of the role that this event relates to.

Returns

Snowflake
The ID of the role that relates to this event.
property shardgateway_shard.GatewayShard

Shard that received this event.

Returns

GatewayShard
The shard that triggered the event.
Methods
def bitmask() -> int: ...

Inherited from: RoleEvent.bitmask

Bitmask for this event.

def dispatches() -> Sequence[Type[Event]]: ...

Inherited from: RoleEvent.dispatches

Sequence of the event classes this event is dispatched as.