+
diff --git a/hikari/__init__.py b/hikari/__init__.py
index 8b2faa13e9..b4c5a90afd 100644
--- a/hikari/__init__.py
+++ b/hikari/__init__.py
@@ -68,30 +68,5 @@
from hikari.voices import *
from hikari.webhooks import *
-# Import everything into this namespace.
-
-__all__ = [
- *audit_logs.__all__,
- *channels.__all__,
- *clients.__all__,
- *colors.__all__,
- *colours.__all__,
- *embeds.__all__,
- *emojis.__all__,
- *bases.__all__,
- *events.__all__,
- *gateway_entities.__all__,
- *guilds.__all__,
- *intents.__all__,
- *invites.__all__,
- *messages.__all__,
- *net.__all__,
- *applications.__all__,
- *permissions.__all__,
- *bases.__all__,
- *state.__all__,
- *unset.__all__,
- *users.__all__,
- *voices.__all__,
- *webhooks.__all__,
-]
+# Adding everything to `__all__` pollutes the top level index in our documentation, therefore this is left empty.
+__all__ = []
diff --git a/hikari/applications.py b/hikari/applications.py
index 30b2c411b9..9dc64618af 100644
--- a/hikari/applications.py
+++ b/hikari/applications.py
@@ -17,7 +17,16 @@
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
"""Components and entities related to discord's Oauth2 flow."""
-__all__ = ["Application", "ApplicationOwner", "OwnGuild", "Team", "TeamMember", "TeamMembershipState"]
+__all__ = [
+ "Application",
+ "ApplicationOwner",
+ "ConnectionVisibility",
+ "OwnConnection",
+ "OwnGuild",
+ "Team",
+ "TeamMember",
+ "TeamMembershipState",
+]
import enum
import typing
@@ -36,11 +45,11 @@
class ConnectionVisibility(enum.IntEnum):
"""Describes who can see a connection with a third party account."""
- #: Only you can see the connection.
NONE = 0
+ """Only you can see the connection."""
- #: Everyone can see the connection.
EVERYONE = 1
+ """Everyone can see the connection."""
@marshaller.marshallable()
@@ -48,37 +57,25 @@ class ConnectionVisibility(enum.IntEnum):
class OwnConnection(bases.HikariEntity, marshaller.Deserializable):
"""Represents a user's connection with a third party account.
- Returned by the ``GET Current User Connections`` endpoint.
+ Returned by the `GET Current User Connections` endpoint.
"""
- #: The string ID of the third party connected account.
- #:
- #: Warning
- #: -------
- #: Seeing as this is a third party ID, it will not be a snowflake.
- #:
- #:
- #: :type: :obj:`~str`
id: str = marshaller.attrib(deserializer=str)
+ """The string ID of the third party connected account.
+
+ !!! warning
+ Seeing as this is a third party ID, it will not be a snowflake.
+ """
- #: The username of the connected account.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str)
+ """The username of the connected account."""
- #: The type of service this connection is for.
- #:
- #: :type: :obj:`~str`
type: str = marshaller.attrib(deserializer=str)
+ """The type of service this connection is for."""
- #: Whether the connection has been revoked.
- #:
- #: :type: :obj:`~bool`
is_revoked: bool = marshaller.attrib(raw_name="revoked", deserializer=bool, if_undefined=False, default=False)
+ """Whether the connection has been revoked."""
- #: A sequence of the partial guild integration objects this connection has.
- #:
- #: :type: :obj:`~typing.Sequence` [ :obj:`~hikari.guilds.PartialGuildIntegration` ]
integrations: typing.Sequence[guilds.PartialGuildIntegration] = marshaller.attrib(
deserializer=lambda payload: [
guilds.PartialGuildIntegration.deserialize(integration) for integration in payload
@@ -86,27 +83,19 @@ class OwnConnection(bases.HikariEntity, marshaller.Deserializable):
if_undefined=list,
factory=list,
)
+ """A sequence of the partial guild integration objects this connection has."""
- #: Whether the connection has been verified.
- #:
- #: :type: :obj:`~bool`
is_verified: bool = marshaller.attrib(raw_name="verified", deserializer=bool)
+ """Whether the connection has been verified."""
- #: Whether friends should be added based on this connection.
- #:
- #: :type: :obj:`~bool`
is_friend_syncing: bool = marshaller.attrib(raw_name="friend_sync", deserializer=bool)
+ """Whether friends should be added based on this connection."""
- #: Whether activities related to this connection will be shown in the
- #: user's presence updates.
- #:
- #: :type: :obj:`~bool`
is_showing_activity: bool = marshaller.attrib(raw_name="show_activity", deserializer=bool)
+ """Whether this connection's activities are shown in the user's presence."""
- #: The visibility of the connection.
- #:
- #: :type: :obj:`~ConnectionVisibility`
visibility: ConnectionVisibility = marshaller.attrib(deserializer=ConnectionVisibility)
+ """The visibility of the connection."""
@marshaller.marshallable()
@@ -114,28 +103,24 @@ class OwnConnection(bases.HikariEntity, marshaller.Deserializable):
class OwnGuild(guilds.PartialGuild):
"""Represents a user bound partial guild object."""
- #: Whether the current user owns this guild.
- #:
- #: :type: :obj:`~bool`
is_owner: bool = marshaller.attrib(raw_name="owner", deserializer=bool)
+ """Whether the current user owns this guild."""
- #: The guild level permissions that apply to the current user or bot.
- #:
- #: :type: :obj:`~hikari.permissions.Permission`
my_permissions: permissions.Permission = marshaller.attrib(
raw_name="permissions", deserializer=permissions.Permission
)
+ """The guild level permissions that apply to the current user or bot."""
@enum.unique
class TeamMembershipState(enum.IntEnum):
"""Represents the state of a user's team membership."""
- #: Denotes the user has been invited to the team but has yet to accept.
INVITED = 1
+ """Denotes the user has been invited to the team but has yet to accept."""
- #: Denotes the user has accepted the invite and is now a member.
ACCEPTED = 2
+ """Denotes the user has accepted the invite and is now a member."""
@marshaller.marshallable()
@@ -143,26 +128,20 @@ class TeamMembershipState(enum.IntEnum):
class TeamMember(bases.HikariEntity, marshaller.Deserializable):
"""Represents a member of a Team."""
- #: The state of this user's membership.
- #:
- #: :type: :obj:`~TeamMembershipState`
membership_state: TeamMembershipState = marshaller.attrib(deserializer=TeamMembershipState)
+ """The state of this user's membership."""
- #: This member's permissions within a team.
- #: Will always be ``["*"]`` until Discord starts using this.
- #:
- #: :type: :obj:`~typing.Set` [ :obj:`~str` ]
permissions: typing.Set[str] = marshaller.attrib(deserializer=set)
+ """This member's permissions within a team.
+
+ Will always be `["*"]` until Discord starts using this.
+ """
- #: The ID of the team this member belongs to.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
team_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the team this member belongs to."""
- #: The user object of this team member.
- #:
- #: :type: :obj:`~hikari.users.User`
user: users.User = marshaller.attrib(deserializer=users.User.deserialize)
+ """The user object of this team member."""
@marshaller.marshallable()
@@ -170,22 +149,16 @@ class TeamMember(bases.HikariEntity, marshaller.Deserializable):
class Team(bases.UniqueEntity, marshaller.Deserializable):
"""Represents a development team, along with all its members."""
- #: The hash of this team's icon, if set.
- #:
- #: :type: :obj:`~str`, optional
icon_hash: typing.Optional[str] = marshaller.attrib(raw_name="icon", deserializer=str)
+ """The hash of this team's icon, if set."""
- #: The member's that belong to this team.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~TeamMember` ]
members: typing.Mapping[bases.Snowflake, TeamMember] = marshaller.attrib(
deserializer=lambda members: {m.user.id: m for m in map(TeamMember.deserialize, members)}
)
+ """The member's that belong to this team."""
- #: The ID of this team's owner.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
owner_user_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of this team's owner."""
@property
def icon_url(self) -> typing.Optional[str]:
@@ -197,22 +170,22 @@ def format_icon_url(self, fmt: str = "png", size: int = 4096) -> typing.Optional
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png``.
- Supports ``png``, ``jpeg``, ``jpg`` and ``webp``.
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``. Can be any power
- of two between 16 and 4096 inclusive.
+ fmt : str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : int
+ The size to set for the URL, defaults to `4096`. Can be any power
+ of two between `16` and `4096` inclusive.
Returns
-------
- :obj:`~str`, optional
+ str, optional
The string URL.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if self.icon_hash:
return urls.generate_cdn_url("team-icons", str(self.id), self.icon_hash, fmt=fmt, size=size)
@@ -224,10 +197,8 @@ def format_icon_url(self, fmt: str = "png", size: int = 4096) -> typing.Optional
class ApplicationOwner(users.User):
"""Represents the user who owns an application, may be a team user."""
- #: This user's flags.
- #:
- #: :type: :obj:`~hikari.users.UserFlag`
flags: int = marshaller.attrib(deserializer=users.UserFlag)
+ """This user's flags."""
@property
def is_team_user(self) -> bool:
@@ -240,100 +211,81 @@ def is_team_user(self) -> bool:
class Application(bases.UniqueEntity, marshaller.Deserializable):
"""Represents the information of an Oauth2 Application."""
- #: The name of this application.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str)
+ """The name of this application."""
- #: The description of this application, will be an empty string if unset.
- #:
- #: :type: :obj:`~str`
description: str = marshaller.attrib(deserializer=str)
+ """The description of this application, will be an empty string if unset."""
- #: Whether the bot associated with this application is public.
- #: Will be :obj:`~None` if this application doesn't have an associated bot.
- #:
- #: :type: :obj:`~bool`, optional
is_bot_public: typing.Optional[bool] = marshaller.attrib(
raw_name="bot_public", deserializer=bool, if_undefined=None, default=None
)
+ """Whether the bot associated with this application is public.
+
+ Will be `None` if this application doesn't have an associated bot.
+ """
- #: Whether the bot associated with this application is requiring code grant
- #: for invites. Will be :obj:`~None` if this application doesn't have a bot.
- #:
- #: :type: :obj:`~bool`, optional
is_bot_code_grant_required: typing.Optional[bool] = marshaller.attrib(
raw_name="bot_require_code_grant", deserializer=bool, if_undefined=None, default=None
)
+ """Whether this application's bot is requiring code grant for invites.
+
+ Will be `None` if this application doesn't have a bot.
+ """
- #: The object of this application's owner.
- #: This should always be :obj:`~None` in application objects retrieved
- #: outside Discord's oauth2 flow.
- #:
- #: :type: :obj:`~ApplicationOwner`, optional
owner: typing.Optional[ApplicationOwner] = marshaller.attrib(
deserializer=ApplicationOwner.deserialize, if_undefined=None, default=None
)
+ """The object of this application's owner.
+
+ This should always be `None` in application objects retrieved outside
+ Discord's oauth2 flow.
+ """
- #: A collection of this application's rpc origin URLs, if rpc is enabled.
- #:
- #: :type: :obj:`~typing.Set` [ :obj:`~str` ], optional
rpc_origins: typing.Optional[typing.Set[str]] = marshaller.attrib(deserializer=set, if_undefined=None, default=None)
+ """A collection of this application's rpc origin URLs, if rpc is enabled."""
- #: This summary for this application's primary SKU if it's sold on Discord.
- #: Will be an empty string if unset.
- #:
- #: :type: :obj:`~str`
summary: str = marshaller.attrib(deserializer=str)
+ """This summary for this application's primary SKU if it's sold on Discord.
+
+ Will be an empty string if unset.
+ """
- #: The base64 encoded key used for the GameSDK's ``GetTicket``.
- #:
- #: :type: :obj:`~bytes`, optional
verify_key: typing.Optional[bytes] = marshaller.attrib(
deserializer=lambda key: bytes(key, "utf-8"), if_undefined=None, default=None
)
+ """The base64 encoded key used for the GameSDK's `GetTicket`."""
- #: The hash of this application's icon, if set.
- #:
- #: :type: :obj:`~str`, optional
icon_hash: typing.Optional[str] = marshaller.attrib(
raw_name="icon", deserializer=str, if_undefined=None, default=None
)
+ """The hash of this application's icon, if set."""
- #: This application's team if it belongs to one.
- #:
- #: :type: :obj:`~Team`, optional
team: typing.Optional[Team] = marshaller.attrib(
deserializer=Team.deserialize, if_undefined=None, if_none=None, default=None
)
+ """This application's team if it belongs to one."""
- #: The ID of the guild this application is linked to
- #: if it's sold on Discord.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild this application is linked to if it's sold on Discord."""
- #: The ID of the primary "Game SKU" of a game that's sold on Discord.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
primary_sku_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the primary "Game SKU" of a game that's sold on Discord."""
- #: The URL slug that links to this application's store page
- #: if it's sold on Discord.
- #:
- #: :type: :obj:`~str`, optional
slug: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The URL slug that links to this application's store page.
+
+ Only applicable to applications sold on Discord.
+ """
- #: The hash of this application's cover image on it's store, if set.
- #:
- #: :type: :obj:`~str`, optional
cover_image_hash: typing.Optional[str] = marshaller.attrib(
raw_name="cover_image", deserializer=str, if_undefined=None, default=None
)
+ """The hash of this application's cover image on it's store, if set."""
@property
def icon_url(self) -> typing.Optional[str]:
@@ -345,22 +297,22 @@ def format_icon_url(self, fmt: str = "png", size: int = 4096) -> typing.Optional
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png``.
- Supports ``png``, ``jpeg``, ``jpg`` and ```webp``.
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``.
+ fmt : str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : int
+ The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
- :obj:`~str`, optional
+ str, optional
The string URL.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if self.icon_hash:
return urls.generate_cdn_url("app-icons", str(self.id), self.icon_hash, fmt=fmt, size=size)
@@ -376,22 +328,22 @@ def format_cover_image_url(self, fmt: str = "png", size: int = 4096) -> typing.O
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png``.
- Supports ``png``, ``jpeg``, ``jpg`` and ``webp``.
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``.
+ fmt : str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : int
+ The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
- :obj:`~str`, optional
+ str, optional
The string URL.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if self.cover_image_hash:
return urls.generate_cdn_url("app-assets", str(self.id), self.cover_image_hash, fmt=fmt, size=size)
diff --git a/hikari/audit_logs.py b/hikari/audit_logs.py
index 62912e978f..f7eeb0c5a4 100644
--- a/hikari/audit_logs.py
+++ b/hikari/audit_logs.py
@@ -33,6 +33,7 @@
"MessageBulkDeleteEntryInfo",
"MessageDeleteEntryInfo",
"MessagePinEntryInfo",
+ "UnrecognisedAuditLogEntryInfo",
]
import abc
@@ -111,8 +112,8 @@ class AuditLogChangeKey(str, enum.Enum):
RATE_LIMIT_PER_USER = "rate_limit_per_user"
SYSTEM_CHANNEL_ID = "system_channel_id"
- #: Alias for "COLOR"
COLOUR = COLOR
+ """Alias for "COLOR"""
def __str__(self) -> str:
return self.name
@@ -164,21 +165,16 @@ def __str__(self) -> str:
@marshaller.marshallable()
@attr.s(slots=True, kw_only=True)
class AuditLogChange(bases.HikariEntity, marshaller.Deserializable):
- """Represents a change made to an audit log entry's target entity.
-
- Attributes
- ----------
- new_value : typing.Any, optional
- The new value of the key, if something was added or changed.
- old_value : typing.Any, optional
- The old value of the key, if something was removed or changed.
- key : typing.Union [ AuditLogChangeKey, str ]
- The name of the audit log change's key.
- """
+ """Represents a change made to an audit log entry's target entity."""
new_value: typing.Optional[typing.Any] = marshaller.attrib()
+ """The new value of the key, if something was added or changed."""
+
old_value: typing.Optional[typing.Any] = marshaller.attrib()
+ """The old value of the key, if something was removed or changed."""
+
key: typing.Union[AuditLogChangeKey, str] = marshaller.attrib()
+ """The name of the audit log change's key."""
@classmethod
def deserialize(cls, payload: typing.Mapping[str, str]) -> "AuditLogChange":
@@ -252,7 +248,7 @@ def register_audit_log_entry_info(
Returns
-------
- ``decorator(T) -> T``
+ decorator(T) -> T
The decorator to decorate the class with.
"""
@@ -284,21 +280,15 @@ class ChannelOverwriteEntryInfo(BaseAuditLogEntryInfo):
Will be attached to the overwrite create, update and delete audit log
entries.
-
- Attributes
- ----------
- id : hikari.snowflakes.Snowflake
- The ID of the overwrite being updated, added or removed (and the entity
- it targets).
- type : hikari.channels.PermissionOverwriteType
- The type of entity this overwrite targets.
- role_name : str, optional
- The name of the role this overwrite targets, if it targets a role.
"""
id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the overwrite being updated, added or removed."""
type: channels.PermissionOverwriteType = marshaller.attrib(deserializer=channels.PermissionOverwriteType)
+ """The type of entity this overwrite targets."""
+
role_name: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The name of the role this overwrite targets, if it targets a role."""
@register_audit_log_entry_info(AuditLogEventType.MESSAGE_PIN, AuditLogEventType.MESSAGE_UNPIN)
@@ -308,107 +298,77 @@ class MessagePinEntryInfo(BaseAuditLogEntryInfo):
"""The extra information for message pin related audit log entries.
Will be attached to the message pin and message unpin audit log entries.
-
- Attributes
- ----------
- channel_id : hikari.snowflakes.Snowflake
- The ID of the guild text based channel where this pinned message is
- being added or removed.
- message_id : hikari.snowflakes.Snowflake
- The ID of the message that's being pinned or unpinned.
"""
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the text based channel where a pinned message is being targeted."""
+
message_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the message that's being pinned or unpinned."""
@register_audit_log_entry_info(AuditLogEventType.MEMBER_PRUNE)
@marshaller.marshallable()
@attr.s(slots=True, kw_only=True)
class MemberPruneEntryInfo(BaseAuditLogEntryInfo):
- """Represents the extra information attached to guild prune log entries.
-
- Attributes
- ----------
- delete_member_days : datetime.timedelta
- The timedelta of how many days members were pruned for inactivity based
- on.
- members_removed : int
- The number of members who were removed by this prune.
- """
+ """Represents the extra information attached to guild prune log entries."""
delete_member_days: datetime.timedelta = marshaller.attrib(
deserializer=lambda payload: datetime.timedelta(days=int(payload))
)
+ """The timedelta of how many days members were pruned for inactivity based on."""
+
members_removed: int = marshaller.attrib(deserializer=int)
+ """The number of members who were removed by this prune."""
@register_audit_log_entry_info(AuditLogEventType.MESSAGE_BULK_DELETE)
@marshaller.marshallable()
@attr.s(slots=True, kw_only=True)
class MessageBulkDeleteEntryInfo(BaseAuditLogEntryInfo):
- """Represents extra information for the message bulk delete audit entry.
-
- Attributes
- ----------
- count : int
- The amount of messages that were deleted.
- """
+ """Represents extra information for the message bulk delete audit entry."""
count: int = marshaller.attrib(deserializer=int)
+ """The amount of messages that were deleted."""
@register_audit_log_entry_info(AuditLogEventType.MESSAGE_DELETE)
@marshaller.marshallable()
@attr.s(slots=True, kw_only=True)
class MessageDeleteEntryInfo(MessageBulkDeleteEntryInfo):
- """Represents extra information attached to the message delete audit entry.
-
- Attributes
- ----------
- channel_id : hikari.snowflakes.Snowflake
- The guild text based channel where these message(s) were deleted.
- count : int
- The amount of messages that were deleted.
- """
+ """Represents extra information attached to the message delete audit entry."""
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The guild text based channel where these message(s) were deleted."""
@register_audit_log_entry_info(AuditLogEventType.MEMBER_DISCONNECT)
@marshaller.marshallable()
@attr.s(slots=True, kw_only=True)
class MemberDisconnectEntryInfo(BaseAuditLogEntryInfo):
- """Represents extra information for the voice chat member disconnect entry.
-
- Attributes
- ----------
- count : int
- The amount of members who were disconnected from voice in this entry.
- """
+ """Represents extra information for the voice chat member disconnect entry."""
count: int = marshaller.attrib(deserializer=int)
+ """The amount of members who were disconnected from voice in this entry."""
@register_audit_log_entry_info(AuditLogEventType.MEMBER_MOVE)
@marshaller.marshallable()
@attr.s(slots=True, kw_only=True)
class MemberMoveEntryInfo(MemberDisconnectEntryInfo):
- """Represents extra information for the voice chat based member move entry.
-
- Attributes
- ----------
- channel_id : hikari.snowflakes.Snowflake
- The channel these member(s) were moved to.
- count : int
- The amount of members who were disconnected from voice in this entry.
- """
+ """Represents extra information for the voice chat based member move entry."""
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The amount of members who were disconnected from voice in this entry."""
class UnrecognisedAuditLogEntryInfo(BaseAuditLogEntryInfo):
- """Represents any audit log entry options that haven't been implemented."""
+ """Represents any audit log entry options that haven't been implemented.
+
+ !!! note
+ This model has no slots and will have arbitrary undocumented attributes
+ (in it's `__dict__` based on the received payload).
+ """
def __init__(self, payload: typing.Mapping[str, str]) -> None:
self.__dict__.update(payload)
@@ -440,31 +400,23 @@ def get_entry_info_entity(type_: int) -> typing.Type[BaseAuditLogEntryInfo]:
@marshaller.marshallable()
@attr.s(slots=True, kw_only=True)
class AuditLogEntry(bases.UniqueEntity, marshaller.Deserializable):
- """Represents an entry in a guild's audit log.
-
- Attributes
- ----------
- target_id : hikari.snowflakes.Snowflake, optional
- The ID of the entity affected by this change, if applicable.
- changes : typing.Sequence [ AuditLogChange ]
- A sequence of the changes made to `AuditLogEntry.target_id`.
- user_id : hikari.snowflakes.Snowflake
- The ID of the user who made this change.
- action_type : typing.Union [ AuditLogEventType, str ]
- The type of action this entry represents.
- options : BaseAuditLogEntryInfo, optional
- Extra information about this entry. Will only be provided for certain
- `action_type`.
- reason : str, optional
- The reason for this change, if set (between 0-512 characters).
- """
+ """Represents an entry in a guild's audit log."""
target_id: typing.Optional[bases.Snowflake] = marshaller.attrib()
+ """The ID of the entity affected by this change, if applicable."""
changes: typing.Sequence[AuditLogChange] = marshaller.attrib()
+ """A sequence of the changes made to `AuditLogEntry.target_id`."""
+
user_id: bases.Snowflake = marshaller.attrib()
+ """The ID of the user who made this change."""
action_type: typing.Union[AuditLogEventType, str] = marshaller.attrib()
+ """The type of action this entry represents."""
+
options: typing.Optional[BaseAuditLogEntryInfo] = marshaller.attrib()
+ """Extra information about this entry. Only be provided for certain `action_type`."""
+
reason: typing.Optional[str] = marshaller.attrib()
+ """The reason for this change, if set (between 0-512 characters)."""
@classmethod
def deserialize(cls, payload: typing.Mapping[str, str]) -> "AuditLogEntry":
@@ -495,34 +447,30 @@ def deserialize(cls, payload: typing.Mapping[str, str]) -> "AuditLogEntry":
@marshaller.marshallable()
@attr.s(slots=True, kw_only=True)
class AuditLog(bases.HikariEntity, marshaller.Deserializable):
- """Represents a guilds audit log.
+ """Represents a guilds audit log."""
- Attributes
- ----------
- entries : typing.Mapping [ hikari.snowflakes.Snowflake, AuditLogEntry ]
- A sequence of the audit log's entries.
- integrations : typing.Mapping [ hikari.snowflakes.Snowflake, hikari.guilds.GuildIntegration ]
- A mapping of the partial objects of integrations found in this audit log.
- users : typing.Mapping [ hikari.bases.Snowflake, hikari.users.User` ]
- A mapping of the objects of users found in this audit log.
- webhooks : typing.Mapping [ hikari.snowflakes.Snowflake, hikari.webhooks.Webhook ]
- A mapping of the objects of webhooks found in this audit log.
- """
entries: typing.Mapping[bases.Snowflake, AuditLogEntry] = marshaller.attrib(
raw_name="audit_log_entries",
deserializer=lambda payload: {entry.id: entry for entry in map(AuditLogEntry.deserialize, payload)},
)
+ """A sequence of the audit log's entries."""
+
integrations: typing.Mapping[bases.Snowflake, guilds.GuildIntegration] = marshaller.attrib(
deserializer=lambda payload: {
integration.id: integration for integration in map(guilds.PartialGuildIntegration.deserialize, payload)
}
)
+ """A mapping of the partial objects of integrations found in this audit log."""
+
users: typing.Mapping[bases.Snowflake, _users.User] = marshaller.attrib(
deserializer=lambda payload: {user.id: user for user in map(_users.User.deserialize, payload)}
)
+ """A mapping of the objects of users found in this audit log."""
+
webhooks: typing.Mapping[bases.Snowflake, _webhooks.Webhook] = marshaller.attrib(
deserializer=lambda payload: {webhook.id: webhook for webhook in map(_webhooks.Webhook.deserialize, payload)}
)
+ """A mapping of the objects of webhooks found in this audit log."""
class AuditLogIterator(typing.AsyncIterator[AuditLogEntry]):
@@ -531,16 +479,6 @@ class AuditLogIterator(typing.AsyncIterator[AuditLogEntry]):
This returns the audit log entries created before a given entry object/ID or
from the newest audit log entry to the oldest.
- Attributes
- ----------
- integrations : typing.Mapping [ hikari.snowflakes.Snowflake, hikari.guilds.GuildIntegration ]
- A mapping of the partial objects of integrations found in this audit log
- so far.
- users : typing.Mapping [ hikari.snowflakes.Snowflake, hikari.users.User ]
- A mapping of the objects of users found in this audit log so far.
- webhooks : typing.Mapping [ hikari.snowflakes.Snowflake, hikari.webhooks.Webhook ]
- A mapping of the objects of webhooks found in this audit log so far.
-
Parameters
----------
guild_id : str
@@ -557,14 +495,18 @@ class AuditLogIterator(typing.AsyncIterator[AuditLogEntry]):
else unlimited.
before : str
If specified, an entry ID to specify where this iterator's returned
- audit log entries should start .
-
- Note
- ----
- This iterator's attributes `AuditLogIterator.integrations`,
- `AuditLogIterator.users` and `AuditLogIterator.webhooks` will be filled up
- as this iterator makes requests to the Get Guild Audit Log endpoint with
- the relevant objects for entities referenced by returned entries.
+ audit log entries should start.
+
+ Yields
+ ------
+ AuditLogEntry
+ The entries found in this audit log.
+
+ !!! note
+ This iterator's attributes `AuditLogIterator.integrations`,
+ `AuditLogIterator.users` and `AuditLogIterator.webhooks` will be filled
+ up as this iterator makes requests to the Get Guild Audit Log endpoint
+ with the relevant objects for entities referenced by returned entries.
"""
__slots__ = (
@@ -579,8 +521,13 @@ class AuditLogIterator(typing.AsyncIterator[AuditLogEntry]):
)
integrations: typing.Mapping[bases.Snowflake, guilds.GuildIntegration]
+ """A mapping of the partial integrations objects found in this log so far."""
+
users: typing.Mapping[bases.Snowflake, _users.User]
+ """A mapping of the objects of users found in this audit log so far."""
+
webhooks: typing.Mapping[bases.Snowflake, _webhooks.Webhook]
+ """A mapping of the objects of webhooks found in this audit log so far."""
def __init__(
self,
@@ -614,7 +561,7 @@ async def __anext__(self) -> AuditLogEntry:
raise StopAsyncIteration
async def _fill(self) -> None:
- """Retrieve entries before :attr:`_front` and add to :attr:`_buffer`."""
+ """Retrieve entries before `_front` and add to `_buffer`."""
payload = await self._request(
**self._kwargs,
before=self._front if self._front is not None else ...,
diff --git a/hikari/bases.py b/hikari/bases.py
index 19d1dc5d94..dc6b7bc262 100644
--- a/hikari/bases.py
+++ b/hikari/bases.py
@@ -40,15 +40,13 @@ class HikariEntity(abc.ABC):
class Snowflake(HikariEntity, typing.SupportsInt):
"""A concrete representation of a unique identifier for an object on Discord.
- This object can be treated as a regular :obj:`~int` for most purposes.
+ This object can be treated as a regular `int` for most purposes.
"""
__slots__ = ("_value",)
- #: The integer value of this ID.
- #:
- #: :type: :obj:`~int`
_value: int
+ """The integer value of this ID."""
# noinspection PyMissingConstructor
def __init__(self, value: typing.Union[int, str]) -> None:
@@ -99,7 +97,7 @@ def serialize(self) -> str:
@classmethod
def deserialize(cls, value: str) -> "Snowflake":
- """Take a :obj:`~str` ID and convert it into a Snowflake object."""
+ """Take a `str` ID and convert it into a Snowflake object."""
return cls(value)
@classmethod
@@ -118,14 +116,12 @@ def from_timestamp(cls, timestamp: float) -> "Snowflake":
class UniqueEntity(HikariEntity, typing.SupportsInt, abc.ABC):
"""A base for an entity that has an integer ID of some sort.
- Casting an object of this type to an :obj:`~int` will produce the
+ Casting an object of this type to an `int` will produce the
integer ID of the object.
"""
- #: The ID of this entity.
- #:
- #: :type: :obj:`~Snowflake`
id: Snowflake = marshaller.attrib(hash=True, eq=True, repr=True, deserializer=Snowflake, serializer=str)
+ """The ID of this entity."""
def __int__(self) -> int:
return int(self.id)
diff --git a/hikari/channels.py b/hikari/channels.py
index df517a3c19..aba57371b3 100644
--- a/hikari/channels.py
+++ b/hikari/channels.py
@@ -16,17 +16,7 @@
#
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
-"""Components and entities that are used to describe both DMs and guild channels on Discord.
-
-.. inheritance-diagram::
- hikari.channels
- enum.IntEnum
- hikari.bases.HikariEntity
- hikari.bases.Deserializable
- hikari.bases.Serializable
- hikari.bases.UniqueEntity
- :parts: 1
-"""
+"""Components and entities that are used to describe both DMs and guild channels on Discord."""
__all__ = [
"Channel",
@@ -37,6 +27,7 @@
"DMChannel",
"GroupDMChannel",
"GuildCategory",
+ "GuildChannel",
"GuildTextChannel",
"GuildNewsChannel",
"GuildStoreChannel",
@@ -61,38 +52,37 @@
class ChannelType(enum.IntEnum):
"""The known channel types that are exposed to us by the API."""
- #: A text channel in a guild.
GUILD_TEXT = 0
+ """A text channel in a guild."""
- #: A direct channel between two users.
DM = 1
+ """A direct channel between two users."""
- #: A voice channel in a guild.
GUILD_VOICE = 2
+ """A voice channel in a guild."""
- #: A direct channel between multiple users.
GROUP_DM = 3
+ """A direct channel between multiple users."""
- #: An category used for organizing channels in a guild.
GUILD_CATEGORY = 4
+ """An category used for organizing channels in a guild."""
- #: A channel that can be followed and can crosspost.
GUILD_NEWS = 5
+ """A channel that can be followed and can crosspost."""
- #: A channel that show's a game's store page.
GUILD_STORE = 6
+ """A channel that show's a game's store page."""
@enum.unique
class PermissionOverwriteType(str, enum.Enum):
"""The type of entity a Permission Overwrite targets."""
- #: A permission overwrite that targets all the members with a specific
- #: guild role.
ROLE = "role"
+ """A permission overwrite that targets all the members with a specific role."""
- #: A permission overwrite that targets a specific guild member.
MEMBER = "member"
+ """A permission overwrite that targets a specific guild member."""
def __str__(self) -> str:
return self.value
@@ -103,24 +93,18 @@ def __str__(self) -> str:
class PermissionOverwrite(bases.UniqueEntity, marshaller.Deserializable, marshaller.Serializable):
"""Represents permission overwrites for a channel or role in a channel."""
- #: The type of entity this overwrite targets.
- #:
- #: :type: :obj:`~PermissionOverwriteType`
type: PermissionOverwriteType = marshaller.attrib(deserializer=PermissionOverwriteType, serializer=str)
+ """The type of entity this overwrite targets."""
- #: The permissions this overwrite allows.
- #:
- #: :type: :obj:`~hikari.permissions.Permission`
allow: permissions.Permission = marshaller.attrib(
deserializer=permissions.Permission, serializer=int, default=permissions.Permission(0)
)
+ """The permissions this overwrite allows."""
- #: The permissions this overwrite denies.
- #:
- #: :type: :obj:`~hikari.permissions.Permission`
deny: permissions.Permission = marshaller.attrib(
deserializer=permissions.Permission, serializer=int, default=permissions.Permission(0)
)
+ """The permissions this overwrite denies."""
@property
def unset(self) -> permissions.Permission:
@@ -135,12 +119,12 @@ def register_channel_type(type_: ChannelType) -> typing.Callable[[typing.Type["C
Parameters
----------
- type_ : :obj:`~ChannelType`
+ type_ : ChannelType
The channel type to associate with.
Returns
-------
- ``decorator(T) -> T``
+ decorator(T) -> T
The decorator to decorate the class with.
"""
@@ -158,10 +142,8 @@ def decorator(cls):
class Channel(bases.UniqueEntity, marshaller.Deserializable):
"""Base class for all channels."""
- #: The channel's type.
- #:
- #: :type: :obj:`~ChannelType`
type: ChannelType = marshaller.attrib(deserializer=ChannelType)
+ """The channel's type."""
@marshaller.marshallable()
@@ -172,10 +154,8 @@ class PartialChannel(Channel):
This is commonly received in REST responses.
"""
- #: The channel's name.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str)
+ """The channel's name."""
@register_channel_type(ChannelType.DM)
@@ -184,22 +164,17 @@ class PartialChannel(Channel):
class DMChannel(Channel):
"""Represents a DM channel."""
- #: The ID of the last message sent in this channel.
- #:
- #: Note
- #: ----
- #: This might point to an invalid or deleted message.
- #:
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
last_message_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize, if_none=None)
+ """The ID of the last message sent in this channel.
+
+ !!! note
+ This might point to an invalid or deleted message.
+ """
- #: The recipients of the DM.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~hikari.users.User` ]
recipients: typing.Mapping[bases.Snowflake, users.User] = marshaller.attrib(
deserializer=lambda recipients: {user.id: user for user in map(users.User.deserialize, recipients)}
)
+ """The recipients of the DM."""
@register_channel_type(ChannelType.GROUP_DM)
@@ -208,28 +183,19 @@ class DMChannel(Channel):
class GroupDMChannel(DMChannel):
"""Represents a DM group channel."""
- #: The group's name.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str)
+ """The group's name."""
- #: The ID of the owner of the group.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
owner_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the owner of the group."""
- #: The hash of the icon of the group.
- #:
- #: :type: :obj:`~str`, optional
icon_hash: typing.Optional[str] = marshaller.attrib(raw_name="icon", deserializer=str, if_none=None)
+ """The hash of the icon of the group."""
- #: The ID of the application that created the group DM, if it's a
- #: bot based group DM.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
application_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the application that created the group DM, if it's a bot based group DM."""
@marshaller.marshallable()
@@ -237,37 +203,25 @@ class GroupDMChannel(DMChannel):
class GuildChannel(Channel):
"""The base for anything that is a guild channel."""
- #: The ID of the guild the channel belongs to.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild the channel belongs to."""
- #: The sorting position of the channel.
- #:
- #: :type: :obj:`~int`
position: int = marshaller.attrib(deserializer=int)
+ """The sorting position of the channel."""
- #: The permission overwrites for the channel.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~PermissionOverwrite` ]
permission_overwrites: PermissionOverwrite = marshaller.attrib(
deserializer=lambda overwrites: {o.id: o for o in map(PermissionOverwrite.deserialize, overwrites)}
)
+ """The permission overwrites for the channel."""
- #: The name of the channel.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str)
+ """The name of the channel."""
- #: Wheter the channel is marked as NSFW.
- #:
- #: :type: :obj:`~bool`
is_nsfw: bool = marshaller.attrib(raw_name="nsfw", deserializer=bool)
+ """Whether the channel is marked as NSFW."""
- #: The ID of the parent category the channel belongs to.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
parent_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize, if_none=None)
+ """The ID of the parent category the channel belongs to."""
@register_channel_type(ChannelType.GUILD_CATEGORY)
@@ -283,33 +237,25 @@ class GuildCategory(GuildChannel):
class GuildTextChannel(GuildChannel):
"""Represents a guild text channel."""
- #: The topic of the channel.
- #:
- #: :type: :obj:`~str`, optional
topic: str = marshaller.attrib(deserializer=str, if_none=None)
+ """The topic of the channel."""
- #: The ID of the last message sent in this channel.
- #:
- #: Note
- #: ----
- #: This might point to an invalid or deleted message.
- #:
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
last_message_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize, if_none=None)
+ """The ID of the last message sent in this channel.
+
+ !!! note
+ This might point to an invalid or deleted message.
+ """
- #: The delay (in seconds) between a user can send a message
- #: to this channel.
- #:
- #: Note
- #: ----
- #: Bots, as well as users with ``MANAGE_MESSAGES`` or
- #: ``MANAGE_CHANNEL``, are not afected by this.
- #:
- #: :type: :obj:`~datetime.timedelta`
rate_limit_per_user: datetime.timedelta = marshaller.attrib(
deserializer=lambda payload: datetime.timedelta(seconds=payload)
)
+ """The delay (in seconds) between a user can send a message to this channel.
+
+ !!! note
+ Bots, as well as users with `MANAGE_MESSAGES` or `MANAGE_CHANNEL`,
+ are not affected by this.
+ """
@register_channel_type(ChannelType.GUILD_NEWS)
@@ -318,20 +264,15 @@ class GuildTextChannel(GuildChannel):
class GuildNewsChannel(GuildChannel):
"""Represents an news channel."""
- #: The topic of the channel.
- #:
- #: :type: :obj:`~str`, optional
topic: str = marshaller.attrib(deserializer=str, if_none=None)
+ """The topic of the channel."""
- #: The ID of the last message sent in this channel.
- #:
- #: Note
- #: ----
- #: This might point to an invalid or deleted message.
- #:
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
last_message_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize, if_none=None)
+ """The ID of the last message sent in this channel.
+
+ !!! note
+ This might point to an invalid or deleted message.
+ """
@register_channel_type(ChannelType.GUILD_STORE)
@@ -347,15 +288,11 @@ class GuildStoreChannel(GuildChannel):
class GuildVoiceChannel(GuildChannel):
"""Represents an voice channel."""
- #: The bitrate for the voice channel (in bits).
- #:
- #: :type: :obj:`~int`
bitrate: int = marshaller.attrib(deserializer=int)
+ """The bitrate for the voice channel (in bits)."""
- #: The user limit for the voice channel.
- #:
- #: :type: :obj:`~int`
user_limit: int = marshaller.attrib(deserializer=int)
+ """The user limit for the voice channel."""
class GuildChannelBuilder(marshaller.Serializable):
@@ -365,13 +302,11 @@ class GuildChannelBuilder(marshaller.Serializable):
----------
channel_name : str
The name to set for the channel.
- channel_type : :obj:`~ChannelType`
+ channel_type : ChannelType
The type of channel this should build.
- Example
- -------
- .. code-block:: python
-
+ Examples
+ --------
channel_obj = (
channels.GuildChannelBuilder("Catgirl-appreciation", channels.ChannelType.GUILD_TEXT)
.is_nsfw(True)
@@ -402,16 +337,15 @@ def is_nsfw(self) -> "GuildChannelBuilder":
def with_permission_overwrites(self, overwrites: typing.Sequence[PermissionOverwrite]) -> "GuildChannelBuilder":
"""Set the permission overwrites for this channel.
- Note
- ----
- Calling this multiple times will overwrite any previously added
- overwrites.
-
Parameters
----------
- overwrites : :obj:`~typing.Sequence` [ :obj:`~PermissionOverwrite` ]
+ overwrites : typing.Sequence [ PermissionOverwrite ]
A sequence of overwrite objects to add, where the first overwrite
object
+
+ !!! note
+ Calling this multiple times will overwrite any previously added
+ overwrites.
"""
self._payload["permission_overwrites"] = [o.serialize() for o in overwrites]
return self
@@ -421,7 +355,7 @@ def with_topic(self, topic: str) -> "GuildChannelBuilder":
Parameters
----------
- topic : :obj:`~str`
+ topic : str
The string topic to set.
"""
self._payload["topic"] = topic
@@ -432,7 +366,7 @@ def with_bitrate(self, bitrate: int) -> "GuildChannelBuilder":
Parameters
----------
- bitrate : :obj:`~int`
+ bitrate : int
The bitrate to set in bits.
"""
self._payload["bitrate"] = int(bitrate)
@@ -443,7 +377,7 @@ def with_user_limit(self, user_limit: int) -> "GuildChannelBuilder":
Parameters
----------
- user_limit : :obj:`~int`
+ user_limit : int
The user limit to set.
"""
self._payload["user_limit"] = int(user_limit)
@@ -456,7 +390,7 @@ def with_rate_limit_per_user(
Parameters
----------
- rate_limit_per_user : :obj:`~typing.Union` [ :obj:`~datetime.timedelta`, :obj:`~int` ]
+ rate_limit_per_user : typing.Union [ datetime.timedelta, int ]
The amount of seconds users will have to wait before sending another
message in the channel to set.
"""
@@ -472,7 +406,7 @@ def with_parent_category(self, category: typing.Union[bases.Snowflake, int]) ->
Parameters
----------
- category : :obj:`~typing.Union` [ :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ category : typing.Union [ hikari.bases.Snowflake, int ]
The placeholder ID of the category channel that should be this
channel's parent.
"""
@@ -482,15 +416,14 @@ def with_parent_category(self, category: typing.Union[bases.Snowflake, int]) ->
def with_id(self, channel_id: typing.Union[bases.Snowflake, int]) -> "GuildChannelBuilder":
"""Set the placeholder ID for this channel.
- Notes
- -----
- This ID is purely a place holder used for setting parent category
- channels and will have no effect on the created channel's ID.
-
Parameters
----------
- channel_id : :obj:`~typing.Union` [ :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel_id : typing.Union [ hikari.bases.Snowflake, int ]
The placeholder ID to use.
+
+ !!! note
+ This ID is purely a place holder used for setting parent category
+ channels and will have no effect on the created channel's ID.
"""
self._payload["id"] = str(int(channel_id))
return self
@@ -499,10 +432,9 @@ def with_id(self, channel_id: typing.Union[bases.Snowflake, int]) -> "GuildChann
def deserialize_channel(payload: typing.Dict[str, typing.Any]) -> typing.Union[GuildChannel, DMChannel]:
"""Deserialize a channel object into the corresponding class.
- Warning
- -------
- This can only be used to deserialize full channel objects. To deserialize a
- partial object, use ``PartialChannel.deserialize()``.
+ !!! warning
+ This can only be used to deserialize full channel objects. To
+ deserialize a partial object, use `PartialChannel.deserialize`.
"""
type_id = payload["type"]
types = getattr(register_channel_type, "types", more_collections.EMPTY_DICT)
diff --git a/hikari/clients/bot_base.py b/hikari/clients/bot_base.py
index da5da1dfaa..85185b8bf8 100644
--- a/hikari/clients/bot_base.py
+++ b/hikari/clients/bot_base.py
@@ -57,59 +57,49 @@ class BotBase(
"""An abstract base class for a bot implementation.
This takes several generic parameter types in the following order:
- - ``ShardClientT`` - the implementation of
- :obj:`~hikari.clients.shard_clients.ShardClient` to use for shards.
- - ``RESTClientT`` - the implementation of
- :obj:`~hikari.clients.rest.RESTClient` to use for API calls.
- - ``EventDispatcherT`` - the implementation of
- :obj:`~hikari.state.dispatchers.EventDispacher` to use for
+
+ * `ShardClientT` - the implementation of
+ `hikari.clients.shards.ShardClient` to use for shards.
+ * `RESTClientT` - the implementation of
+ `hikari.clients.rest.RESTClient` to use for API calls.
+ * `EventDispatcherT` - the implementation of
+ `hikari.state.dispatchers.EventDispatcher` to use for
dispatching events. This class will then delegate any calls inherited
- from :obj:`~hikari.state.dispatchers.EventDispacher` to that
+ from `hikari.state.dispatchers.EventDispatcher` to that
implementation when provided.
- - ``EventManagerT`` - the implementation of
- :obj:`~hikari.state.event_managers.EventManager` to use for
+ * `EventManagerT` - the implementation of
+ `hikari.state.event_managers.EventManager` to use for
event management, translation, and dispatching.
- - ``BotConfigT`` - the implementation of
- :obj:`~hikari.clients.configs.BotConfig` to read component-specific
+ * `BotConfigT` - the implementation of
+ `hikari.clients.configs.BotConfig` to read component-specific
details from.
Parameters
----------
- config : :obj:`~hikari.clients.configs.BotConfig`
+ config : hikari.clients.configs.BotConfig
The config object to use.
"""
- #: The config for this bot.
- #:
- #: :type: :obj:`~hikari.clients.configs.BotConfig`
_config: BotConfigT
+ """The config for this bot."""
- #: The event dispatcher for this bot.
- #:
- #: :type: an implementation instance of :obj:`~hikari.state.dispatcher.EventDispatcher`
event_dispatcher: EventDispatcherT
+ """The event dispatcher for this bot."""
- #: The event manager for this bot.
- #:
- #: :type: an implementation instance of :obj:`~hikari.state.event_managers.EventManager`
event_manager: EventManagerT
+ """The event manager for this bot."""
- #: The logger to use for this bot.
- #:
- #: :type: :obj:`~logging.Logger`
logger: logging.Logger
+ """The logger to use for this bot."""
- #: The REST HTTP client to use for this bot.
- #:
- #: :type: :obj:`~hikari.clients.rest.RESTClient`
rest: RESTClientT
+ """The REST HTTP client to use for this bot."""
- #: Shards registered to this bot.
- #:
- #: These will be created once the bot has started execution.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~int`, ? extends :obj:`~hikari.clients.shard_client.ShardClient` ]
shards: typing.Mapping[int, ShardClientT]
+ """Shards registered to this bot.
+
+ These will be created once the bot has started execution.
+ """
def __init__(self, config: configs.BotConfig) -> None:
super().__init__(logging.getLogger(f"hikari.{type(self).__qualname__}"))
@@ -125,18 +115,18 @@ def heartbeat_latency(self) -> float:
This will return a mean of all the heartbeat intervals for all shards
with a valid heartbeat latency that are in the
- :obj:`~hikari.clients.shard_clients.ShardState.READY` state.
+ `hikari.clients.shards.ShardState.READY` state.
- If no shards are in this state, this will return ``float('nan')``
+ If no shards are in this state, this will return `float("nan")`
instead.
Returns
-------
- :obj:`~float`
- The mean latency for all ``READY`` shards that have sent at least
- one acknowledged ``HEARTBEAT`` payload. If there is not at least
+ float
+ The mean latency for all `READY` shards that have sent at least
+ one acknowledged `HEARTBEAT` payload. If there is not at least
one shard that meets this criteria, this will instead return
- ``float('nan')``.
+ `float("nan")`.
"""
latencies = []
for shard in self.shards.values():
@@ -147,48 +137,25 @@ def heartbeat_latency(self) -> float:
@property
def total_disconnect_count(self) -> int:
- """Total number of times any shard has disconnected.
-
- Returns
- -------
- :obj:`int`
- Total disconnect count.
- """
+ """Total number of times any shard has disconnected."""
return sum(s.disconnect_count for s in self.shards.values())
@property
def total_reconnect_count(self) -> int:
- """Total number of times any shard has reconnected.
-
- Returns
- -------
- :obj:`int`
- Total reconnect count.
- """
+ """Total number of times any shard has reconnected."""
return sum(s.reconnect_count for s in self.shards.values())
@property
- def intents(self) -> typing.Optional[intents.Intent]:
- """Intent values that any shard connections will be using.
+ def intents(self) -> typing.Optional[intents.Intent]: # noqa: D401
+ """Intents that are in use for the connection.
- Returns
- -------
- :obj:`~hikari.intents.Intent`, optional
- A :obj:`~enum.IntFlag` enum containing each intent that is set. If
- intents are not being used at all, then this will return
- :obj:`~None` instead.
+ If intents are not being used at all, then this will be `None` instead.
"""
return self._config.intents
@property
def version(self) -> float:
- """Version being used for the gateway API.
-
- Returns
- -------
- :obj:`~int`
- The API version being used.
- """
+ """Version being used for the gateway API."""
return self._config.gateway_version
async def start(self):
@@ -290,29 +257,26 @@ async def update_presence(
Any arguments that you do not explicitly provide some value for will
not be changed.
- Warning
- -------
- This will only apply to connected shards.
+ !!! warning
+ This will only apply to connected shards.
- Notes
- -----
- If you wish to update a presence for a specific shard, you can do this
- by using the ``shards`` :obj:`~typing.Mapping` to find the shard you
- wish to update.
+ !!! note
+ If you wish to update a presence for a specific shard, you can do this
+ by using the `shards` `typing.Mapping` to find the shard you wish to
+ update.
Parameters
----------
- status : :obj:`~hikari.guilds.PresenceStatus`
+ status : hikari.guilds.PresenceStatus
If specified, the new status to set.
- activity : :obj:`~hikari.gateway_entities.GatewayActivity`, optional
+ activity : hikari.gateway_entities.Activity, optional
If specified, the new activity to set.
- idle_since : :obj:`~datetime.datetime`, optional
+ idle_since : datetime.datetime, optional
If specified, the time to show up as being idle since,
- or :obj:`~None` if not applicable.
- is_afk : :obj:`~bool`
- If specified, :obj:`~True` if the user should be marked as AFK,
- or :obj:`~False` otherwise.
-
+ or `None` if not applicable.
+ is_afk : bool
+ If specified, `True` if the user should be marked as AFK,
+ or `False` otherwise.
"""
await asyncio.gather(
*(
@@ -331,30 +295,28 @@ def _create_shard(
Parameters
----------
- shard_id : :obj:`~int`
+ shard_id : int
The shard ID to use.
- shard_count : :obj:`~int`
+ shard_count : int
The shard count to use.
- url : :obj:`~str`
+ url : str
The gateway URL to connect to.
- config : :obj:`~hikari.clients.configs.BotConfig`
+ config : hikari.clients.configs.BotConfig
The bot config to use.
- event_manager :obj:`~hikari.state.event_managers.EventManager`
+ event_manager hikari.state.event_managers.EventManager
The event manager to use.
Returns
-------
- :obj:`~hikari.clients.shard_clients.ShardClient`
+ hikari.clients.shards.ShardClient
The shard client implementation to use for the given shard ID.
- Notes
- -----
- The ``shard_id`` and ``shard_count`` may be set within the ``config``
- object passed, but any conforming implementations are expected to
- use the value passed in the ``shard_id` and ``shard_count`` parameters
- regardless. Failure to do so may result in an invalid sharding
- configuration being used.
-
+ !!! note
+ The `shard_id` and `shard_count` may be set within the `config`
+ object passed, but any conforming implementations are expected to
+ use the value passed in the `shard_id` and `shard_count` parameters
+ regardless. Failure to do so may result in an invalid sharding
+ configuration being used.
"""
@classmethod
@@ -364,12 +326,12 @@ def _create_rest(cls, config: BotConfigT) -> RESTClientT:
Parameters
----------
- config : :obj:`~hikari.clients.configs.BotConfig`
+ config : hikari.clients.configs.BotConfig
The bot config to use.
Returns
-------
- :obj:`~hikari.clients.rest.RESTClient`
+ hikari.clients.rest.RESTClient
The REST client to use.
"""
@@ -381,12 +343,12 @@ def _create_event_manager(cls, config: BotConfigT, dispatcher: EventDispatcherT)
Parameters
----------
- config : :obj:`~hikari.clients.configs.BotConfig`
+ config : hikari.clients.configs.BotConfig
The bot config to use.
Returns
-------
- :obj:`~hikari.state.event_managers.EventManager`
+ hikari.state.event_managers.EventManager
The event manager to use internally.
"""
@@ -398,11 +360,10 @@ def _create_event_dispatcher(cls, config: BotConfigT) -> EventDispatcherT:
Parameters
----------
- config : :obj:`~hikari.clients.configs.BotConfig`
+ config : hikari.clients.configs.BotConfig`
The bot config to use.
Returns
-------
- :obj:`~hikari.state.dispatchers.EventDispatcher`
-
+ hikari.state.dispatchers.EventDispatcher
"""
diff --git a/hikari/clients/configs.py b/hikari/clients/configs.py
index 02a515d8e6..13c51afacd 100644
--- a/hikari/clients/configs.py
+++ b/hikari/clients/configs.py
@@ -52,118 +52,106 @@ class BaseConfig(marshaller.Deserializable):
@marshaller.marshallable()
@attr.s(kw_only=True)
class DebugConfig(BaseConfig):
- """Configuration for anything with a debugging mode."""
+ """Configuration for anything with a debugging mode.
+
+ Attributes
+ ----------
+ debug : bool
+ Whether to enable debugging mode. Usually you don't want to enable this.
+ """
- #: Whether to enable debugging mode. Usually you don't want to enable this.
- #:
- #: :type: :obj:`~bool`
debug: bool = marshaller.attrib(deserializer=bool, if_undefined=False, default=False)
@marshaller.marshallable()
@attr.s(kw_only=True)
class AIOHTTPConfig(BaseConfig):
- """Config for components that use AIOHTTP somewhere."""
-
- #: If :obj:`~True`, allow following redirects from ``3xx`` HTTP responses.
- #: Generally you do not want to enable this unless you have a good reason
- #: to.
- #:
- #: Defaults to :obj:`~False` if unspecified during deserialization.
- #:
- #: :type: :obj:`~bool`
+ """Config for components that use AIOHTTP somewhere.
+
+ Attributes
+ ----------
+ allow_redirects : bool
+ If `True`, allow following redirects from `3xx` HTTP responses.
+ Generally you do not want to enable this unless you have a good reason to.
+ Defaults to `False` if unspecified during deserialization.
+ tcp_connector : aiohttp.TCPConnector, optional
+ This may otherwise be `None` to use the default settings provided by
+ `aiohttp`.
+ This is deserialized as an object reference in the format
+ `package.module#object.attribute` that is expected to point to the
+ desired value.
+ Defaults to `None` if unspecified during deserialization.
+ proxy_headers : typing.Mapping [ str, str ], optional
+ Optional proxy headers to provide in any HTTP requests.
+ Defaults to `None` if unspecified during deserialization.
+ proxy_auth : aiohttp.BasicAuth, optional
+ Optional proxy authorization to provide in any HTTP requests.
+ This is deserialized using the format `"basic {{base 64 string here}}"`.
+ Defaults to `None` if unspecified during deserialization.
+ proxy_url : str, optional
+ The optional URL of the proxy to send requests via.
+ Defaults to `None` if unspecified during deserialization.
+ request_timeout : float, optional
+ Optional request timeout to use. If an HTTP request takes longer than
+ this, it will be aborted.
+ If not `None`, the value represents a number of seconds as a floating
+ point number.
+ Defaults to `None` if unspecified during deserialization.
+ ssl_context : ssl.SSLContext, optional
+ The optional SSL context to use.
+ This is deserialized as an object reference in the format
+ `package.module#object.attribute` that is expected to point to the
+ desired value.
+ Defaults to `None` if unspecified during deserialization.
+ verify_ssl : bool
+ If `True`, then responses with invalid SSL certificates will be
+ rejected. Generally you want to keep this enabled unless you have a
+ problem with SSL and you know exactly what you are doing by disabling
+ this. Disabling SSL verification can have major security implications.
+ You turn this off at your own risk.
+ Defaults to `True` if unspecified during deserialization.
+ """
+
allow_redirects: bool = marshaller.attrib(deserializer=bool, if_undefined=False, default=False)
- #: Either an implementation of :obj:`~aiohttp.TCPConnector`.
- #:
- #: This may otherwise be :obj:`~None` to use the default settings provided
- #: by :mod:`aiohttp`.
- #:
- #: This is deserialized as an object reference in the format
- #: ``package.module#object.attribute`` that is expected to point to the
- #: desired value.
- #:
- #: Defaults to :obj:`~None` if unspecified during deserialization.
- #:
- #: :type: :obj:`~aiohttp.TCPConnector`, optional
tcp_connector: typing.Optional[aiohttp.TCPConnector] = marshaller.attrib(
deserializer=marshaller.dereference_handle, if_none=None, if_undefined=None, default=None
)
- #: Optional proxy headers to provide in any HTTP requests.
- #:
- #: Defaults to :obj:`~None` if unspecified during deserialization.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~str`, :obj:`~str` ], optional
proxy_headers: typing.Optional[typing.Mapping[str, str]] = marshaller.attrib(
deserializer=dict, if_none=None, if_undefined=None, default=None
)
- #: Optional proxy authorization to provide in any HTTP requests.
- #:
- #: This is deserialized using the format ``"basic {{base 64 string here}}"``.
- #:
- #: Defaults to :obj:`~None` if unspecified during deserialization.
- #:
- #: :type: :obj:`~aiohttp.BasicAuth`, optional
proxy_auth: typing.Optional[aiohttp.BasicAuth] = marshaller.attrib(
deserializer=aiohttp.BasicAuth.decode, if_none=None, if_undefined=None, default=None
)
- #: The optional URL of the proxy to send requests via.
- #:
- #: Defaults to :obj:`~None` if unspecified during deserialization.
- #:
- #: :type: :obj:`~str`, optional
proxy_url: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, if_none=None, default=None)
- #: Optional request timeout to use. If an HTTP request takes longer than
- #: this, it will be aborted.
- #:
- #: If not :obj:`~None`, the value represents a number of seconds as a
- #: floating point number.
- #:
- #: Defaults to :obj:`~None` if unspecified during deserialization.
- #:
- #: :type: :obj:`~float`, optional
request_timeout: typing.Optional[float] = marshaller.attrib(
deserializer=float, if_undefined=None, if_none=None, default=None
)
- #: The optional SSL context to use.
- #:
- #: This is deserialized as an object reference in the format
- #: ``package.module#object.attribute`` that is expected to point to the
- #: desired value.
- #:
- #: Defaults to :obj:`~None` if unspecified during deserialization.
- #:
- #: :type: :obj:`~ssl.SSLContext`, optional
ssl_context: typing.Optional[ssl.SSLContext] = marshaller.attrib(
deserializer=marshaller.dereference_handle, if_none=None, if_undefined=None, default=None
)
- #: If :obj:`~True`, then responses with invalid SSL certificates will be
- #: rejected. Generally you want to keep this enabled unless you have a
- #: problem with SSL and you know exactly what you are doing by disabling
- #: this. Disabling SSL verification can have major security implications.
- #: You turn this off at your own risk.
- #:
- #: Defaults to :obj:`~True` if unspecified during deserialization.
- #:
- #: :type: :obj:`~bool`
verify_ssl: bool = marshaller.attrib(deserializer=bool, if_undefined=True, default=True)
@marshaller.marshallable()
@attr.s(kw_only=True)
class TokenConfig(BaseConfig):
- """Token config options."""
+ """Token config options.
+
+ Attributes
+ ----------
+ token : str, optional
+ The token to use.
+ """
- #: The token to use.
- #:
- #: :type: :obj:`~str`, optional
token: typing.Optional[str] = marshaller.attrib(deserializer=str, if_none=None, if_undefined=None, default=None)
+ """The token to use."""
def _parse_shard_info(payload):
@@ -189,160 +177,334 @@ def _parse_shard_info(payload):
@marshaller.marshallable()
@attr.s(kw_only=True)
class GatewayConfig(AIOHTTPConfig, TokenConfig, DebugConfig):
- """Single-websocket specific configuration options."""
+ """Single-websocket specific configuration options.
+
+ Attributes
+ ----------
+ allow_redirects : bool
+ If `True`, allow following redirects from `3xx` HTTP responses.
+ Generally you do not want to enable this unless you have a good reason to.
+ Defaults to `False` if unspecified during deserialization.
+ tcp_connector : aiohttp.TCPConnector, optional
+ This may otherwise be `None` to use the default settings provided by
+ `aiohttp`.
+ This is deserialized as an object reference in the format
+ `package.module#object.attribute` that is expected to point to the
+ desired value.
+ Defaults to `None` if unspecified during deserialization.
+ proxy_headers : typing.Mapping [ str, str ], optional
+ Optional proxy headers to provide in any HTTP requests.
+ Defaults to `None` if unspecified during deserialization.
+ proxy_auth : aiohttp.BasicAuth, optional
+ Optional proxy authorization to provide in any HTTP requests.
+ This is deserialized using the format `"basic {{base 64 string here}}"`.
+ Defaults to `None` if unspecified during deserialization.
+ proxy_url : str, optional
+ The optional URL of the proxy to send requests via.
+ Defaults to `None` if unspecified during deserialization.
+ request_timeout : float, optional
+ Optional request timeout to use. If an HTTP request takes longer than
+ this, it will be aborted.
+ If not `None`, the value represents a number of seconds as a floating
+ point number.
+ Defaults to `None` if unspecified during deserialization.
+ ssl_context : ssl.SSLContext, optional
+ The optional SSL context to use.
+ This is deserialized as an object reference in the format
+ `package.module#object.attribute` that is expected to point to the
+ desired value.
+ Defaults to `None` if unspecified during deserialization.
+ verify_ssl : bool
+ If `True`, then responses with invalid SSL certificates will be
+ rejected. Generally you want to keep this enabled unless you have a
+ problem with SSL and you know exactly what you are doing by disabling
+ this. Disabling SSL verification can have major security implications.
+ You turn this off at your own risk.
+ Defaults to `True` if unspecified during deserialization.
+ token : str, optional
+ The token to use.
+ debug : bool
+ Whether to enable debugging mode. Usually you don't want to enable this.
+ gateway_use_compression : bool
+ Whether to use zlib compression on the gateway for inbound messages.
+ Usually you want this turned on.
+ gateway_version : int
+ The gateway API version to use. Defaults to v6
+ initial_activity : hikari.gateway_entities.Activity, optional
+ The initial activity to set all shards to when starting the gateway.
+ If this is `None` then no activity will be set, this is the default.
+ initial_status : hikari.guilds.PresenceStatus
+ The initial status to set the shards to when starting the gateway.
+ Defaults to `ONLINE`.
+ initial_is_afk : bool
+ Whether to show up as AFK or not on sign-in.
+ initial_idle_since : datetime.datetime, optional
+ The idle time to show on signing in.
+ If set to `None` to not show an idle time, this is the default.
+ intents : hikari.intents.Intent
+ The intents to use for the connection.
+ If being deserialized, this can be an integer bitfield, or a sequence of
+ intent names. If unspecified, this will be set to `None`.
+ large_threshold : int
+ The large threshold to use.
+ shard_id : typing.Sequence [ int ], optional
+ The shard IDs to produce shard connections for.
+ If being deserialized, this can be several formats shown in `notes`.
+ shard_count : int, optional
+ The number of shards the entire distributed application should consists
+ of. If you run multiple distributed instances of the bot, you should
+ ensure this value is consistent.
+ This can be set to `None` to enable auto-sharding. This is the default.
+
+ !!! note
+ The several formats for `shard_id` are as follows:
+
+ * A specific shard ID (e.g. `12`);
+ * A sequence of shard IDs (e.g. `[0, 1, 2, 3, 8, 9, 10]`);
+ * A range string. Two periods indicate a range of `[5, 16]`
+ (inclusive beginning, exclusive end).
+ * A range string. Three periods indicate a range of
+ `[5, 17]` (inclusive beginning, inclusive end);
+ * `None` this means `shard_count` will be considered and that many
+ shards will be created for you. If the `shard_count` is also
+ `None` then auto-sharding will be performed for you.
+
+ !!! note
+
+ If being deserialized, `intents` can be an integer bitfield, or a
+ sequence of intent names. If unspecified, `intents` will be set to
+ `None`.
+
+ See `hikari.intents.Intent` for valid names of intents you
+ can use. Integer values are as documented on Discord's developer portal.
+
+ !!! warning
+ If you are using the V7 gateway implementation, you will NEED to provide
+ explicit `intents` values for this field in order to get online.
+ Additionally, intents that are classed by Discord as being privileged
+ will require you to whitelist your application in order to use them.
+
+ If you are using the V6 gateway implementation, setting `intents` to
+ `None` will simply opt you into every event you can subscribe to.
+ """
- #: Whether to use zlib compression on the gateway for inbound messages or
- #: not. Usually you want this turned on.
- #:
- #: :type: :obj:`~bool`
gateway_use_compression: bool = marshaller.attrib(deserializer=bool, if_undefined=True, default=True)
- #: The gateway API version to use.
- #:
- #: If unspecified, then V6 is used.
- #:
- #: :type: :obj:`~int`
gateway_version: int = marshaller.attrib(deserializer=int, if_undefined=lambda: 6, default=6)
- #: The initial activity to set all shards to when starting the gateway. If
- #: :obj:`~None`, then no activity will be set.
- #:
- #: :type: :obj:`~hikari.gateway_entities.GatewayActivity`, optional
initial_activity: typing.Optional[gateway_entities.Activity] = marshaller.attrib(
deserializer=gateway_entities.Activity.deserialize, if_none=None, if_undefined=None, default=None
)
- #: The initial status to set the shards to when starting the gateway.
- #:
- #: :type: :obj:`~hikari.guilds.PresenceStatus`
initial_status: guilds.PresenceStatus = marshaller.attrib(
deserializer=guilds.PresenceStatus,
if_undefined=lambda: guilds.PresenceStatus.ONLINE,
default=guilds.PresenceStatus.ONLINE,
)
- #: Whether to show up as AFK or not on sign-in.
- #:
- #: :type: :obj:`~bool`
initial_is_afk: bool = marshaller.attrib(deserializer=bool, if_undefined=False, default=False)
- #: The idle time to show on signing in, or :obj:`~None` to not show an idle
- #: time.
- #:
- #: :type: :obj:`~datetime.datetime`, optional
initial_idle_since: typing.Optional[datetime.datetime] = marshaller.attrib(
deserializer=datetime.datetime.fromtimestamp, if_none=None, if_undefined=None, default=None
)
- #: The intents to use for the connection.
- #:
- #: If being deserialized, this can be an integer bitfield, or a sequence of
- #: intent names. If
- #: unspecified, this will be set to :obj:`~None`.
- #:
- #: Examples
- #: --------
- #:
- #: .. code-block:: python
- #:
- #: # Python example
- #: GatewayIntent.GUILDS | GatewayIntent.GUILD_MESSAGES
- #:
- #: .. code-block:: js
- #:
- #: // JSON example, using explicit bitfield values
- #: 513
- #: // JSON example, using an array of names
- #: [ "GUILDS", "GUILD_MESSAGES" ]
- #:
- #: See :obj:`~hikari.intents.Intent` for valid names of
- #: intents you can use. Integer values are as documented on Discord's
- #: developer portal.
- #:
- #: Warnings
- #: --------
- #: If you are using the V7 gateway implementation, you will NEED to provide
- #: explicit intent values for this field in order to get online.
- #: Additionally, intents that are classed by Discord as being privileged
- #: will require you to whitelist your application in order to use them.
- #:
- #: If you are using the V6 gateway implementation, setting this to
- #: :obj:`~None` will simply opt you into every event you can subscribe to.
- #:
- #:
- #: :type: :obj:`~hikari.intents.Intent`, optional
intents: typing.Optional[_intents.Intent] = marshaller.attrib(
deserializer=lambda value: conversions.dereference_int_flag(_intents.Intent, value),
if_undefined=None,
default=None,
)
- #: The large threshold to use.
- #:
- #: :type: :obj:`~int`
large_threshold: int = marshaller.attrib(deserializer=int, if_undefined=lambda: 250, default=250)
"""Definition of shard management configuration settings."""
- #: The shard IDs to produce shard connections for.
- #:
- #: If being deserialized, this can be several formats.
- #: ``12``:
- #: A specific shard ID.
- #: ``[0, 1, 2, 3, 8, 9, 10]``:
- #: A sequence of shard IDs.
- #: ``"5..16"``:
- #: A range string. Two periods indicate a range of ``[5, 16)``
- #: (inclusive beginning, exclusive end).
- #: ``"5...16"``:
- #: A range string. Three periods indicate a range of
- #: ``[5, 17]`` (inclusive beginning, inclusive end).
- #: :obj:`~None`:
- #: The ``shard_count`` will be considered and that many shards will
- #: be created for you. If the ``shard_count`` is also :obj:`~None`,
- #: then auto-sharding will be performed for you.
- #:
- #: :type: :obj:`~typing.Sequence` [ :obj:`~int` ], optional
shard_ids: typing.Optional[typing.Sequence[int]] = marshaller.attrib(
deserializer=_parse_shard_info, if_none=None, if_undefined=None, default=None
)
- #: The number of shards the entire distributed application should consist
- #: of. If you run multiple distributed instances of the bot, you should
- #: ensure this value is consistent.
- #:
- #: This can be set to :obj:`~None` to enable auto-sharding. This is the
- #: default behaviour.
- #:
- #: :type: :obj:`~int`, optional.
shard_count: typing.Optional[int] = marshaller.attrib(deserializer=int, if_undefined=None, default=None)
@marshaller.marshallable()
@attr.s(kw_only=True)
class RESTConfig(AIOHTTPConfig, TokenConfig):
- """REST-specific configuration details."""
-
- #: Token authentication scheme.
- #:
- #: Should be ``"Bot"`` or ``"Bearer"``, or ``None`` if not relevant.
- #:
- #: Defaults to ``"Bot"``
- #:
- #: :type: :obj:`~str`, optional
+ """Single-websocket specific configuration options.
+
+ Attributes
+ ----------
+ allow_redirects : bool
+ If `True`, allow following redirects from `3xx` HTTP responses.
+ Generally you do not want to enable this unless you have a good reason to.
+ Defaults to `False` if unspecified during deserialization.
+ tcp_connector : aiohttp.TCPConnector, optional
+ This may otherwise be `None` to use the default settings provided by
+ `aiohttp`.
+ This is deserialized as an object reference in the format
+ `package.module#object.attribute` that is expected to point to the
+ desired value.
+ Defaults to `None` if unspecified during deserialization.
+ proxy_headers : typing.Mapping [ str, str ], optional
+ Optional proxy headers to provide in any HTTP requests.
+ Defaults to `None` if unspecified during deserialization.
+ proxy_auth : aiohttp.BasicAuth, optional
+ Optional proxy authorization to provide in any HTTP requests.
+ This is deserialized using the format `"basic {{base 64 string here}}"`.
+ Defaults to `None` if unspecified during deserialization.
+ proxy_url : str, optional
+ The optional URL of the proxy to send requests via.
+ Defaults to `None` if unspecified during deserialization.
+ request_timeout : float, optional
+ Optional request timeout to use. If an HTTP request takes longer than
+ this, it will be aborted.
+ If not `None`, the value represents a number of seconds as a floating
+ point number.
+ Defaults to `None` if unspecified during deserialization.
+ ssl_context : ssl.SSLContext, optional
+ The optional SSL context to use.
+ This is deserialized as an object reference in the format
+ `package.module#object.attribute` that is expected to point to the
+ desired value.
+ Defaults to `None` if unspecified during deserialization.
+ verify_ssl : bool
+ If `True`, then responses with invalid SSL certificates will be
+ rejected. Generally you want to keep this enabled unless you have a
+ problem with SSL and you know exactly what you are doing by disabling
+ this. Disabling SSL verification can have major security implications.
+ You turn this off at your own risk.
+ Defaults to `True` if unspecified during deserialization.
+ token : str, optional
+ The token to use.
+ debug : bool
+ Whether to enable debugging mode. Usually you don't want to enable this.
+ token_type : str, optional
+ Token authentication scheme, this defaults to `"Bot"` and should be
+ one of `"Bot"` or `"Bearer"`, or `None` if not relevant.
+ rest_version : int
+ The HTTP API version to use. If unspecified, then V7 is used.
+ """
+
token_type: typing.Optional[str] = marshaller.attrib(
deserializer=str, if_undefined=lambda: "Bot", if_none=None, default="Bot"
)
- #: The HTTP API version to use.
- #:
- #: If unspecified, then V7 is used.
- #:
- #: :type: :obj:`~int`
rest_version: int = marshaller.attrib(deserializer=int, if_undefined=lambda: 7, default=7)
@marshaller.marshallable()
@attr.s(kw_only=True)
class BotConfig(RESTConfig, GatewayConfig):
- """Configuration for a standard bot."""
+ """Configuration for a standard bot.
+
+ Attributes
+ ----------
+ allow_redirects : bool
+ If `True`, allow following redirects from `3xx` HTTP responses.
+ Generally you do not want to enable this unless you have a good reason to.
+ Defaults to `False` if unspecified during deserialization.
+ tcp_connector : aiohttp.TCPConnector, optional
+ This may otherwise be `None` to use the default settings provided by
+ `aiohttp`.
+ This is deserialized as an object reference in the format
+ `package.module#object.attribute` that is expected to point to the
+ desired value.
+ Defaults to `None` if unspecified during deserialization.
+ proxy_headers : typing.Mapping [ str, str ], optional
+ Optional proxy headers to provide in any HTTP requests.
+ Defaults to `None` if unspecified during deserialization.
+ proxy_auth : aiohttp.BasicAuth, optional
+ Optional proxy authorization to provide in any HTTP requests.
+ This is deserialized using the format `"basic {{base 64 string here}}"`.
+ Defaults to `None` if unspecified during deserialization.
+ proxy_url : str, optional
+ The optional URL of the proxy to send requests via.
+ Defaults to `None` if unspecified during deserialization.
+ request_timeout : float, optional
+ Optional request timeout to use. If an HTTP request takes longer than
+ this, it will be aborted.
+ If not `None`, the value represents a number of seconds as a floating
+ point number.
+ Defaults to `None` if unspecified during deserialization.
+ ssl_context : ssl.SSLContext, optional
+ The optional SSL context to use.
+ This is deserialized as an object reference in the format
+ `package.module#object.attribute` that is expected to point to the
+ desired value.
+ Defaults to `None` if unspecified during deserialization.
+ verify_ssl : bool
+ If `True`, then responses with invalid SSL certificates will be
+ rejected. Generally you want to keep this enabled unless you have a
+ problem with SSL and you know exactly what you are doing by disabling
+ this. Disabling SSL verification can have major security implications.
+ You turn this off at your own risk.
+ Defaults to `True` if unspecified during deserialization.
+ token : str, optional
+ The token to use.
+ debug : bool
+ Whether to enable debugging mode. Usually you don't want to enable this.
+ gateway_use_compression : bool
+ Whether to use zlib compression on the gateway for inbound messages.
+ Usually you want this turned on.
+ gateway_version : int
+ The gateway API version to use. Defaults to v6
+ initial_activity : hikari.gateway_entities.Activity, optional
+ The initial activity to set all shards to when starting the gateway.
+ If this is `None` then no activity will be set, this is the default.
+ initial_status : hikari.guilds.PresenceStatus
+ The initial status to set the shards to when starting the gateway.
+ Defaults to `ONLINE`.
+ initial_is_afk : bool
+ Whether to show up as AFK or not on sign-in.
+ initial_idle_since : datetime.datetime, optional
+ The idle time to show on signing in.
+ If set to `None` to not show an idle time, this is the default.
+ intents : hikari.intents.Intent
+ The intents to use for the connection.
+ If being deserialized, this can be an integer bitfield, or a sequence of
+ intent names. If unspecified, this will be set to `None`.
+ large_threshold : int
+ The large threshold to use.
+ shard_id : typing.Sequence [ int ], optional
+ The shard IDs to produce shard connections for.
+ If being deserialized, this can be several formats shown in `notes`.
+ shard_count : int, optional
+ The number of shards the entire distributed application should consists
+ of. If you run multiple distributed instances of the bot, you should
+ ensure this value is consistent.
+ This can be set to `None` to enable auto-sharding. This is the default.
+ token_type : str, optional
+ Token authentication scheme, this defaults to `"Bot"` and should be
+ one of `"Bot"` or `"Bearer"`, or `None` if not relevant.
+ rest_version : int
+ The HTTP API version to use. If unspecified, then V7 is used.
+
+ !!! note
+ The several formats for `shard_id` are as follows:
+
+ * A specific shard ID (e.g. `12`);
+ * A sequence of shard IDs (e.g. `[0, 1, 2, 3, 8, 9, 10]`);
+ * A range string. Two periods indicate a range of `[5, 16]`
+ (inclusive beginning, exclusive end).
+ * A range string. Three periods indicate a range of
+ `[5, 17]` (inclusive beginning, inclusive end);
+ * `None` this means `shard_count` will be considered and that many
+ shards will be created for you. If the `shard_count` is also
+ `None` then auto-sharding will be performed for you.
+
+ !!! note
+
+ If being deserialized, `intents` can be an integer bitfield, or a
+ sequence of intent names. If unspecified, `intents` will be set to
+ `None`.
+
+ See `hikari.intents.Intent` for valid names of intents you
+ can use. Integer values are as documented on Discord's developer portal.
+
+ !!! warning
+ If you are using the V7 gateway implementation, you will NEED to provide
+ explicit `intents` values for this field in order to get online.
+ Additionally, intents that are classed by Discord as being privileged
+ will require you to whitelist your application in order to use them.
+
+ If you are using the V6 gateway implementation, setting `intents` to
+ `None` will simply opt you into every event you can subscribe to.
+ """
diff --git a/hikari/clients/rest/__init__.py b/hikari/clients/rest/__init__.py
index 99b4216e6d..904fa028f0 100644
--- a/hikari/clients/rest/__init__.py
+++ b/hikari/clients/rest/__init__.py
@@ -54,19 +54,18 @@ class RESTClient(
A marshalling object-oriented REST API client.
This client bridges the basic REST API exposed by
- `hikari.net.rest_sessions.LowLevelRestfulClient` and wraps it in a unit of
- processing that can handle parsing API objects into Hikari entity objects.
+ `hikari.net.rest.REST` and wraps it in a unit of processing that can handle
+ handle parsing API objects into Hikari entity objects.
Parameters
----------
- config : `hikari.clients.configs.RESTConfig`
+ config : hikari.clients.configs.RESTConfig
A HTTP configuration object.
- Note
- ----
- For all endpoints where a `reason` argument is provided, this may be a
- string inclusively between `0` and `512` characters length, with any
- additional characters being cut off.
+ !!! note
+ For all endpoints where a `reason` argument is provided, this may be a
+ string inclusively between `0` and `512` characters length, with any
+ additional characters being cut off.
"""
def __init__(self, config: configs.RESTConfig) -> None:
diff --git a/hikari/clients/rest/base.py b/hikari/clients/rest/base.py
index 3e2b9cbc55..9d3921d7ec 100644
--- a/hikari/clients/rest/base.py
+++ b/hikari/clients/rest/base.py
@@ -32,8 +32,8 @@ class BaseRESTComponent(abc.ABC, metaclass=meta.UniqueFunctionMeta):
"""An abstract class that all REST client logic classes should inherit from.
This defines the abstract method `__init__` which will assign an instance
- of `hikari.net.rest_sessions.LowLevelRestfulClient` to the attribute that
- all components will expect to make calls to.
+ of `hikari.net.rest.REST` to the attribute that all components will expect
+ to make calls to.
"""
@abc.abstractmethod
diff --git a/hikari/clients/rest/channel.py b/hikari/clients/rest/channel.py
index b6e95b8607..2d5e2f8a07 100644
--- a/hikari/clients/rest/channel.py
+++ b/hikari/clients/rest/channel.py
@@ -50,22 +50,22 @@ async def fetch_channel(self, channel: bases.Hashable[_channels.Channel]) -> _ch
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object ID of the channel to look up.
Returns
-------
- :obj:`~hikari.channels.Channel`
+ hikari.channels.Channel
The channel object that has been found.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you don't have access to the channel.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel does not exist.
"""
payload = await self._session.get_channel(
@@ -92,59 +92,59 @@ async def update_channel(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The channel ID to update.
- name : :obj:`~str`
+ name : str
If specified, the new name for the channel. This must be
- inclusively between ``1`` and ``100`` characters in length.
- position : :obj:`~int`
+ inclusively between `1` and `100` characters in length.
+ position : int
If specified, the position to change the channel to.
- topic : :obj:`~str`
+ topic : str
If specified, the topic to set. This is only applicable to
- text channels. This must be inclusively between ``0`` and ``1024``
+ text channels. This must be inclusively between `0` and `1024`
characters in length.
- nsfw : :obj:`~bool`
- Mark the channel as being not safe for work (NSFW) if :obj:`~True`.
- If :obj:`~False` or unspecified, then the channel is not marked as
+ nsfw : bool
+ Mark the channel as being not safe for work (NSFW) if `True`.
+ If `False` or unspecified, then the channel is not marked as
NSFW. Will have no visible effect for non-text guild channels.
- rate_limit_per_user : :obj:`~typing.Union` [ :obj:`~int`, :obj:`~datetime.timedelta` ]
+ rate_limit_per_user : typing.Union [ int, datetime.timedelta ]
If specified, the time delta of seconds the user has to wait
before sending another message. This will not apply to bots, or to
- members with ``MANAGE_MESSAGES`` or ``MANAGE_CHANNEL`` permissions.
- This must be inclusively between ``0`` and ``21600`` seconds.
- bitrate : :obj:`~int`
+ members with `MANAGE_MESSAGES` or `MANAGE_CHANNEL` permissions.
+ This must be inclusively between `0` and `21600` seconds.
+ bitrate : int
If specified, the bitrate in bits per second allowable for the
channel. This only applies to voice channels and must be inclusively
- between ``8000`` and ``96000`` for normal servers or ``8000`` and
- ``128000`` for VIP servers.
- user_limit : :obj:`~int`
+ between `8000` and `96000` for normal servers or `8000` and
+ `128000` for VIP servers.
+ user_limit : int
If specified, the new max number of users to allow in a voice
- channel. This must be between ``0`` and ``99`` inclusive, where
- ``0`` implies no limit.
- permission_overwrites : :obj:`~typing.Sequence` [ :obj:`~hikari.channels.PermissionOverwrite` ]
+ channel. This must be between `0` and `99` inclusive, where
+ `0` implies no limit.
+ permission_overwrites : typing.Sequence [ hikari.channels.PermissionOverwrite ]
If specified, the new list of permission overwrites that are
category specific to replace the existing overwrites with.
- parent_category : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ], optional
+ parent_category : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ], optional
If specified, the new parent category ID to set for the channel,
- pass :obj:`~None` to unset.
- reason : :obj:`~str`
+ pass `None` to unset.
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~hikari.channels.Channel`
+ hikari.channels.Channel
The channel object that has been modified.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel does not exist.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack the permission to make the change.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If you provide incorrect options for the corresponding channel type
- (e.g. a ``bitrate`` for a text channel).
+ (e.g. a `bitrate` for a text channel).
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
"""
@@ -178,35 +178,33 @@ async def delete_channel(self, channel: bases.Hashable[_channels.Channel]) -> No
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake` :obj:`~str` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake str ]
The object or ID of the channel to delete.
Returns
-------
- :obj:`~None`
+ None
Nothing, unlike what the API specifies. This is done to maintain
consistency with other calls of a similar nature in this API
wrapper.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel does not exist.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you do not have permission to delete the channel.
- Note
- ----
- Closing a DM channel won't raise an exception but will have no effect
- and "closed" DM channels will not have to be reopened to send messages
- in theme.
+ !!! note
+ Closing a DM channel won't raise an exception but will have no
+ effect and "closed" DM channels will not have to be reopened to send
+ messages in theme.
- Warning
- -------
- Deleted channels cannot be un-deleted.
+ !!! warning
+ Deleted channels cannot be un-deleted.
"""
await self._session.delete_close_channel(
channel_id=str(channel.id if isinstance(channel, bases.UniqueEntity) else int(channel))
@@ -226,45 +224,43 @@ def fetch_messages_after(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The ID of the channel to retrieve the messages from.
- limit : :obj:`~int`
+ limit : int
If specified, the maximum number of how many messages this iterator
should return.
- after : :obj:`~typing.Union` [ :obj:`~datetime.datetime`, :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ after : typing.Union [ datetime.datetime, hikari.channels.Channel, hikari.bases.Snowflake, int ]
A object or ID message. Only return messages sent AFTER this
message if it's specified else this will return every message after
(and including) the first message in the channel.
- Example
- -------
-
+ Examples
+ --------
async for message in client.fetch_messages_after(channel, after=9876543, limit=3232):
if message.author.id in BLACKLISTED_USERS:
await client.ban_member(channel.guild_id, message.author)
Returns
-------
- :obj:`~typing.AsyncIterator` [ :obj:`~hikari.messages.Message` ]
+ typing.AsyncIterator [ hikari.messages.Message ]
An async iterator that retrieves the channel's message objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permission to read the channel.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found, or the message
provided for one of the filter arguments is not found.
- Note
- ----
- If you are missing the ``VIEW_CHANNEL`` permission, you will receive a
- :obj:`~hikari.errors.ForbiddenHTTPError`. If you are instead missing
- the ``READ_MESSAGE_HISTORY`` permission, you will always receive
- zero results, and thus an empty list will be returned instead.
+ !!! note
+ If you are missing the `VIEW_CHANNEL` permission, you will receive a
+ hikari.errors.ForbiddenHTTPError. If you are instead missing
+ the `READ_MESSAGE_HISTORY` permission, you will always receive
+ zero results, and thus an empty list will be returned instead.
"""
if isinstance(after, datetime.datetime):
after = str(bases.Snowflake.from_datetime(after))
@@ -294,47 +290,44 @@ def fetch_messages_before(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The ID of the channel to retrieve the messages from.
- limit : :obj:`~int`
+ limit : int
If specified, the maximum number of how many messages this iterator
should return.
- before : :obj:`~typing.Union` [ :obj:`~datetime.datetime`, :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ before : typing.Union [ datetime.datetime, hikari.channels.Channel, hikari.bases.Snowflake, int ]
A message object or ID. Only return messages sent BEFORE
this message if this is specified else this will return every
message before (and including) the most recent message in the
channel.
- Example
- -------
- .. code-block:: python
-
+ Examples
+ --------
async for message in client.fetch_messages_before(channel, before=9876543, limit=1231):
if message.content.lower().contains("delete this"):
await client.delete_message(channel, message)
Returns
-------
- :obj:`~typing.AsyncIterator` [ :obj:`~hikari.messages.Message` ]
+ typing.AsyncIterator [ hikari.messages.Message ]
An async iterator that retrieves the channel's message objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permission to read the channel.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found, or the message
provided for one of the filter arguments is not found.
- Note
- ----
- If you are missing the ``VIEW_CHANNEL`` permission, you will receive a
- :obj:`~hikari.errors.ForbiddenHTTPError`. If you are instead missing
- the ``READ_MESSAGE_HISTORY`` permission, you will always receive
- zero results, and thus an empty list will be returned instead.
+ !!! note
+ If you are missing the `VIEW_CHANNEL` permission, you will receive a
+ hikari.errors.ForbiddenHTTPError. If you are instead missing
+ the `READ_MESSAGE_HISTORY` permission, you will always receive
+ zero results, and thus an empty list will be returned instead.
"""
if isinstance(before, datetime.datetime):
before = str(bases.Snowflake.from_datetime(before))
@@ -365,47 +358,44 @@ async def fetch_messages_around(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The ID of the channel to retrieve the messages from.
- around : :obj:`~typing.Union` [ :obj:`~datetime.datetime`, :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ around : typing.Union [ datetime.datetime, hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the message to get messages that were sent
- AROUND it in the provided channel, unlike ``before`` and ``after``,
+ AROUND it in the provided channel, unlike `before` and `after`,
this argument is required and the provided message will also be
returned if it still exists.
- limit : :obj:`~int`
+ limit : int
If specified, the maximum number of how many messages this iterator
should return, cannot be more than `100`
- Example
- -------
- .. code-block:: python
-
+ Examples
+ --------
async for message in client.fetch_messages_around(channel, around=9876543, limit=42):
if message.embeds and not message.author.is_bot:
await client.delete_message(channel, message)
Returns
-------
- :obj:`~typing.AsyncIterator` [ :obj:`~hikari.messages.Message` ]
+ typing.AsyncIterator [ hikari.messages.Message ]
An async iterator that retrieves the found message objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permission to read the channel.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found, or the message
provided for one of the filter arguments is not found.
- Note
- ----
- If you are missing the ``VIEW_CHANNEL`` permission, you will receive a
- :obj:`~hikari.errors.ForbiddenHTTPError`. If you are instead missing
- the ``READ_MESSAGE_HISTORY`` permission, you will always receive
- zero results, and thus an empty list will be returned instead.
+ !!! note
+ If you are missing the `VIEW_CHANNEL` permission, you will receive a
+ `hikari.errors.ForbiddenHTTPError`. If you are instead missing
+ the `READ_MESSAGE_HISTORY` permission, you will always receive
+ zero results, and thus an empty list will be returned instead.
"""
if isinstance(around, datetime.datetime):
around = str(bases.Snowflake.from_datetime(around))
@@ -425,28 +415,27 @@ async def fetch_message(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to get the message from.
- message : :obj:`~typing.Union` [ :obj:`~hikari.messages.Message`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ message : typing.Union [ hikari.messages.Message, hikari.bases.Snowflake, int ]
The object or ID of the message to retrieve.
Returns
-------
- :obj:`~hikari.messages.Message`
+ hikari.messages.Message
The found message object.
- Note
- ----
- This requires the ``READ_MESSAGE_HISTORY`` permission.
+ !!! note
+ This requires the `READ_MESSAGE_HISTORY` permission.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permission to see the message.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found.
"""
payload = await self._session.get_channel_message(
@@ -472,54 +461,54 @@ async def create_message(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The channel or ID of the channel to send to.
- content : :obj:`~str`
+ content : str
If specified, the message content to send with the message.
- nonce : :obj:`~str`
+ nonce : str
If specified, an optional ID to send for opportunistic message
creation. This doesn't serve any real purpose for general use,
and can usually be ignored.
- tts : :obj:`~bool`
+ tts : bool
If specified, whether the message will be sent as a TTS message.
- files : :obj:`~typing.Collection` [ ``hikari.media.IO`` ]
- If specified, this should be a list of inclusively between ``1`` and
- ``5`` IO like media objects, as defined in :mod:`hikari.media`.
- embed : :obj:`~hikari.embeds.Embed`
+ files : typing.Collection [ `hikari.media.IO` ]
+ If specified, this should be a list of inclusively between `1` and
+ `5` IO like media objects, as defined in `hikari.media`.
+ embed : hikari.embeds.Embed
If specified, the embed object to send with the message.
- mentions_everyone : :obj:`~bool`
- Whether ``@everyone`` and ``@here`` mentions should be resolved by
- discord and lead to actual pings, defaults to :obj:`~True`.
- user_mentions : :obj:`~typing.Union` [ :obj:`~typing.Collection` [ :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ], :obj:`~bool` ]
+ mentions_everyone : bool
+ Whether `@everyone` and `@here` mentions should be resolved by
+ discord and lead to actual pings, defaults to `True`.
+ user_mentions : typing.Union [ typing.Collection [ typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ], bool ]
Either an array of user objects/IDs to allow mentions for,
- :obj:`~True` to allow all user mentions or :obj:`~False` to block all
- user mentions from resolving, defaults to :obj:`~True`.
- role_mentions : :obj:`~typing.Union` [ :obj:`~typing.Collection` [ :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ] ], :obj:`~bool` ]
+ `True` to allow all user mentions or `False` to block all
+ user mentions from resolving, defaults to `True`.
+ role_mentions : typing.Union [ typing.Collection [ typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ] ], bool ]
Either an array of guild role objects/IDs to allow mentions for,
- :obj:`~True` to allow all role mentions or :obj:`~False` to block all
- role mentions from resolving, defaults to :obj:`~True`.
+ `True` to allow all role mentions or `False` to block all
+ role mentions from resolving, defaults to `True`.
Returns
-------
- :obj:`~hikari.messages.Message`
+ hikari.messages.Message
The created message object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
This can be raised if the file is too large; if the embed exceeds
the defined limits; if the message content is specified only and
- empty or greater than ``2000`` characters; if neither content, files
+ empty or greater than `2000` characters; if neither content, files
or embed are specified.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permissions to send to this channel.
- :obj:`~ValueError`
+ ValueError
If more than 100 unique objects/entities are passed for
- ``role_mentions`` or ``user_mentions``.
+ `role_mentions` or `user_mentions`.
"""
payload = await self._session.create_message(
channel_id=str(channel.id if isinstance(channel, bases.UniqueEntity) else int(channel)),
@@ -549,9 +538,10 @@ def safe_create_message(
) -> more_typing.Coroutine[_messages.Message]:
"""Create a message in the given channel with mention safety.
- This endpoint has the same signature as :attr:`create_message` with
- the only difference being that ``mentions_everyone``,
- ``user_mentions`` and ``role_mentions`` default to :obj:`~False`.
+ This endpoint has the same signature as
+ `RESTChannelComponent.create_message` with the only difference being
+ that `mentions_everyone`, `user_mentions` and `role_mentions` default to
+ `False`.
"""
return self.create_message(
channel=channel,
@@ -581,56 +571,56 @@ async def update_message(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to get the message from.
- message : :obj:`~typing.Union` [ :obj:`~hikari.messages.Message`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ message : typing.Union [ hikari.messages.Message, hikari.bases.Snowflake, int ]
The object or ID of the message to edit.
- content : :obj:`~str`, optional
+ content : str, optional
If specified, the string content to replace with in the message.
- If :obj:`~None`, the content will be removed from the message.
- embed : :obj:`~hikari.embeds.Embed`, optional
- If specified, the embed to replace with in the message.
- If :obj:`~None`, the embed will be removed from the message.
- flags : :obj:`~hikari.messages.MessageFlag`
+ If `None`, then the content will be removed from the message.
+ embed : hikari.embeds.Embed, optional
+ If specified, then the embed to replace with in the message.
+ If `None`, then the embed will be removed from the message.
+ flags : hikari.messages.MessageFlag
If specified, the new flags for this message, while a raw int may
be passed for this, this can lead to unexpected behaviour if it's
outside the range of the MessageFlag int flag.
- mentions_everyone : :obj:`~bool`
- Whether ``@everyone`` and ``@here`` mentions should be resolved by
- discord and lead to actual pings, defaults to :obj:`~True`.
- user_mentions : :obj:`~typing.Union` [ :obj:`~typing.Collection` [ :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ], :obj:`~bool` ]
+ mentions_everyone : bool
+ Whether `@everyone` and `@here` mentions should be resolved by
+ discord and lead to actual pings, defaults to `True`.
+ user_mentions : typing.Union [ typing.Collection [ typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ], bool ]
Either an array of user objects/IDs to allow mentions for,
- :obj:`~True` to allow all user mentions or :obj:`~False` to block all
- user mentions from resolving, defaults to :obj:`~True`.
- role_mentions : :obj:`~typing.Union` [ :obj:`~typing.Collection` [ :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ] ], :obj:`~bool` ]
+ `True` to allow all user mentions or `False` to block all
+ user mentions from resolving, defaults to `True`.
+ role_mentions : typing.Union [ typing.Collection [ typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ] ], bool ]
Either an array of guild role objects/IDs to allow mentions for,
- :obj:`~True` to allow all role mentions or :obj:`~False` to block all
- role mentions from resolving, defaults to :obj:`~True`.
+ `True` to allow all role mentions or `False` to block all
+ role mentions from resolving, defaults to `True`.
Returns
-------
- :obj:`~hikari.messages.Message`
+ hikari.messages.Message
The edited message object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
This can be raised if the embed exceeds the defined limits;
if the message content is specified only and empty or greater
- than ``2000`` characters; if neither content, file or embed
+ than `2000` characters; if neither content, file or embed
are specified.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you try to edit ``content`` or ``embed`` or ``allowed_mentions`
+ hikari.errors.ForbiddenHTTPError
+ If you try to edit `content` or `embed` or `allowed_mentions`
on a message you did not author.
If you try to edit the flags on a message you did not author without
- the ``MANAGE_MESSAGES`` permission.
- :obj:`~ValueError`
+ the `MANAGE_MESSAGES` permission.
+ ValueError
If more than 100 unique objects/entities are passed for
- ``role_mentions`` or ``user_mentions``.
+ `role_mentions` or `user_mentions`.
"""
payload = await self._session.edit_message(
channel_id=str(channel.id if isinstance(channel, bases.UniqueEntity) else int(channel)),
@@ -658,9 +648,10 @@ def safe_update_message(
) -> typing.Coroutine[typing.Any, typing.Any, _messages.Message]:
"""Update a message in the given channel with mention safety.
- This endpoint has the same signature as :attr:`update_message` with
- the only difference being that ``mentions_everyone``,
- ``user_mentions`` and ``role_mentions`` default to :obj:`~False`.
+ This endpoint has the same signature as
+ `RESTChannelComponent.update_message` with the only difference being
+ that `mentions_everyone`, `user_mentions` and `role_mentions` default to
+ `False`.
"""
return self.update_message(
message=message,
@@ -683,35 +674,34 @@ async def delete_messages(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to get the message from.
- message : :obj:`~typing.Union` [ :obj:`~hikari.messages.Message`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ message : typing.Union [ hikari.messages.Message, hikari.bases.Snowflake, int ]
The object or ID of the message to delete.
- *additional_messages : :obj:`~typing.Union` [ :obj:`~hikari.messages.Message`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ *additional_messages : typing.Union [ hikari.messages.Message, hikari.bases.Snowflake, int ]
Objects and/or IDs of additional messages to delete in the same
channel, in total you can delete up to 100 messages in a request.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you did not author the message and are in a DM, or if you did
- not author the message and lack the ``MANAGE_MESSAGES``
+ not author the message and lack the `MANAGE_MESSAGES`
permission in a guild channel.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found.
- :obj:`~ValueError`
- If you try to delete over ``100`` messages in a single request.
-
- Note
- ----
- This can only be used on guild text channels.
- Any message IDs that do not exist or are invalid still add towards the
- total ``100`` max messages to remove. This can only delete messages
- that are newer than ``2`` weeks in age. If any of the messages ar
- older than ``2`` weeks then this call will fail.
+ ValueError
+ If you try to delete over `100` messages in a single request.
+
+ !!! note
+ This can only be used on guild text channels.
+ Any message IDs that do not exist or are invalid still add towards
+ the total `100` max messages to remove. This can only delete
+ messages that are newer than `2` weeks in age. If any of the
+ messages are older than `2` weeks then this call will fail.
"""
if additional_messages:
messages = list(
@@ -750,32 +740,32 @@ async def update_channel_overwrite(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.messages.Message`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.messages.Message, hikari.bases.Snowflake, int ]
The object or ID of the channel to edit permissions for.
- overwrite : :obj:`~typing.Union` [ :obj:`~hikari.channels.PermissionOverwrite`, :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake` , :obj:`~int` ]
+ overwrite : typing.Union [ hikari.channels.PermissionOverwrite, hikari.guilds.GuildRole, hikari.users.User, hikari.bases.Snowflake , int ]
The object or ID of the target member or role to edit/create the
overwrite for.
- target_type : :obj:`~typing.Union` [ :obj:`~hikari.channels.PermissionOverwriteType`, :obj:`~int` ]
+ target_type : typing.Union [ hikari.channels.PermissionOverwriteType, int ]
The type of overwrite, passing a raw string that's outside of the
enum's range for this may lead to unexpected behaviour.
- allow : :obj:`~typing.Union` [ :obj:`~hikari.permissions.Permission`, :obj:`~int` ]
+ allow : typing.Union [ hikari.permissions.Permission, int ]
If specified, the value of all permissions to set to be allowed,
passing a raw integer for this may lead to unexpected behaviour.
- deny : :obj:`~typing.Union` [ :obj:`~hikari.permissions.Permission`, :obj:`~int` ]
+ deny : typing.Union [ hikari.permissions.Permission, int ]
If specified, the value of all permissions to set to be denied,
passing a raw integer for this may lead to unexpected behaviour.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the target channel or overwrite doesn't exist.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permission to do this.
"""
await self._session.edit_channel_permissions(
@@ -794,22 +784,22 @@ async def fetch_invites_for_channel(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to get invites for.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~hikari.invites.InviteWithMetadata` ]
+ typing.Sequence [ hikari.invites.InviteWithMetadata ]
A list of invite objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_CHANNELS`` permission.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_CHANNELS` permission.
+ hikari.errors.NotFoundHTTPError
If the channel does not exist.
"""
payload = await self._session.get_channel_invites(
@@ -833,42 +823,42 @@ async def create_invite_for_channel(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~datetime.timedelta`, :obj:`~str` ]
+ channel : typing.Union [ datetime.timedelta, str ]
The object or ID of the channel to create the invite for.
- max_age : :obj:`~int`
+ max_age : int
If specified, the seconds time delta for the max age of the invite,
- defaults to ``86400`` seconds (``24`` hours).
- Set to ``0`` seconds to never expire.
- max_uses : :obj:`~int`
- If specified, the max number of uses this invite can have, or ``0``
+ defaults to `86400` seconds (`24` hours).
+ Set to `0` seconds to never expire.
+ max_uses : int
+ If specified, the max number of uses this invite can have, or `0`
for unlimited (as per the default).
- temporary : :obj:`~bool`
+ temporary : bool
If specified, whether to grant temporary membership, meaning the
user is kicked when their session ends unless they are given a role.
- unique : :obj:`~bool`
+ unique : bool
If specified, whether to try to reuse a similar invite.
- target_user : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ target_user : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
If specified, the object or ID of the user this invite should
target.
- target_user_type : :obj:`~typing.Union` [ :obj:`~hikari.invites.TargetUserType`, :obj:`~int` ]
+ target_user_type : typing.Union [ hikari.invites.TargetUserType, int ]
If specified, the type of target for this invite, passing a raw
integer for this may lead to unexpected results.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~hikari.invites.InviteWithMetadata`
+ hikari.invites.InviteWithMetadata
The created invite object.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``CREATE_INSTANT_MESSAGES`` permission.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `CREATE_INSTANT_MESSAGES` permission.
+ hikari.errors.NotFoundHTTPError
If the channel does not exist.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If the arguments provided are not valid (e.g. negative age, etc).
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
@@ -898,20 +888,20 @@ async def delete_channel_overwrite(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to delete the overwrite from.
- overwrite : :obj:`~typing.Union` [ :obj:`~hikari.channels.PermissionOverwrite`, :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:int ]
+ overwrite : typing.Union [ hikari.channels.PermissionOverwrite, hikari.guilds.GuildRole, hikari.users.User, hikari.bases.Snowflake, int ]
The ID of the entity this overwrite targets.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the overwrite or channel do not exist.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission for that channel.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission for that channel.
"""
await self._session.delete_channel_permission(
channel_id=str(channel.id if isinstance(channel, bases.UniqueEntity) else int(channel)),
@@ -919,21 +909,21 @@ async def delete_channel_overwrite(
)
async def trigger_typing(self, channel: bases.Hashable[_channels.Channel]) -> None:
- """Trigger the typing indicator for ``10`` seconds in a channel.
+ """Trigger the typing indicator for `10` seconds in a channel.
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to appear to be typing in.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you are not able to type in the channel.
"""
await self._session.trigger_typing_indicator(
@@ -947,29 +937,28 @@ async def fetch_pins(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to get messages from.
Returns
-------
- :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~hikari.messages.Message` ]
+ typing.Mapping [ hikari.bases.Snowflake, hikari.messages.Message ]
A list of message objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you are not able to see the channel.
- Note
- ----
- If you are not able to see the pinned message (eg. you are missing
- ``READ_MESSAGE_HISTORY`` and the pinned message is an old message), it
- will not be returned.
+ !!! note
+ If you are not able to see the pinned message (eg. you are missing
+ `READ_MESSAGE_HISTORY` and the pinned message is an old message), it
+ will not be returned.
"""
payload = await self._session.get_pinned_messages(
channel_id=str(channel.id if isinstance(channel, bases.UniqueEntity) else int(channel))
@@ -983,19 +972,19 @@ async def pin_message(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to pin a message to.
- message : :obj:`~typing.Union` [ :obj:`~hikari.messages.Message`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ message : typing.Union [ hikari.messages.Message, hikari.bases.Snowflake, int ]
The object or ID of the message to pin.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_MESSAGES`` permission.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_MESSAGES` permission.
+ hikari.errors.NotFoundHTTPError
If the message or channel do not exist.
"""
await self._session.add_pinned_channel_message(
@@ -1012,19 +1001,19 @@ async def unpin_message(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The ID of the channel to remove a pin from.
- message : :obj:`~typing.Union` [ :obj:`~hikari.messages.Message`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ message : typing.Union [ hikari.messages.Message, hikari.bases.Snowflake, int ]
The object or ID of the message to unpin.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_MESSAGES`` permission.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_MESSAGES` permission.
+ hikari.errors.NotFoundHTTPError
If the message or channel do not exist.
"""
await self._session.delete_pinned_channel_message(
@@ -1044,29 +1033,29 @@ async def create_webhook(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.GuildChannel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.GuildChannel, hikari.bases.Snowflake, int ]
The object or ID of the channel for webhook to be created in.
- name : :obj:`~str`
+ name : str
The webhook's name string.
- avatar_data : ``hikari.internal.conversions.FileLikeT``
+ avatar_data : `hikari.internal.conversions.FileLikeT`
If specified, the avatar image data.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~hikari.webhooks.Webhook`
+ hikari.webhooks.Webhook
The newly created webhook object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_WEBHOOKS`` permission or
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_WEBHOOKS` permission or
can not see the given channel.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If the avatar image is too big or the format is invalid.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
@@ -1086,23 +1075,23 @@ async def fetch_channel_webhooks(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.GuildChannel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.GuildChannel, hikari.bases.Snowflake, int ]
The object or ID of the guild channel to get the webhooks from.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~hikari.webhooks.Webhook` ]
+ typing.Sequence [ hikari.webhooks.Webhook ]
A list of webhook objects for the give channel.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_WEBHOOKS`` permission or
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_WEBHOOKS` permission or
can not see the given channel.
"""
payload = await self._session.get_channel_webhooks(
diff --git a/hikari/clients/rest/gateway.py b/hikari/clients/rest/gateway.py
index d2ce803adf..2db1292b6a 100644
--- a/hikari/clients/rest/gateway.py
+++ b/hikari/clients/rest/gateway.py
@@ -34,12 +34,11 @@ async def fetch_gateway_url(self) -> str:
Returns
-------
- :obj:`~str`
+ str
A static URL to use to connect to the gateway with.
- Note
- ----
- Users are expected to attempt to cache this result.
+ !!! note
+ Users are expected to attempt to cache this result.
"""
return await self._session.get_gateway()
@@ -48,12 +47,12 @@ async def fetch_gateway_bot(self) -> gateway_entities.GatewayBot:
Returns
-------
- :obj:`~hikari.gateway_entities.GatewayBot`
+ hikari.gateway_entities.GatewayBot
The bot specific gateway information object.
- Note
- ----
- Unlike :meth:`fetch_gateway_url`, this requires a valid token to work.
+ !!! note
+ Unlike `RESTGatewayComponent.fetch_gateway_url`, this requires a
+ valid token to work.
"""
payload = await self._session.get_gateway_bot()
return gateway_entities.GatewayBot.deserialize(payload)
diff --git a/hikari/clients/rest/guild.py b/hikari/clients/rest/guild.py
index e58632db72..0842dbb107 100644
--- a/hikari/clients/rest/guild.py
+++ b/hikari/clients/rest/guild.py
@@ -60,33 +60,33 @@ async def fetch_audit_log(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get the audit logs for.
- user : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ user : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
If specified, the object or ID of the user to filter by.
- action_type : :obj:`~typing.Union` [ :obj:`~hikari.audit_logs.AuditLogEventType`, :obj:`~int` ]
+ action_type : typing.Union [ hikari.audit_logs.AuditLogEventType, int ]
If specified, the action type to look up. Passing a raw integer
for this may lead to unexpected behaviour.
- limit : :obj:`~int`
+ limit : int
If specified, the limit to apply to the number of records.
- Defaults to ``50``. Must be between ``1`` and ``100`` inclusive.
- before : :obj:`~typing.Union` [ :obj:`~datetime.datetime`, :obj:`~hikari.audit_logs.AuditLogEntry`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ Defaults to `50`. Must be between `1` and `100` inclusive.
+ before : typing.Union [ datetime.datetime, hikari.audit_logs.AuditLogEntry, hikari.bases.Snowflake, int ]
If specified, the object or ID of the entry that all retrieved
- entries should have occurred befor.
+ entries should have occurred before.
Returns
-------
- :obj:`~hikari.audit_logs.AuditLog`
+ hikari.audit_logs.AuditLog
An audit log object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack the given permissions to view an audit log.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild does not exist.
"""
if isinstance(before, datetime.datetime):
@@ -118,44 +118,41 @@ def fetch_audit_log_entries_before(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The ID or object of the guild to get audit log entries for
- before : :obj:`~typing.Union` [ :obj:`~datetime.datetime`, :obj:`~hikari.audit_logs.AuditLogEntry`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ], optional
+ before : typing.Union [ datetime.datetime, hikari.audit_logs.AuditLogEntry, hikari.bases.Snowflake, int ], optional
If specified, the ID or object of the entry or datetime to get
entries that happened before otherwise this will start from the
newest entry.
- user : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ user : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
If specified, the object or ID of the user to filter by.
- action_type : :obj:`~typing.Union` [ :obj:`~hikari.audit_logs.AuditLogEventType`, :obj:`~int` ]
+ action_type : typing.Union [ hikari.audit_logs.AuditLogEventType, int ]
If specified, the action type to look up. Passing a raw integer
for this may lead to unexpected behaviour.
- limit : :obj:`~int`, optional
+ limit : int, optional
If specified, the limit for how many entries this iterator should
return, defaults to unlimited.
- Example
- -------
- .. code-block:: python
-
+ Examples
+ --------
audit_log_entries = client.fetch_audit_log_entries_before(guild, before=9876543, limit=6969)
async for entry in audit_log_entries:
if (user := audit_log_entries.users[entry.user_id]).is_bot:
await client.ban_member(guild, user)
- Note
- ----
- The returned iterator has the attributes ``users``, ``members`` and
- ``integrations`` which are mappings of snowflake IDs to objects for the
- relevant entities that are referenced by the retrieved audit log
- entries. These will be filled over time as more audit log entries are
- fetched by the iterator.
+ !!! note
+ The returned iterator has the attributes `users`, `members` and
+ `integrations` which are mappings of snowflake IDs to objects for
+ the relevant entities that are referenced by the retrieved audit log
+ entries. These will be filled over time as more audit log entries
+ are fetched by the iterator.
Returns
-------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.audit_logs.AuditLogIterator`
+ hikari.audit_logs.AuditLogIterator
An async iterator of the audit log entries in a guild (from newest
to oldest).
"""
@@ -179,24 +176,24 @@ async def fetch_guild_emoji(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get the emoji from.
- emoji : :obj:`~typing.Union` [ :obj:`~hikari.emojis.GuildEmoji`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ emoji : typing.Union [ hikari.emojis.GuildEmoji, hikari.bases.Snowflake, int ]
The object or ID of the emoji to get.
Returns
-------
- :obj:`~hikari.emojis.GuildEmoji`
+ hikari.emojis.GuildEmoji
A guild emoji object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the emoji aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you aren't a member of said guild.
"""
payload = await self._session.get_guild_emoji(
@@ -210,22 +207,22 @@ async def fetch_guild_emojis(self, guild: bases.Hashable[guilds.Guild]) -> typin
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get the emojis for.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~hikari.emojis.GuildEmoji` ]
+ typing.Sequence [ hikari.emojis.GuildEmoji ]
A list of guild emoji objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you aren't a member of the guild.
"""
payload = await self._session.list_guild_emojis(
@@ -246,35 +243,35 @@ async def create_guild_emoji(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ]
The object or ID of the guild to create the emoji in.
- name : :obj:`~str`
+ name : str
The new emoji's name.
- image_data : ``hikari.internal.conversions.FileLikeT``
- The ``128x128`` image data.
- roles : :obj:`~typing.Sequence` [ :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ] ]
+ image_data : hikari.internal.conversions.FileLikeT
+ The `128x128` image data.
+ roles : typing.Sequence [ typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ] ]
If specified, a list of role objects or IDs for which the emoji
will be whitelisted. If empty, all roles are whitelisted.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~hikari.emojis.GuildEmoji`
+ hikari.emojis.GuildEmoji
The newly created emoji object.
Raises
------
- :obj:`~ValueError`
- If ``image`` is :obj:`~None`.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ ValueError
+ If `image` is `None`.
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_EMOJIS`` permission or aren't a
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_EMOJIS` permission or aren't a
member of said guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you attempt to upload an image larger than ``256kb``, an empty
+ hikari.errors.BadRequestHTTPError
+ If you attempt to upload an image larger than `256kb`, an empty
image or an invalid image format.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
@@ -303,35 +300,35 @@ async def update_guild_emoji(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to which the emoji to edit belongs to.
- emoji : :obj:`~typing.Union` [ :obj:`~hikari.emojis.GuildEmoji`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ emoji : typing.Union [ hikari.emojis.GuildEmoji, hikari.bases.Snowflake, int ]
The object or ID of the emoji to edit.
- name : :obj:`~str`
+ name : str
If specified, a new emoji name string. Keep unspecified to leave the
name unchanged.
- roles : :obj:`~typing.Sequence` [ :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ] ]
+ roles : typing.Sequence [ typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ] ]
If specified, a list of objects or IDs for the new whitelisted
roles. Set to an empty list to whitelist all roles.
Keep unspecified to leave the same roles already set.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~hikari.emojis.GuildEmoji`
+ hikari.emojis.GuildEmoji
The updated emoji object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the emoji aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_EMOJIS`` permission or are not a
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_EMOJIS` permission or are not a
member of the given guild.
"""
payload = await self._session.modify_guild_emoji(
@@ -352,20 +349,20 @@ async def delete_guild_emoji(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to delete the emoji from.
- emoji : :obj:`~typing.Union` [ :obj:`~hikari.emojis.GuildEmoji`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ emoji : typing.Union [ hikari.emojis.GuildEmoji, hikari.bases.Snowflake, int ]
The object or ID of the guild emoji to be deleted.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the emoji aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_EMOJIS`` permission or aren't a
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_EMOJIS` permission or aren't a
member of said guild.
"""
await self._session.delete_guild_emoji(
@@ -387,47 +384,46 @@ async def create_guild(
) -> guilds.Guild:
"""Create a new guild.
- Warning
- -------
- Can only be used by bots in less than ``10`` guilds.
+ !!! warning
+ Can only be used by bots in less than `10` guilds.
Parameters
----------
- name : :obj:`~str`
- The name string for the new guild (``2-100`` characters).
- region : :obj:`~str`
+ name : str
+ The name string for the new guild (`2-100` characters).
+ region : str
If specified, the voice region ID for new guild. You can use
- :meth:`fetch_guild_voice_regions` to see which region IDs are
- available.
- icon_data : ``hikari.internal.conversions.FileLikeT``
+ `RESTGuildComponent.fetch_guild_voice_regions` to see which region
+ IDs are available.
+ icon_data : hikari.internal.conversions.FileLikeT
If specified, the guild icon image data.
- verification_level : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildVerificationLevel`, :obj:`~int` ]
+ verification_level : typing.Union [ hikari.guilds.GuildVerificationLevel, int ]
If specified, the verification level. Passing a raw int for this
may lead to unexpected behaviour.
- default_message_notifications : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildMessageNotificationsLevel`, :obj:`~int` ]
+ default_message_notifications : typing.Union [ hikari.guilds.GuildMessageNotificationsLevel, int ]
If specified, the default notification level. Passing a raw int for
this may lead to unexpected behaviour.
- explicit_content_filter : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildExplicitContentFilterLevel`, :obj:`~int` ]
+ explicit_content_filter : typing.Union [ hikari.guilds.GuildExplicitContentFilterLevel, int ]
If specified, the explicit content filter. Passing a raw int for
this may lead to unexpected behaviour.
- roles : :obj:`~typing.Sequence` [ :obj:`~hikari.guilds.GuildRole` ]
+ roles : typing.Sequence [ hikari.guilds.GuildRole ]
If specified, an array of role objects to be created alongside the
- guild. First element changes the ``@everyone`` role.
- channels : :obj:`~typing.Sequence` [ :obj:`~hikari.channels.GuildChannelBuilder` ]
+ guild. First element changes the `@everyone` role.
+ channels : typing.Sequence [ hikari.channels.GuildChannelBuilder ]
If specified, an array of guild channel builder objects to be
created within the guild.
Returns
-------
- :obj:`~hikari.guilds.Guild`
+ hikari.guilds.Guild
The newly created guild object.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you are in ``10`` or more guilds.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you provide unsupported fields like ``parent_id`` in channel
+ hikari.errors.ForbiddenHTTPError
+ If you are in `10` or more guilds.
+ hikari.errors.BadRequestHTTPError
+ If you provide unsupported fields like `parent_id` in channel
objects.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
@@ -449,22 +445,22 @@ async def fetch_guild(self, guild: bases.Hashable[guilds.Guild]) -> guilds.Guild
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get.
Returns
-------
- :obj:`~hikari.guilds.Guild`
+ hikari.guilds.Guild
The requested guild object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you don't have access to the guild.
"""
payload = await self._session.get_guild(
@@ -477,26 +473,25 @@ async def fetch_guild_preview(self, guild: bases.Hashable[guilds.Guild]) -> guil
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get the preview object for.
Returns
-------
- :obj:`~hikari.guilds.GuildPreview`
+ hikari.guilds.GuildPreview
The requested guild preview object.
- Note
- ----
- Unlike other guild endpoints, the bot doesn't have to be in the target
- guild to get it's preview.
+ !!! note
+ Unlike other guild endpoints, the bot doesn't have to be in the
+ target guild to get it's preview.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of UINT64.
- :obj:`~hikari.errors.NotFoundHTTPError`
- If the guild is not found or it isn't ``PUBLIC``.
+ hikari.errors.NotFoundHTTPError
+ If the guild is not found or it isn't `PUBLIC`.
"""
payload = await self._session.get_guild_preview(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild))
@@ -524,53 +519,53 @@ async def update_guild(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to be edited.
- name : :obj:`~str`
- If specified, the new name string for the guild (``2-100`` characters).
- region : :obj:`~str`
+ name : str
+ If specified, the new name string for the guild (`2-100` characters).
+ region : str
If specified, the new voice region ID for guild. You can use
- :meth:`fetch_guild_voice_regions` to see which region IDs are
- available.
- verification_level : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildVerificationLevel`, :obj:`~int` ]
+ `RESTGuildComponent.fetch_guild_voice_regions` to see which region
+ IDs are available.
+ verification_level : typing.Union [ hikari.guilds.GuildVerificationLevel, int ]
If specified, the new verification level. Passing a raw int for this
may lead to unexpected behaviour.
- default_message_notifications : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildMessageNotificationsLevel`, :obj:`~int` ]
+ default_message_notifications : typing.Union [ hikari.guilds.GuildMessageNotificationsLevel, int ]
If specified, the new default notification level. Passing a raw int
for this may lead to unexpected behaviour.
- explicit_content_filter : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildExplicitContentFilterLevel`, :obj:`~int` ]
+ explicit_content_filter : typing.Union [ hikari.guilds.GuildExplicitContentFilterLevel, int ]
If specified, the new explicit content filter. Passing a raw int for
this may lead to unexpected behaviour.
- afk_channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.GuildVoiceChannel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ afk_channel : typing.Union [ hikari.channels.GuildVoiceChannel, hikari.bases.Snowflake, int ]
If specified, the object or ID for the new AFK voice channel.
- afk_timeout : :obj:`~typing.Union` [ :obj:`~datetime.timedelta`, :obj:`~int` ]
+ afk_timeout : typing.Union [ datetime.timedelta, int ]
If specified, the new AFK timeout seconds timedelta.
- icon_data : ``hikari.internal.conversions.FileLikeT``
+ icon_data : hikari.internal.conversions.FileLikeT
If specified, the new guild icon image file data.
- owner : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ owner : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
If specified, the object or ID of the new guild owner.
- splash_data : ``hikari.internal.conversions.FileLikeT``
+ splash_data : hikari.internal.conversions.FileLikeT
If specified, the new new splash image file data.
- system_channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.GuildVoiceChannel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ system_channel : typing.Union [ hikari.channels.GuildVoiceChannel, hikari.bases.Snowflake, int ]
If specified, the object or ID of the new system channel.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~hikari.guilds.Guild`
+ hikari.guilds.Guild
The edited guild object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_GUILD` permission or are not in the guild.
"""
payload = await self._session.modify_guild(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild)),
@@ -606,17 +601,17 @@ async def delete_guild(self, guild: bases.Hashable[guilds.Guild]) -> None:
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to be deleted.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you are not the guild owner.
"""
await self._session.delete_guild(
@@ -630,22 +625,22 @@ async def fetch_guild_channels(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get the channels from.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~hikari.channels.GuildChannel` ]
+ typing.Sequence [ hikari.channels.GuildChannel ]
A list of guild channel objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you are not in the guild.
"""
payload = await self._session.list_guild_channels(
@@ -672,62 +667,62 @@ async def create_guild_channel(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to create the channel in.
- name : :obj:`~str`
+ name : str
If specified, the name for the channel. This must be
- inclusively between ``1` and ``100`` characters in length.
- channel_type: :obj:`~typing.Union` [ :obj:`~hikari.channels.ChannelType`, :obj:`~int` ]
+ inclusively between `1` and `100` characters in length.
+ channel_type: typing.Union [ hikari.channels.ChannelType, int ]
If specified, the channel type, passing through a raw integer here
may lead to unexpected behaviour.
- position : :obj:`~int`
+ position : int
If specified, the position to change the channel to.
- topic : :obj:`~str`
+ topic : str
If specified, the topic to set. This is only applicable to
- text channels. This must be inclusively between ``0`` and ``1024``
+ text channels. This must be inclusively between `0` and `1024`
characters in length.
- nsfw : :obj:`~bool`
+ nsfw : bool
If specified, whether the channel will be marked as NSFW.
Only applicable for text channels.
- rate_limit_per_user : :obj:`~typing.Union` [ :obj:`~datetime.timedelta`, :obj:`~int` ]
+ rate_limit_per_user : typing.Union [ datetime.timedelta, int ]
If specified, the second time delta the user has to wait before
sending another message. This will not apply to bots, or to
- members with ``MANAGE_MESSAGES`` or ``MANAGE_CHANNEL`` permissions.
- This must be inclusively between ``0`` and ``21600`` seconds.
- bitrate : :obj:`~int`
+ members with `MANAGE_MESSAGES` or `MANAGE_CHANNEL` permissions.
+ This must be inclusively between `0` and `21600` seconds.
+ bitrate : int
If specified, the bitrate in bits per second allowable for the
channel. This only applies to voice channels and must be inclusively
- between ``8000`` and ``96000`` for normal servers or ``8000`` and
- ``128000`` for VIP servers.
- user_limit : :obj:`~int`
+ between `8000` and `96000` for normal servers or `8000` and
+ `128000` for VIP servers.
+ user_limit : int
If specified, the max number of users to allow in a voice channel.
- This must be between ``0`` and ``99`` inclusive, where
- ``0`` implies no limit.
- permission_overwrites : :obj:`~typing.Sequence` [ :obj:`~hikari.channels.PermissionOverwrite` ]
+ This must be between `0` and `99` inclusive, where
+ `0` implies no limit.
+ permission_overwrites : typing.Sequence [ hikari.channels.PermissionOverwrite ]
If specified, the list of permission overwrite objects that are
category specific to replace the existing overwrites with.
- parent_category : :obj:`~typing.Union` [ :obj:`~hikari.channels.GuildCategory`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ parent_category : typing.Union [ hikari.channels.GuildCategory, hikari.bases.Snowflake, int ]
If specified, the object or ID of the parent category to set for
the channel.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~hikari.channels.GuildChannel`
+ hikari.channels.GuildChannel
The newly created channel object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_CHANNEL`` permission or are not in the
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_CHANNEL` permission or are not in the
guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If you provide incorrect options for the corresponding channel type
- (e.g. a ``bitrate`` for a text channel).
+ (e.g. a `bitrate` for a text channel).
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
"""
@@ -767,25 +762,25 @@ async def reposition_guild_channels(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild in which to edit the channels.
- channel : :obj:`~typing.Tuple` [ :obj:`~int` , :obj:`~typing.Union` [ :obj:`~hikari.channels.GuildChannel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ] ]
+ channel : typing.Tuple [ int , typing.Union [ hikari.channels.GuildChannel, hikari.bases.Snowflake, int ] ]
The first channel to change the position of. This is a tuple of the
integer position the channel object or ID.
- *additional_channels : :obj:`~typing.Tuple` [ :obj:`~int`, :obj:`~typing.Union` [ :obj:`~hikari.channels.GuildChannel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ] ]
+ *additional_channels : typing.Tuple [ int, typing.Union [ hikari.channels.GuildChannel, hikari.bases.Snowflake, int ] ]
Optional additional channels to change the position of. These must
be tuples of integer positions to change to and the channel object
or ID and the.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or any of the channels aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_CHANNELS`` permission or are not a
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_CHANNELS` permission or are not a
member of said guild or are not in the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you provide anything other than the ``id`` and ``position``
+ hikari.errors.BadRequestHTTPError
+ If you provide anything other than the `id` and `position`
fields for the channels.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
@@ -805,24 +800,24 @@ async def fetch_member(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get the member from.
- user : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ user : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
The object or ID of the member to get.
Returns
-------
- :obj:`~hikari.guilds.GuildMember`
+ hikari.guilds.GuildMember
The requested member object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the member aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you don't have access to the target guild.
"""
payload = await self._session.get_guild_member(
@@ -846,36 +841,34 @@ def fetch_members_after(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get the members from.
- limit : :obj:`~int`
+ limit : int
If specified, the maximum number of members this iterator
should return.
- after : :obj:`~typing.Union` [ :obj:`~datetime.datetime`, :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ after : typing.Union [ datetime.datetime, hikari.users.User, hikari.bases.Snowflake, int ]
The object or ID of the user this iterator should start
after if specified, else this will start at the oldest user.
- Example
- -------
- .. code-block:: python
-
+ Examples
+ --------
async for user in client.fetch_members_after(guild, after=9876543, limit=1231):
if member.user.username[0] in HOIST_BLACKLIST:
await client.update_member(member, nickname="💩")
Returns
-------
- :obj:`~typing.AsyncIterator` [ :obj:`~hikari.guilds.GuildMember` ]
+ typing.AsyncIterator [ hikari.guilds.GuildMember ]
An async iterator of member objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you are not in the guild.
"""
if isinstance(after, datetime.datetime):
@@ -908,40 +901,40 @@ async def update_member(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to edit the member from.
- user : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildMember`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ user : typing.Union [ hikari.guilds.GuildMember, hikari.bases.Snowflake, int ]
The object or ID of the member to edit.
- nickname : :obj:`~str`, optional
- If specified, the new nickname string. Setting it to :obj:`~None`
+ nickname : str, optional
+ If specified, the new nickname string. Setting it to `None`
explicitly will clear the nickname.
- roles : :obj:`~typing.Sequence` [ :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ] ]
+ roles : typing.Sequence [ typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ] ]
If specified, a list of role IDs the member should have.
- mute : :obj:`~bool`
+ mute : bool
If specified, whether the user should be muted in the voice channel
or not.
- deaf : :obj:`~bool`
+ deaf : bool
If specified, whether the user should be deafen in the voice
channel or not.
- voice_channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.GuildVoiceChannel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ], optional
+ voice_channel : typing.Union [ hikari.channels.GuildVoiceChannel, hikari.bases.Snowflake, int ], optional
If specified, the ID of the channel to move the member to. Setting
- it to :obj:`~None` explicitly will disconnect the user.
- reason : :obj:`~str`
+ it to `None` explicitly will disconnect the user.
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild, user, channel or any of the roles aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack any of the applicable permissions
- (``MANAGE_NICKNAMES``, ``MANAGE_ROLES``, ``MUTE_MEMBERS``, ``DEAFEN_MEMBERS`` or ``MOVE_MEMBERS``).
+ hikari.errors.ForbiddenHTTPError
+ If you lack any of the applicable permissions (`MANAGE_NICKNAMES`,
+ `MANAGE_ROLES`, `MUTE_MEMBERS`, `DEAFEN_MEMBERS` or `MOVE_MEMBERS`).
Note that to move a member you must also have permission to connect
to the end channel. This will also be raised if you're not in the
guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you pass ``mute``, ``deaf`` or ``channel_id`` while the member
+ hikari.errors.BadRequestHTTPError
+ If you pass `mute`, `deaf` or `channel_id` while the member
is not connected to a voice channel.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
@@ -972,22 +965,22 @@ async def update_my_member_nickname(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild you want to change the nick on.
- nickname : :obj:`~str`, optional
+ nickname : str, optional
The new nick string. Setting this to `None` clears the nickname.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``CHANGE_NICKNAME`` permission or are not in the
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `CHANGE_NICKNAME` permission or are not in the
guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If you provide a disallowed nickname, one that is too long, or one
that is empty.
If any invalid snowflake IDs are passed; a snowflake may be invalid
@@ -1011,25 +1004,25 @@ async def add_role_to_member(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild the member belongs to.
- user : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ user : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
The object or ID of the member you want to add the role to.
- role : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ role : typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ]
The object or ID of the role you want to add.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild, member or role aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission or are not in the guild.
"""
await self._session.add_guild_member_role(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild)),
@@ -1050,25 +1043,25 @@ async def remove_role_from_member(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild the member belongs to.
- user : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ user : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
The object or ID of the member you want to remove the role from.
- role : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ role : typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ]
The object or ID of the role you want to remove.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild, member or role aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission or are not in the guild.
"""
await self._session.remove_guild_member_role(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild)),
@@ -1084,23 +1077,23 @@ async def kick_member(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild the member belongs to.
- user : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ user : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
The object or ID of the member you want to kick.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or member aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``KICK_MEMBERS`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `KICK_MEMBERS` permission or are not in the guild.
"""
await self._session.remove_guild_member(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild)),
@@ -1115,26 +1108,26 @@ async def fetch_ban(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild you want to get the ban from.
- user : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ user : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
The object or ID of the user to get the ban information for.
Returns
-------
- :obj:`~hikari.guilds.GuildMemberBan`
+ hikari.guilds.GuildMemberBan
A ban object for the requested user.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the user aren't found, or if the user is not
banned.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``BAN_MEMBERS`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `BAN_MEMBERS` permission or are not in the guild.
"""
payload = await self._session.get_guild_ban(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild)),
@@ -1147,23 +1140,23 @@ async def fetch_bans(self, guild: bases.Hashable[guilds.Guild],) -> typing.Seque
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild you want to get the bans from.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~hikari.guilds.GuildMemberBan` ]
+ typing.Sequence [ hikari.guilds.GuildMemberBan ]
A list of ban objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``BAN_MEMBERS`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `BAN_MEMBERS` permission or are not in the guild.
"""
payload = await self._session.get_guild_bans(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild))
@@ -1182,26 +1175,26 @@ async def ban_member(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild the member belongs to.
- user : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ user : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
The object or ID of the member you want to ban.
- delete_message_days : :obj:`~typing.Union` [ :obj:`~datetime.timedelta`, :obj:`~int` ]
+ delete_message_days : typing.Union [ datetime.timedelta, int ]
If specified, the tim delta of how many days of messages from the
user should be removed.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or member aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``BAN_MEMBERS`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `BAN_MEMBERS` permission or are not in the guild.
"""
await self._session.create_guild_ban(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild)),
@@ -1217,24 +1210,24 @@ async def unban_member(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to un-ban the user from.
- user : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ user : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
The ID of the user you want to un-ban.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or member aren't found, or the member is not
banned.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``BAN_MEMBERS`` permission or are not a in the
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `BAN_MEMBERS` permission or are not a in the
guild.
"""
await self._session.remove_guild_ban(
@@ -1250,22 +1243,22 @@ async def fetch_roles(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild you want to get the roles from.
Returns
-------
- :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~hikari.guilds.GuildRole` ]
+ typing.Mapping [ hikari.bases.Snowflake, hikari.guilds.GuildRole ]
A list of role objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you're not in the guild.
"""
payload = await self._session.get_guild_roles(
@@ -1288,37 +1281,37 @@ async def create_role(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild you want to create the role on.
- name : :obj:`~str`
+ name : str
If specified, the new role name string.
- permissions : :obj:`~typing.Union` [ :obj:`~hikari.permissions.Permission`, :obj:`~int` ]
+ permissions : typing.Union [ hikari.permissions.Permission, int ]
If specified, the permissions integer for the role, passing a raw
integer rather than the int flag may lead to unexpected results.
- color : :obj:`~typing.Union` [ :obj:`~hikari.colors.Color`, :obj:`~int` ]
+ color : typing.Union [ hikari.colors.Color, int ]
If specified, the color for the role.
- hoist : :obj:`~bool`
+ hoist : bool
If specified, whether the role will be hoisted.
- mentionable : :obj:`~bool`
+ mentionable : bool
If specified, whether the role will be able to be mentioned by any
user.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~hikari.guilds.GuildRole`
+ hikari.guilds.GuildRole
The newly created role object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission or you're not in the
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission or you're not in the
guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If you provide invalid values for the role attributes.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
@@ -1344,28 +1337,28 @@ async def reposition_roles(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The ID of the guild the roles belong to.
- role : :obj:`~typing.Tuple` [ :obj:`~int`, :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ] ]
+ role : typing.Tuple [ int, typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ] ]
The first role to move. This is a tuple of the integer position and
the role object or ID.
- *additional_roles : :obj:`~typing.Tuple` [ :obj:`~int`, :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ] ]
+ *additional_roles : typing.Tuple [ int, typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ] ]
Optional extra roles to move. These must be tuples of the integer
position and the role object or ID.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~hikari.guilds.GuildRole` ]
+ typing.Sequence [ hikari.guilds.GuildRole ]
A list of all the guild roles.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or any of the roles aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission or you're not in the
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission or you're not in the
guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If you provide invalid values for the `position` fields.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
@@ -1395,39 +1388,39 @@ async def update_role(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild the role belong to.
- role : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ role : typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ]
The object or ID of the role you want to edit.
- name : :obj:`~str`
+ name : str
If specified, the new role's name string.
- permissions : :obj:`~typing.Union` [ :obj:`~hikari.permissions.Permission`, :obj:`~int` ]
+ permissions : typing.Union [ hikari.permissions.Permission, int ]
If specified, the new permissions integer for the role, passing a
raw integer for this may lead to unexpected behaviour.
- color : :obj:`~typing.Union` [ :obj:`~hikari.colors.Color`, :obj:`~int` ]
+ color : typing.Union [ hikari.colors.Color, int ]
If specified, the new color for the new role passing a raw integer
for this may lead to unexpected behaviour.
- hoist : :obj:`~bool`
+ hoist : bool
If specified, whether the role should hoist or not.
- mentionable : :obj:`~bool`
+ mentionable : bool
If specified, whether the role should be mentionable or not.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~hikari.guilds.GuildRole`
+ hikari.guilds.GuildRole
The edited role object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or role aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission or you're not in the
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission or you're not in the
guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If you provide invalid values for the role attributes.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
@@ -1449,20 +1442,20 @@ async def delete_role(self, guild: bases.Hashable[guilds.Guild], role: bases.Has
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild you want to remove the role from.
- role : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ role : typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ]
The object or ID of the role you want to delete.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the role aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission or are not in the guild.
"""
await self._session.delete_guild_role(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild)),
@@ -1476,23 +1469,23 @@ async def estimate_guild_prune_count(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild you want to get the count for.
- days : :obj:`~typing.Union` [ :obj:`~datetime.timedelta`, :obj:`~int` ]
- The time delta of days to count prune for (at least ``1``).
+ days : typing.Union [ datetime.timedelta, int ]
+ The time delta of days to count prune for (at least `1`).
Returns
-------
- :obj:`~int`
+ int
The number of members estimated to be pruned.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``KICK_MEMBERS`` or you are not in the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `KICK_MEMBERS` or you are not in the guild.
+ hikari.errors.BadRequestHTTPError
If you pass an invalid amount of days.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
@@ -1514,32 +1507,32 @@ async def begin_guild_prune(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild you want to prune member of.
- days : :obj:`~typing.Union` [ :obj:`~datetime.timedelta`, :obj:`~int` ]
+ days : typing.Union [ datetime.timedelta, int ]
The time delta of inactivity days you want to use as filter.
- compute_prune_count : :obj:`~bool`
+ compute_prune_count : bool
Whether a count of pruned members is returned or not.
Discouraged for large guilds out of politeness.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~int`, optional
- The number of members who were kicked if ``compute_prune_count``
- is :obj:`~True`, else :obj:`~None`.
+ int, optional
+ The number of members who were kicked if `compute_prune_count`
+ is `True`, else `None`.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found:
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``KICK_MEMBER`` permission or are not in the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you provide invalid values for the ``days`` or
- ``compute_prune_count`` fields.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `KICK_MEMBER` permission or are not in the guild.
+ hikari.errors.BadRequestHTTPError
+ If you provide invalid values for the `days` or
+ `compute_prune_count` fields.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
"""
@@ -1557,22 +1550,22 @@ async def fetch_guild_voice_regions(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get the voice regions for.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~hikari.voices.VoiceRegion` ]
+ typing.Sequence [ hikari.voices.VoiceRegion ]
A list of voice region objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you are not in the guild.
"""
payload = await self._session.get_guild_voice_regions(
@@ -1587,23 +1580,23 @@ async def fetch_guild_invites(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get the invites for.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~hikari.invites.InviteWithMetadata` ]
+ typing.Sequence [ hikari.invites.InviteWithMetadata ]
A list of invite objects (with metadata).
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_GUILD` permission or are not in the guild.
"""
payload = await self._session.get_guild_invites(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild))
@@ -1615,23 +1608,23 @@ async def fetch_integrations(self, guild: bases.Hashable[guilds.Guild]) -> typin
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get the integrations for.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~hikari.guilds.GuildIntegration` ]
+ typing.Sequence [ hikari.guilds.GuildIntegration ]
A list of integration objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_GUILD` permission or are not in the guild.
"""
payload = await self._session.get_guild_integrations(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild))
@@ -1652,32 +1645,32 @@ async def update_integration(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to which the integration belongs to.
- integration : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildIntegration`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ integration : typing.Union [ hikari.guilds.GuildIntegration, hikari.bases.Snowflake, int ]
The object or ID of the integration to update.
- expire_behaviour : :obj:`~typing.Union` [ :obj:`~hikari.guilds.IntegrationExpireBehaviour`, :obj:`~int` ]
+ expire_behaviour : typing.Union [ hikari.guilds.IntegrationExpireBehaviour, int ]
If specified, the behaviour for when an integration subscription
expires (passing a raw integer for this may lead to unexpected
behaviour).
- expire_grace_period : :obj:`~typing.Union` [ :obj:`~datetime.timedelta`, :obj:`~int` ]
+ expire_grace_period : typing.Union [ datetime.timedelta, int ]
If specified, time time delta of how many days the integration will
ignore lapsed subscriptions for.
- enable_emojis : :obj:`~bool`
+ enable_emojis : bool
If specified, whether emojis should be synced for this integration.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the integration aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_GUILD` permission or are not in the guild.
"""
await self._session.modify_guild_integration(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild)),
@@ -1699,22 +1692,22 @@ async def delete_integration(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to which the integration belongs to.
- integration : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildIntegration`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ integration : typing.Union [ hikari.guilds.GuildIntegration, hikari.bases.Snowflake, int ]
The object or ID of the integration to delete.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the integration aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack the `MANAGE_GUILD` permission or are not in the guild.
"""
await self._session.delete_guild_integration(
@@ -1730,20 +1723,20 @@ async def sync_guild_integration(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to which the integration belongs to.
- integration : :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildIntegration`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ integration : typing.Union [ hikari.guilds.GuildIntegration, hikari.bases.Snowflake, int ]
The ID of the integration to sync.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the integration aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_GUILD` permission or are not in the guild.
"""
await self._session.sync_guild_integration(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild)),
@@ -1755,23 +1748,23 @@ async def fetch_guild_embed(self, guild: bases.Hashable[guilds.Guild],) -> guild
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get the embed for.
Returns
-------
- :obj:`~hikari.guilds.GuildEmbed`
+ hikari.guilds.GuildEmbed
A guild embed object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_GUILD`` permission or are not in
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_GUILD` permission or are not in
the guild.
"""
payload = await self._session.get_guild_embed(
@@ -1791,32 +1784,32 @@ async def update_guild_embed(
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to edit the embed for.
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.GuildChannel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ], optional
+ channel : typing.Union [ hikari.channels.GuildChannel, hikari.bases.Snowflake, int ], optional
If specified, the object or ID of the channel that this embed's
- invite should target. Set to :obj:`~None` to disable invites for this
+ invite should target. Set to `None` to disable invites for this
embed.
- enabled : :obj:`~bool`
+ enabled : bool
If specified, whether this embed should be enabled.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~hikari.guilds.GuildEmbed`
+ hikari.guilds.GuildEmbed
The updated embed object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_GUILD`` permission or are not in
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_GUILD` permission or are not in
the guild.
"""
payload = await self._session.modify_guild_embed(
@@ -1837,24 +1830,24 @@ async def fetch_guild_vanity_url(self, guild: bases.Hashable[guilds.Guild],) ->
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to get the vanity URL for.
Returns
-------
- :obj:`~hikari.invites.VanityUrl`
- A partial invite object containing the vanity URL in the ``code``
+ hikari.invites.VanityUrl
+ A partial invite object containing the vanity URL in the `code`
field.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_GUILD`` permission or are not in
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_GUILD` permission or are not in
the guild.
"""
payload = await self._session.get_guild_vanity_url(
@@ -1867,25 +1860,23 @@ def format_guild_widget_image(self, guild: bases.Hashable[guilds.Guild], *, styl
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to form the widget.
- style : :obj:`~str`
- If specified, the syle of the widget.
+ style : str
+ If specified, the style of the widget.
Returns
-------
- :obj:`~str`
+ str
A URL to retrieve a PNG widget for your guild.
- Note
- ----
- This does not actually make any form of request, and shouldn't be
- awaited. Thus, it doesn't have rate limits either.
+ !!! note
+ This does not actually make any form of request, and shouldn't be
+ awaited. Thus, it doesn't have rate limits either.
- Warning
- -------
- The guild must have the widget enabled in the guild settings for this
- to be valid.
+ !!! warning
+ The guild must have the widget enabled in the guild settings for
+ this to be valid.
"""
return self._session.get_guild_widget_image_url(
guild_id=str(guild.id if isinstance(guild, bases.UniqueEntity) else int(guild)), style=style
@@ -1896,23 +1887,23 @@ async def fetch_guild_webhooks(self, guild: bases.Hashable[guilds.Guild]) -> typ
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID for the guild to get the webhooks from.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~hikari.webhooks.Webhook` ]
+ typing.Sequence [ hikari.webhooks.Webhook ]
A list of webhook objects for the given guild.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_WEBHOOKS`` permission or
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_WEBHOOKS` permission or
aren't a member of the given guild.
"""
payload = await self._session.get_guild_webhooks(
diff --git a/hikari/clients/rest/invite.py b/hikari/clients/rest/invite.py
index 07d5757e2b..ba5cdf0880 100644
--- a/hikari/clients/rest/invite.py
+++ b/hikari/clients/rest/invite.py
@@ -37,23 +37,23 @@ async def fetch_invite(
Parameters
----------
- invite : :obj:`~typing.Union` [ :obj:`~hikari.invites.Invite`, :obj:`~str` ]
+ invite : typing.Union [ hikari.invites.Invite, str ]
The object or code of the wanted invite.
- with_counts : :bool:
+ with_counts : bool
If specified, whether to attempt to count the number of
times the invite has been used.
Returns
-------
- :obj:`~hikari.invites.Invite`
+ hikari.invites.Invite
The requested invite object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the invite is not found.
"""
payload = await self._session.get_invite(invite_code=getattr(invite, "code", invite), with_counts=with_counts)
@@ -64,21 +64,21 @@ async def delete_invite(self, invite: typing.Union[invites.Invite, str]) -> None
Parameters
----------
- invite : :obj:`~typing.Union` [ :obj:`~hikari.invites.Invite`, :obj:`~str` ]
+ invite : typing.Union [ hikari.invites.Invite, str ]
The object or ID for the invite to be deleted.
Returns
-------
- :obj:`~None`
+ None
Nothing, unlike what the API specifies. This is done to maintain
consistency with other calls of a similar nature in this API wrapper.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the invite is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack either ``MANAGE_CHANNELS`` on the channel the invite
- belongs to or ``MANAGE_GUILD`` for guild-global delete.
+ hikari.errors.ForbiddenHTTPError
+ If you lack either `MANAGE_CHANNELS` on the channel the invite
+ belongs to or `MANAGE_GUILD` for guild-global delete.
"""
await self._session.delete_invite(invite_code=getattr(invite, "code", invite))
diff --git a/hikari/clients/rest/me.py b/hikari/clients/rest/me.py
index 121a19c5ca..4cb1b54356 100644
--- a/hikari/clients/rest/me.py
+++ b/hikari/clients/rest/me.py
@@ -16,7 +16,7 @@
#
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
-"""The logic for handling requests to ``@me`` endpoints."""
+"""The logic for handling requests to `@me` endpoints."""
__all__ = ["RESTCurrentUserComponent"]
@@ -35,14 +35,14 @@
class RESTCurrentUserComponent(base.BaseRESTComponent, abc.ABC): # pylint: disable=W0223
- """The REST client component for handling requests to ``@me`` endpoints."""
+ """The REST client component for handling requests to `@me` endpoints."""
async def fetch_me(self) -> users.MyUser:
"""Get the current user that of the token given to the client.
Returns
-------
- :obj:`~hikari.users.MyUser`
+ hikari.users.MyUser
The current user object.
"""
payload = await self._session.get_current_user()
@@ -55,21 +55,21 @@ async def update_me(
Parameters
----------
- username : :obj:`~str`
+ username : str
If specified, the new username string.
- avatar_data : ``hikari.internal.conversions.FileLikeT``, optional
+ avatar_data : hikari.internal.conversions.FileLikeT, optional
If specified, the new avatar image data.
- If it is :obj:`~None`, the avatar is removed.
+ If it is None, the avatar is removed.
Returns
-------
- :obj:`~hikari.users.MyUser`
+ hikari.users.MyUser
The updated user object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you pass username longer than the limit (``2-32``) or an invalid image.
+ hikari.errors.BadRequestHTTPError
+ If you pass username longer than the limit (`2-32`) or an invalid image.
"""
payload = await self._session.modify_current_user(
username=username,
@@ -81,15 +81,15 @@ async def fetch_my_connections(self) -> typing.Sequence[applications.OwnConnecti
"""
Get the current user's connections.
- Note
- ----
- This endpoint can be used with both ``Bearer`` and ``Bot`` tokens but
- will usually return an empty list for bots (with there being some
- exceptions to this, like user accounts that have been converted to bots).
+ !!! note
+ This endpoint can be used with both `Bearer` and `Bot` tokens but
+ will usually return an empty list for bots (with there being some
+ exceptions to this, like user accounts that have been converted to
+ bots).
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~hikari.oauth2.OwnConnection` ]
+ typing.Sequence [ hikari.applications.OwnConnection ]
A list of connection objects.
"""
payload = await self._session.get_current_user_connections()
@@ -108,30 +108,28 @@ def fetch_my_guilds_after(
Parameters
----------
- after : :obj:`~typing.Union` [ :obj:`~datetime.datetime`, :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ after : typing.Union [ datetime.datetime, hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of a guild to get guilds that were created after
it if specified, else this will start at the oldest guild.
- limit : :obj:`~int`
+ limit : int
If specified, the maximum amount of guilds that this paginator
should return.
- Example
- -------
- .. code-block:: python
-
+ Examples
+ --------
async for user in client.fetch_my_guilds_after(after=9876543, limit=1231):
await client.leave_guild(guild)
Returns
-------
- :obj:`~typing.AsyncIterator` [ :obj:`~hikari.oauth2.OwnGuild` ]
+ typing.AsyncIterator [ hikari.applications.OwnGuild ]
An async iterator of partial guild objects.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
"""
@@ -161,23 +159,23 @@ def fetch_my_guilds_before(
Parameters
----------
- before : :obj:`~typing.Union` [ :obj:`~datetime.datetime`, :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ before : typing.Union [ datetime.datetime, hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of a guild to get guilds that were created
before it if specified, else this will start at the newest guild.
- limit : :obj:`~int`
+ limit : int
If specified, the maximum amount of guilds that this paginator
should return.
Returns
-------
- :obj:`~typing.AsyncIterator` [ :obj:`~hikari.oauth2.OwnGuild` ]
+ typing.AsyncIterator [ hikari.applications.OwnGuild ]
An async iterator of partial guild objects.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
"""
@@ -199,14 +197,14 @@ async def leave_guild(self, guild: bases.Hashable[guilds.Guild]) -> None:
Parameters
----------
- guild : :obj:`~typing.Union` [ :obj:`~hikari.guilds.Guild`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ guild : typing.Union [ hikari.guilds.Guild, hikari.bases.Snowflake, int ]
The object or ID of the guild to leave.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
"""
@@ -217,19 +215,19 @@ async def create_dm_channel(self, recipient: bases.Hashable[users.User]) -> _cha
Parameters
----------
- recipient : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ recipient : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
The object or ID of the user to create the new DM channel with.
Returns
-------
- :obj:`~hikari.channels.DMChannel`
+ hikari.channels.DMChannel
The newly created DM channel object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the recipient is not found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
"""
diff --git a/hikari/clients/rest/oauth2.py b/hikari/clients/rest/oauth2.py
index 91f8ab5d91..2c83bc9187 100644
--- a/hikari/clients/rest/oauth2.py
+++ b/hikari/clients/rest/oauth2.py
@@ -34,7 +34,7 @@ async def fetch_my_application_info(self) -> applications.Application:
Returns
-------
- :obj:`~hikari.oauth2.Application`
+ hikari.applications.Application
An application info object.
"""
payload = await self._session.get_current_application_info()
diff --git a/hikari/clients/rest/react.py b/hikari/clients/rest/react.py
index dabac88c3e..4da9df3894 100644
--- a/hikari/clients/rest/react.py
+++ b/hikari/clients/rest/react.py
@@ -46,25 +46,25 @@ async def create_reaction(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to add this reaction in.
- message : :obj:`~typing.Union` [ :obj:`~hikari.messages.Message`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ message : typing.Union [ hikari.messages.Message, hikari.bases.Snowflake, int ]
The object or ID of the message to add the reaction in.
- emoji : :obj:`~typing.Union` [ :obj:`~hikari.emojis.Emoji`, :obj:`~str` ]
+ emoji : typing.Union [ hikari.emojis.Emoji, str ]
The emoji to add. This can either be an emoji object or a string
representation of an emoji. The string representation will be either
- ``"name:id"`` for custom emojis else it's unicode character(s) (can
+ `"name:id"` for custom emojis else it's unicode character(s) (can
be UTF-32).
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If this is the first reaction using this specific emoji on this
- message and you lack the ``ADD_REACTIONS`` permission. If you lack
- ``READ_MESSAGE_HISTORY``, this may also raise this error.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ message and you lack the `ADD_REACTIONS` permission. If you lack
+ `READ_MESSAGE_HISTORY`, this may also raise this error.
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found, or if the emoji is not found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If the emoji is not valid, unknown, or formatted incorrectly.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
@@ -85,26 +85,26 @@ async def delete_reaction(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to add this reaction in.
- message : :obj:`~typing.Union` [ :obj:`~hikari.messages.Message`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ message : typing.Union [ hikari.messages.Message, hikari.bases.Snowflake, int ]
The object or ID of the message to add the reaction in.
- emoji : :obj:`~typing.Union` [ :obj:`~hikari.emojis.Emoji`, :obj:`~str` ]
+ emoji : typing.Union [ hikari.emojis.Emoji, str ]
The emoji to add. This can either be an emoji object or a
string representation of an emoji. The string representation will be
- either ``"name:id"`` for custom emojis else it's unicode
+ either `"name:id"` for custom emojis else it's unicode
character(s) (can be UTF-32).
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If this is the first reaction using this specific emoji on this
- message and you lack the ``ADD_REACTIONS`` permission. If you lack
- ``READ_MESSAGE_HISTORY``, this may also raise this error.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ message and you lack the `ADD_REACTIONS` permission. If you lack
+ `READ_MESSAGE_HISTORY`, this may also raise this error.
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found, or if the emoji is not
found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If the emoji is not valid, unknown, or formatted incorrectly.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
@@ -122,20 +122,20 @@ async def delete_all_reactions(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to get the message from.
- message : :obj:`~typing.Union` [ :obj:`~hikari.messages.Message`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ message : typing.Union [ hikari.messages.Message, hikari.bases.Snowflake, int ]
The object or ID of the message to remove all reactions from.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_MESSAGES`` permission.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_MESSAGES` permission.
"""
await self._session.delete_all_reactions(
channel_id=str(channel.id if isinstance(channel, bases.UniqueEntity) else int(channel)),
@@ -152,24 +152,24 @@ async def delete_all_reactions_for_emoji(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to get the message from.
- message : :obj:`~typing.Union` [ :obj:`~hikari.messages.Message`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ message : typing.Union [ hikari.messages.Message, hikari.bases.Snowflake, int ]
The object or ID of the message to delete the reactions from.
- emoji : :obj:`~typing.Union` [ :obj:`~hikari.emojis.Emoji`, :obj:`~str` ]
- The object or string representatiom of the emoji to delete. The
- string representation will be either ``"name:id"`` for custom emojis
+ emoji : typing.Union [ hikari.emojis.Emoji, str ]
+ The object or string representation of the emoji to delete. The
+ string representation will be either `"name:id"` for custom emojis
else it's unicode character(s) (can be UTF-32).
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message or emoji or user is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_MESSAGES`` permission, or the channel is a
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_MESSAGES` permission, or the channel is a
DM channel.
"""
await self._session.delete_all_reactions_for_emoji(
@@ -194,44 +194,42 @@ def fetch_reactors_after(
Parameters
----------
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.Channel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.Channel, hikari.bases.Snowflake, int ]
The object or ID of the channel to get the message from.
- message : :obj:`~typing.Union` [ :obj:`~hikari.messages.Message`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ message : typing.Union [ hikari.messages.Message, hikari.bases.Snowflake, int ]
The object or ID of the message to get the reactions from.
- emoji : :obj:`~typing.Union` [ :obj:`~hikari.emojis.Emoji`, :obj:`~str` ]
+ emoji : typing.Union [ hikari.emojis.Emoji, str ]
The emoji to get. This can either be it's object or the string
representation of the emoji. The string representation will be
- either ``"name:id"`` for custom emojis else it's unicode
+ either `"name:id"` for custom emojis else it's unicode
character(s) (can be UTF-32).
- after : :obj:`~typing.Union` [ :obj:`~datetime.datetime`, :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ after : typing.Union [ datetime.datetime, hikari.users.User, hikari.bases.Snowflake, int ]
If specified, a object or ID user. If specified, only users with a
snowflake that is lexicographically greater than the value will be
returned.
- limit : :obj:`~str`
+ limit : str
If specified, the limit of the number of users this iterator should
return.
- Example
- -------
- .. code-block:: python
-
+ Examples
+ --------
async for user in client.fetch_reactors_after(channel, message, emoji, after=9876543, limit=1231):
if user.is_bot:
await client.kick_member(channel.guild_id, user)
Returns
-------
- :obj:`~typing.AsyncIterator` [ :obj:`~hikari.users.User` ]
+ typing.AsyncIterator [ hikari.users.User ]
An async iterator of user objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack access to the message.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found.
"""
if isinstance(after, datetime.datetime):
diff --git a/hikari/clients/rest/user.py b/hikari/clients/rest/user.py
index 9e81210b6c..cac74e8dbb 100644
--- a/hikari/clients/rest/user.py
+++ b/hikari/clients/rest/user.py
@@ -35,20 +35,20 @@ async def fetch_user(self, user: bases.Hashable[users.User]) -> users.User:
Parameters
----------
- user : :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ user : typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ]
The object or ID of the user to get.
Returns
-------
- :obj:`~hikari.users.User`
+ hikari.users.User
The requested user object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the user is not found.
"""
payload = await self._session.get_user(
diff --git a/hikari/clients/rest/voice.py b/hikari/clients/rest/voice.py
index d519f8a8a9..59d6b2735b 100644
--- a/hikari/clients/rest/voice.py
+++ b/hikari/clients/rest/voice.py
@@ -35,12 +35,11 @@ async def fetch_voice_regions(self) -> typing.Sequence[voices.VoiceRegion]:
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~hikari.voices.VoiceRegion` ]
+ typing.Sequence [ hikari.voices.VoiceRegion ]
A list of voice regions available
- Note
- ----
- This does not include VIP servers.
+ !!! note
+ This does not include VIP servers.
"""
payload = await self._session.list_voice_regions()
return [voices.VoiceRegion.deserialize(region) for region in payload]
diff --git a/hikari/clients/rest/webhook.py b/hikari/clients/rest/webhook.py
index 7ba3f1c36a..29a293daa3 100644
--- a/hikari/clients/rest/webhook.py
+++ b/hikari/clients/rest/webhook.py
@@ -46,28 +46,28 @@ async def fetch_webhook(
Parameters
----------
- webhook : :obj:`~typing.Union` [ :obj:`~hikari.webhooks.Webhook`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ webhook : typing.Union [ hikari.webhooks.Webhook, hikari.bases.Snowflake, int ]
The object or ID of the webhook to get.
- webhook_token : :obj:`~str`
+ webhook_token : str
If specified, the webhook token to use to get it (bypassing this
- session's provided authorization ``token``).
+ session's provided authorization `token`).
Returns
-------
- :obj:`~hikari.webhooks.Webhook`
+ hikari.webhooks.Webhook
The requested webhook object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the webhook is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you're not in the guild that owns this webhook or
- lack the ``MANAGE_WEBHOOKS`` permission.
- :obj:`~hikari.errors.UnauthorizedHTTPError`
+ lack the `MANAGE_WEBHOOKS` permission.
+ hikari.errors.UnauthorizedHTTPError
If you pass a token that's invalid for the target webhook.
"""
payload = await self._session.get_webhook(
@@ -90,39 +90,39 @@ async def update_webhook(
Parameters
----------
- webhook : :obj:`~typing.Union` [ :obj:`~hikari.webhooks.Webhook`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ webhook : typing.Union [ hikari.webhooks.Webhook, hikari.bases.Snowflake, int ]
The object or ID of the webhook to edit.
- webhook_token : :obj:`~str`
+ webhook_token : str
If specified, the webhook token to use to modify it (bypassing this
- session's provided authorization ``token``).
- name : :obj:`~str`
+ session's provided authorization `token`).
+ name : str
If specified, the new name string.
- avatar_data : ``hikari.internal.conversions.FileLikeT``, optional
- If specified, the new avatar image file object. If :obj:`~None`, then
+ avatar_data : hikari.internal.conversions.FileLikeT, optional
+ If specified, the new avatar image file object. If `None`, then
it is removed.
- channel : :obj:`~typing.Union` [ :obj:`~hikari.channels.GuildChannel`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ channel : typing.Union [ hikari.channels.GuildChannel, hikari.bases.Snowflake, int ]
If specified, the object or ID of the new channel the given
webhook should be moved to.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~hikari.webhooks.Webhook`
+ hikari.webhooks.Webhook
The updated webhook object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the webhook or the channel aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_WEBHOOKS`` permission or
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_WEBHOOKS` permission or
aren't a member of the guild this webhook belongs to.
- :obj:`~hikari.errors.UnauthorizedHTTPError`
+ hikari.errors.UnauthorizedHTTPError
If you pass a token that's invalid for the target webhook.
"""
payload = await self._session.modify_webhook(
@@ -148,23 +148,23 @@ async def delete_webhook(self, webhook: bases.Hashable[webhooks.Webhook], *, web
Parameters
----------
- webhook : :obj:`~typing.Union` [ :obj:`~hikari.webhooks.Webhook`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ webhook : typing.Union [ hikari.webhooks.Webhook, hikari.bases.Snowflake, int ]
The object or ID of the webhook to delete
- webhook_token : :obj:`~str`
+ webhook_token : str
If specified, the webhook token to use to delete it (bypassing this
- session's provided authorization ``token``).
+ session's provided authorization `token`).
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the webhook is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_WEBHOOKS`` permission or
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_WEBHOOKS` permission or
aren't a member of the guild this webhook belongs to.
- :obj:`~hikari.errors.UnauthorizedHTTPError`
+ hikari.errors.UnauthorizedHTTPError
If you pass a token that's invalid for the target webhook.
"""
await self._session.delete_webhook(
@@ -192,65 +192,64 @@ async def execute_webhook(
Parameters
----------
- webhook : :obj:`~typing.Union` [ :obj:`~hikari.webhooks.Webhook`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ]
+ webhook : typing.Union [ hikari.webhooks.Webhook, hikari.bases.Snowflake, int ]
The object or ID of the webhook to execute.
- webhook_token : :obj:`~str`
+ webhook_token : str
The token of the webhook to execute.
- content : :obj:`~str`
+ content : str
If specified, the message content to send with the message.
- username : :obj:`~str`
+ username : str
If specified, the username to override the webhook's username
for this request.
- avatar_url : :obj:`~str`
+ avatar_url : str
If specified, the url of an image to override the webhook's
avatar with for this request.
- tts : :obj:`~bool`
+ tts : bool
If specified, whether the message will be sent as a TTS message.
- wait : :obj:`~bool`
+ wait : bool
If specified, whether this request should wait for the webhook
to be executed and return the resultant message object.
- file : ``hikari.media.IO``
+ file : hikari.media.IO
If specified, this is a file object to send along with the webhook
- as defined in :mod:`hikari.media`.
- embeds : :obj:`~typing.Sequence` [ :obj:`~hikari.embeds.Embed` ]
- If specified, a sequence of ``1`` to ``10`` embed objects to send
+ as defined in `hikari.media`.
+ embeds : typing.Sequence [ hikari.embeds.Embed ]
+ If specified, a sequence of `1` to `10` embed objects to send
with the embed.
- mentions_everyone : :obj:`~bool`
- Whether ``@everyone`` and ``@here`` mentions should be resolved by
- discord and lead to actual pings, defaults to :obj:`~True`.
- user_mentions : :obj:`~typing.Union` [ :obj:`~typing.Collection` [ :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ], :obj:`~bool` ]
+ mentions_everyone : bool
+ Whether `@everyone` and `@here` mentions should be resolved by
+ discord and lead to actual pings, defaults to `True`.
+ user_mentions : typing.Union [ typing.Collection [ typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ], bool ]
Either an array of user objects/IDs to allow mentions for,
- :obj:`~True` to allow all user mentions or :obj:`~False` to block all
- user mentions from resolving, defaults to :obj:`~True`.
- role_mentions : :obj:`~typing.Union` [ :obj:`~typing.Collection` [ :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ] ], :obj:`~bool` ]
+ `True` to allow all user mentions or `False` to block all
+ user mentions from resolving, defaults to `True`.
+ role_mentions : typing.Union [ typing.Collection [ typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ] ], bool ]
Either an array of guild role objects/IDs to allow mentions for,
- :obj:`~True` to allow all role mentions or :obj:`~False` to block all
- role mentions from resolving, defaults to :obj:`~True`.
+ `True` to allow all role mentions or `False` to block all
+ role mentions from resolving, defaults to `True`.
Returns
-------
- :obj:`~hikari.messages.Message`, optional
- The created message object, if ``wait`` is :obj:`~True`, else
- :obj:`~None`.
+ hikari.messages.Message, optional
+ The created message object, if `wait` is `True`, else `None`.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel ID or webhook ID is not found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
This can be raised if the file is too large; if the embed exceeds
the defined limits; if the message content is specified only and
- empty or greater than ``2000`` characters; if neither content, file
+ empty or greater than `2000` characters; if neither content, file
or embeds are specified.
If any invalid snowflake IDs are passed; a snowflake may be invalid
due to it being outside of the range of a 64 bit integer.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permissions to send to this channel.
- :obj:`~hikari.errors.UnauthorizedHTTPError`
+ hikari.errors.UnauthorizedHTTPError
If you pass a token that's invalid for the target webhook.
- :obj:`~ValueError`
+ ValueError
If more than 100 unique objects/entities are passed for
- ``role_mentions`` or ``user_mentions``.
+ `role_mentions` or `user_mentions`.
"""
payload = await self._session.execute_webhook(
webhook_id=str(webhook.id if isinstance(webhook, bases.UniqueEntity) else int(webhook)),
@@ -288,9 +287,10 @@ def safe_webhook_execute(
) -> typing.Coroutine[typing.Any, typing.Any, typing.Optional[_messages.Message]]:
"""Execute a webhook to create a message with mention safety.
- This endpoint has the same signature as :attr:`execute_webhook` with
- the only difference being that ``mentions_everyone``,
- ``user_mentions`` and ``role_mentions`` default to :obj:`~False`.
+ This endpoint has the same signature as
+ `RESTWebhookComponent.execute_webhook` with the only difference being
+ that `mentions_everyone`, `user_mentions` and `role_mentions` default to
+ `False`.
"""
return self.execute_webhook(
webhook=webhook,
diff --git a/hikari/clients/runnable.py b/hikari/clients/runnable.py
index 4525a9b583..bf73bb68dd 100644
--- a/hikari/clients/runnable.py
+++ b/hikari/clients/runnable.py
@@ -33,10 +33,8 @@ class RunnableClient(abc.ABC):
__slots__ = ("logger",)
- #: The logger to use for this client.
- #:
- #: :type: :obj:`~logging.Logger`
logger: logging.Logger
+ """The logger to use for this client."""
@abc.abstractmethod
def __init__(self, logger: typing.Union[logging.Logger, logging.LoggerAdapter]) -> None:
@@ -57,12 +55,12 @@ async def join(self) -> None:
def run(self) -> None:
"""Execute this component on an event loop.
- Performs the same job as :meth:`start`, but provides additional
+ Performs the same job as `RunnableClient.start`, but provides additional
preparation such as registering OS signal handlers for interrupts,
and preparing the initial event loop.
This enables the client to be run immediately without having to
- set up the :mod:`asyncio` event loop manually first.
+ set up the `asyncio` event loop manually first.
"""
loop = asyncio.get_event_loop()
diff --git a/hikari/clients/shards.py b/hikari/clients/shards.py
index 9317c41272..704d559491 100644
--- a/hikari/clients/shards.py
+++ b/hikari/clients/shards.py
@@ -16,13 +16,13 @@
#
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
-"""Provides a facade around :obj:`~hikari.net.shards.Shard`.
+"""Provides a facade around `hikari.net.shards.Shard`.
This handles parsing and initializing the object from a configuration, as
well as restarting it if it disconnects.
Additional functions and coroutines are provided to update the presence on the
-shard using models defined in :mod:`hikari`.
+shard using models defined in `hikari`.
"""
from __future__ import annotations
@@ -56,27 +56,29 @@
class ShardState(enum.IntEnum):
"""Describes the state of a shard."""
- #: The shard is not running.
NOT_RUNNING = 0
+ """The shard is not running."""
- #: The shard is undergoing the initial connection handshake.
CONNECTING = enum.auto()
+ """The shard is undergoing the initial connection handshake."""
- #: The initialization handshake has completed. We are waiting for the shard
- #: to receive the ``READY`` event.
WAITING_FOR_READY = enum.auto()
+ """The initialization handshake has completed.
+
+ We are waiting for the shard to receive the `READY` event.
+ """
- #: The shard is ``READY``.
READY = enum.auto()
+ """The shard is `READY`."""
- #: The shard has sent a request to ``RESUME`` and is waiting for a response.
RESUMING = enum.auto()
+ """The shard has sent a request to `RESUME` and is waiting for a response."""
- #: The shard is currently shutting down permanently.
STOPPING = enum.auto()
+ """The shard is currently shutting down permanently."""
- #: The shard has shut down and is no longer connected.
STOPPED = enum.auto()
+ """The shard has shut down and is no longer connected."""
def __str__(self) -> str:
return self.name
@@ -90,187 +92,107 @@ class ShardClient(runnable.RunnableClient, abc.ABC):
@property
@abc.abstractmethod
def shard_id(self) -> int:
- """Shard ID.
-
- Returns
- -------
- :obj:`~int`
- The 0-indexed shard ID.
- """
+ """Shard ID (this is 0-indexed)."""
@property
@abc.abstractmethod
def shard_count(self) -> int:
- """Shard count.
-
- Returns
- -------
- :obj:`~int`
- The number of shards that make up this bot.
- """
+ """Count of how many shards make up this bot."""
@property
@abc.abstractmethod
def status(self) -> guilds.PresenceStatus:
- """User status for this shard.
-
- Returns
- -------
- :obj:`~hikari.guilds.PresenceStatus`
- The current user status for this shard.
- """
+ """User status for this shard."""
@property
@abc.abstractmethod
def activity(self) -> typing.Optional[gateway_entities.Activity]:
"""Activity for the user status for this shard.
- Returns
- -------
- :obj:`~hikari.gateway_entities.GatewayActivity`, optional
- The current activity for the user on this shard, or :obj:`~None` if
- there is no activity.
+ This will be `None` if there is no activity.
"""
@property
@abc.abstractmethod
def idle_since(self) -> typing.Optional[datetime.datetime]:
- """Timestamp when the user of this shard appeared to be idle.
+ """Timestamp of when the user of this shard appeared to be idle.
- Returns
- -------
- :obj:`~datetime.datetime`, optional
- The timestamp when the user of this shard appeared to be idle, or
- :obj:`~None` if not applicable.
+ This will be `None` if not applicable.
"""
@property
@abc.abstractmethod
def is_afk(self) -> bool:
- """Whether the user is AFK or not.
-
- Returns
- -------
- :obj:`~bool`
- :obj:`~True` if the user is AFK, :obj:`~False` otherwise.
- """
+ """Whether the user is appearing as AFK or not.."""
@property
@abc.abstractmethod
def heartbeat_latency(self) -> float:
- """Latency between sending a HEARTBEAT and receiving an ACK.
+ """Latency between sending a HEARTBEAT and receiving an ACK in seconds.
- Returns
- -------
- :obj:`~float`
- The heartbeat latency in seconds. This will be ``float('nan')``
- until the first heartbeat is performed.
+ This will be `float("nan")` until the first heartbeat is performed.
"""
@property
@abc.abstractmethod
def heartbeat_interval(self) -> float:
- """Time period to wait between sending HEARTBEAT payloads.
+ """Time period to wait between sending HEARTBEAT payloads in seconds.
- Returns
- -------
- :obj:`~float`
- The heartbeat interval in seconds. This will be ``float('nan')``
- until the connection has received a ``HELLO`` payload.
+ This will be `float("nan")` until the connection has received a `HELLO`
+ payload.
"""
@property
@abc.abstractmethod
def disconnect_count(self) -> int:
- """Count of number of times the internal connection has disconnected.
-
- Returns
- -------
- :obj:`~int`
- The number of disconnects this shard has performed.
- """
+ """Count of number of times this shard's connection has disconnected."""
@property
@abc.abstractmethod
def reconnect_count(self) -> int:
- """Count of number of times the internal connection has reconnected.
+ """Count of number of times this shard's connection has reconnected.
This includes RESUME and re-IDENTIFY events.
-
- Returns
- -------
- :obj:`~int`
- The number of reconnects this shard has performed.
"""
@property
@abc.abstractmethod
def connection_state(self) -> ShardState:
- """State of this shard.
-
- Returns
- -------
- :obj:`~ShardState`
- The state of this shard.
- """
+ """State of this shard's connection."""
@property
@abc.abstractmethod
def is_connected(self) -> bool:
- """Whether the shard is connected or not.
-
- Returns
- -------
- :obj:`~bool`
- :obj:`~True` if connected; :obj:`~False` otherwise.
- """
+ """Whether the shard is connected or not."""
@property
@abc.abstractmethod
def seq(self) -> typing.Optional[int]:
"""Sequence ID of the shard.
- Returns
- -------
- :obj:`~int`, optional
- The sequence number for the shard. This is the number of payloads
- that have been received since an ``IDENTIFY`` was sent.
+ This is the number of payloads that have been received since the last
+ `IDENTIFY` was sent.
"""
@property
@abc.abstractmethod
def session_id(self) -> typing.Optional[str]:
- """Session ID.
+ """Session ID of the shard connection.
- Returns
- -------
- :obj:`~str`, optional
- The session ID for the shard connection, if there is one. If not,
- then :obj:`~None`.
+ Will be `None` if there is no session.
"""
@property
@abc.abstractmethod
def version(self) -> float:
- """Version being used for the gateway API.
-
- Returns
- -------
- :obj:`~int`
- The API version being used.
- """
+ """Version being used for the gateway API."""
@property
@abc.abstractmethod
def intents(self) -> typing.Optional[_intents.Intent]:
- """Intent values that this connection is using.
-
- Returns
- -------
- :obj:`~hikari.intents.Intent`, optional
- A :obj:`~enum.IntFlag` enum containing each intent that is set. If
- intents are not being used at all, then this will return
- :obj:`~None` instead.
+ """Intents that are in use for the shard connection.
+
+ If intents are not being used at all, then this will be `None` instead.
"""
@abc.abstractmethod
@@ -288,20 +210,19 @@ async def update_presence(
Any arguments that you do not explicitly provide some value for will
not be changed.
- Warnings
- --------
- This will fail if the shard is not online.
+ !!! warning
+ This will fail if the shard is not online.
Parameters
----------
- status : :obj:`~hikari.guilds.PresenceStatus`
+ status : hikari.guilds.PresenceStatus
If specified, the new status to set.
- activity : :obj:`~hikari.gateway_entities.GatewayActivity`, optional
+ activity : hikari.gateway_entities.Activity, optional
If specified, the new activity to set.
- idle_since : :obj:`~datetime.datetime`, optional
+ idle_since : datetime.datetime, optional
If specified, the time to show up as being idle since, or
- :obj:`~None` if not applicable.
- is_afk : :obj:`~bool`
+ `None` if not applicable.
+ is_afk : bool
If specified, whether the user should be marked as AFK.
"""
@@ -311,35 +232,34 @@ class ShardClientImpl(ShardClient):
This contains several abstractions to enable usage of the low
level gateway network interface with the higher level constructs
- in :mod:`hikari`.
+ in `hikari`.
Parameters
----------
- shard_id : :obj:`~int`
+ shard_id : int
The ID of this specific shard.
- shard_id : :obj:`~int`
+ shard_id : int
The number of shards that make up this distributed application.
- config : :obj:`~hikari.clients.configs.WebsocketConfig`
+ config : hikari.clients.configs.GatewayConfig
The gateway configuration to use to initialize this shard.
- raw_event_consumer_impl : :obj:`~hikari.state.raw_event_consumers.RawEventConsumer`
+ raw_event_consumer_impl : hikari.state.consumers.RawEventConsumer
The consumer of a raw event.
- url : :obj:`~str`
+ url : str
The URL to connect the gateway to.
- dispatcher : :obj:`~hikari.state.event_dispatchers.EventDispatcher`, optional
+ dispatcher : hikari.state.dispatchers.EventDispatcher, optional
The high level event dispatcher to use for dispatching start and stop
- events. Set this to :obj:`~None` to disable that functionality (useful if
+ events. Set this to `None` to disable that functionality (useful if
you use a gateway manager to orchestrate multiple shards instead and
- provide this functionality there). Defaults to :obj:`~None` if
+ provide this functionality there). Defaults to `None` if
unspecified.
- Notes
- -----
- Generally, you want to use
- :obj:`~hikari.clients.gateway_managers.GatewayManager` rather than this class
- directly, as that will handle sharding where enabled and applicable, and
- provides a few more bits and pieces that may be useful such as state
- management and event dispatcher integration. and If you want to customize
- this, you can subclass it and simply override anything you want.
+ !!! note
+ Generally, you want to use
+ `hikari.clients.bot_base.BotBase` rather than this class
+ directly, as that will handle sharding where enabled and applicable,
+ and provides a few more bits and pieces that may be useful such as state
+ management and event dispatcher integration. and If you want to customize
+ this, you can subclass it and simply override anything you want.
"""
__slots__ = (
@@ -467,7 +387,7 @@ def intents(self) -> typing.Optional[_intents.Intent]:
async def start(self):
"""Connect to the gateway on this shard and keep the connection alive.
- This will wait for the shard to dispatch a ``READY`` event, and
+ This will wait for the shard to dispatch a `READY` event, and
then return.
"""
if self._shard_state not in (ShardState.NOT_RUNNING, ShardState.STOPPED):
diff --git a/hikari/clients/test.py b/hikari/clients/test.py
index 26bccd5e63..6c65fbd9fd 100644
--- a/hikari/clients/test.py
+++ b/hikari/clients/test.py
@@ -68,7 +68,7 @@ def _supports_color():
@click.option("--verify-ssl", default=True, type=click.BOOL, help="Enable or disable SSL verification.")
@click.option("--version", default=6, type=click.IntRange(min=6), help="Version of the gateway to use.")
def run_gateway(compression, color, debug, intents, logger, shards, token, verify_ssl, version) -> None:
- """:mod:`click` command line client for running a test gateway connection.
+ """`click` command line client for running a test gateway connection.
This is provided for internal testing purposes for benchmarking API
stability, etc.
diff --git a/hikari/colors.py b/hikari/colors.py
index 1dbf659b09..313e47cc22 100644
--- a/hikari/colors.py
+++ b/hikari/colors.py
@@ -16,13 +16,7 @@
#
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
-"""Model that represents a common RGB color and provides simple conversions to other common color systems.
-
-.. inheritance-diagram::
- builtins.int
- hikari.colors
- :parts: 1
-"""
+"""Model that represents a common RGB color and provides simple conversions to other common color systems."""
from __future__ import annotations
__all__ = ["Color", "ColorCompatibleT"]
@@ -38,8 +32,8 @@ class Color(int, typing.SupportsInt):
This value is immutable.
- This is a specialization of :obj:`~int` which provides alternative overrides for common methods and color system
- conversions.
+ This is a specialization of `int` which provides alternative overrides for
+ common methods and color system conversions.
This currently supports:
@@ -53,7 +47,6 @@ class Color(int, typing.SupportsInt):
Examples
--------
Examples of conversions to given formats include:
- .. code-block::python
>>> c = Color(0xFF051A)
Color(r=0xff, g=0x5, b=0x1a)
@@ -72,7 +65,6 @@ class Color(int, typing.SupportsInt):
Alternatively, if you have an arbitrary input in one of the above formats that you wish to become a color, you can
use the get-attribute operator on the class itself to automatically attempt to resolve the color:
- .. code-block::python
>>> Color[0xFF051A]
Color(r=0xff, g=0x5, b=0x1a)
@@ -92,7 +84,6 @@ class Color(int, typing.SupportsInt):
Color(r=0xff, g=0x5, b=0x1a)
Examples of initialization of Color objects from given formats include:
- .. code-block::python
>>> c = Color(16712986)
Color(r=0xff, g=0x5, b=0x1a)
@@ -146,11 +137,11 @@ def rgb_float(self) -> typing.Tuple[float, float, float]:
def hex_code(self) -> str:
"""Six-digit hexadecimal color code for this Color.
- This is prepended with a ``#`` symbol, and will be in upper case.
+ This is prepended with a `#` symbol, and will be in upper case.
- Example
- -------
- ``#1A2B3C``
+ Examples
+ --------
+ `#1A2B3C`
"""
return "#" + self.raw_hex_code
@@ -158,9 +149,9 @@ def hex_code(self) -> str:
def raw_hex_code(self) -> str:
"""Raw hex code.
- Example
- -------
- ``1A2B3C``
+ Examples
+ --------
+ `1A2B3C`
"""
components = self.rgb
return "".join(hex(c)[2:].zfill(2) for c in components).upper()
@@ -168,33 +159,33 @@ def raw_hex_code(self) -> str:
# Ignore docstring not starting in an imperative mood
@property
def is_web_safe(self) -> bool: # noqa: D401
- """:obj:`~True` if the color is web safe, :obj:`~False` otherwise."""
+ """`True` if the color is web safe, `False` otherwise."""
hex_code = self.raw_hex_code
return all(_all_same(*c) for c in (hex_code[:2], hex_code[2:4], hex_code[4:]))
@classmethod
def from_rgb(cls, red: int, green: int, blue: int) -> Color:
- """Convert the given RGB to a :obj:`~Color` object.
+ """Convert the given RGB to a `Color` object.
Each channel must be withing the range [0, 255] (0x0, 0xFF).
Parameters
----------
- red : :obj:`~int`
+ red : int
Red channel.
- green : :obj:`~int`
+ green : int
Green channel.
- blue : :obj:`~int`
+ blue : int
Blue channel.
Returns
-------
- :obj:`~Color`
+ Color
A Color object.
Raises
------
- :obj:`~ValueError`
+ ValueError
If red, green, or blue are outside the range [0x0, 0xFF].
"""
assertions.assert_in_range(red, 0, 0xFF, "red")
@@ -205,28 +196,28 @@ def from_rgb(cls, red: int, green: int, blue: int) -> Color:
@classmethod
def from_rgb_float(cls, red_f: float, green_f: float, blue_f: float) -> Color:
- """Convert the given RGB to a :obj:`~Color` object.
+ """Convert the given RGB to a `Color` object.
The colorspace represented values have to be within the
range [0, 1].
Parameters
----------
- red_f : :obj:`~float`
+ red_f : float
Red channel.
- green_f : :obj:`~float`
+ green_f : float
Green channel.
- blue_f : :obj:`~float`
+ blue_f : float
Blue channel.
Returns
-------
- :obj:`~Color`
+ Color
A Color object.
Raises
------
- :obj:`~ValueError`
+ ValueError
If red, green or blue are outside the range [0, 1].
"""
assertions.assert_in_range(red_f, 0, 1, "red")
@@ -237,26 +228,26 @@ def from_rgb_float(cls, red_f: float, green_f: float, blue_f: float) -> Color:
@classmethod
def from_hex_code(cls, hex_code: str) -> Color:
- """Convert the given hexadecimal color code to a :obj:`~Color`.
+ """Convert the given hexadecimal color code to a `Color`.
The inputs may be of the following format (case insensitive):
- ``1a2``, ``#1a2``, ``0x1a2`` (for websafe colors), or
- ``1a2b3c``, ``#1a2b3c``, ``0x1a2b3c`` (for regular 3-byte color-codes).
+ `1a2`, `#1a2`, `0x1a2` (for websafe colors), or
+ `1a2b3c`, `#1a2b3c`, `0x1a2b3c` (for regular 3-byte color-codes).
Parameters
----------
- hex_code : :obj:`~str`
+ hex_code : str
A hexadecimal color code to parse.
Returns
-------
- :obj:`~Color`
+ Color
A corresponding Color object.
Raises
------
- :obj:`~ValueError`
- If ``hex_code`` is not a hexadecimal or is a inalid length.
+ ValueError
+ If `hex_code` is not a hexadecimal or is a invalid length.
"""
if hex_code.startswith("#"):
hex_code = hex_code[1:]
@@ -279,16 +270,16 @@ def from_hex_code(cls, hex_code: str) -> Color:
@classmethod
def from_int(cls, i: typing.SupportsInt) -> Color:
- """Convert the given :obj:`~typing.SupportsInt` to a :obj:`~Color`.
+ """Convert the given `typing.SupportsInt` to a `Color`.
Parameters
----------
- i : :obj:`~typing.SupportsInt`
+ i : typing.SupportsInt
The raw color integer.
Returns
-------
- :obj:`~Color`
+ Color
The Color object.
"""
return cls(i)
@@ -296,23 +287,23 @@ def from_int(cls, i: typing.SupportsInt) -> Color:
# Partially chose to override these as the docstrings contain typos according to Sphinx.
@classmethod
def from_bytes(cls, bytes_: typing.Sequence[int], byteorder: str, *, signed: bool = True) -> Color:
- """Convert the bytes to a :obj:`~Color`.
+ """Convert the bytes to a `Color`.
Parameters
----------
- bytes_ : :obj:`~typing.Iterable` [ :obj:`~int` ]
- A iterable of :obj:`~int` byte values.
+ bytes_ : typing.Iterable [ int ]
+ A iterable of int byte values.
- byteorder : :obj:`~str`
+ byteorder : str
The endianess of the value represented by the bytes.
- Can be ``"big"`` endian or ``"little"`` endian.
+ Can be `"big"` endian or `"little"` endian.
- signed : :obj:`~bool`
+ signed : bool
Whether the value is signed or unsigned.
Returns
-------
- :obj:`~Color`
+ Color
The Color object.
"""
return Color(int.from_bytes(bytes_, byteorder, signed=signed))
@@ -322,19 +313,19 @@ def to_bytes(self, length: int, byteorder: str, *, signed: bool = True) -> bytes
Parameters
----------
- length : :obj:`~int`
- The number of bytes to produce. Should be around ``3``, but not less.
+ length : int
+ The number of bytes to produce. Should be around `3`, but not less.
- byteorder : :obj:`~str`
+ byteorder : str
The endianess of the value represented by the bytes.
- Can be ``"big"`` endian or ``"little"`` endian.
+ Can be `"big"` endian or `"little"` endian.
- signed : :obj:`~bool`
+ signed : bool
Whether the value is signed or unsigned.
Returns
-------
- :obj:`~bytes`
+ bytes
The bytes representation of the Color.
"""
return int(self).to_bytes(length, byteorder, signed=signed)
@@ -377,7 +368,6 @@ def _all_same(first, *rest):
return True
-#: Any type that can be converted into a color object.
ColorCompatibleT = typing.Union[
Color,
typing.SupportsInt,
@@ -387,3 +377,4 @@ def _all_same(first, *rest):
typing.Sequence[typing.SupportsFloat],
str,
]
+"""Any type that can be converted into a color object."""
diff --git a/hikari/colours.py b/hikari/colours.py
index 6e1e19bace..fc56d0f23f 100644
--- a/hikari/colours.py
+++ b/hikari/colours.py
@@ -16,7 +16,7 @@
#
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
-"""Alias for the :mod:`hikari.colors` module."""
+"""Alias for the `hikari.colors` module."""
__all__ = ["Colour", "ColourCompatibleT"]
from hikari.colors import Color as Colour
diff --git a/hikari/embeds.py b/hikari/embeds.py
index 451f09eedf..1d95892c5b 100644
--- a/hikari/embeds.py
+++ b/hikari/embeds.py
@@ -44,30 +44,23 @@
class EmbedFooter(bases.HikariEntity, marshaller.Deserializable, marshaller.Serializable):
"""Represents an embed footer."""
- #: The footer text.
- #:
- #: :type: :obj:`~str`
text: str = marshaller.attrib(deserializer=str, serializer=str)
+ """The footer text."""
- #: The URL of the footer icon.
- #:
- #: :type: :obj:`~str`, optional
icon_url: typing.Optional[str] = marshaller.attrib(
deserializer=str, serializer=str, if_undefined=None, default=None
)
+ """The URL of the footer icon."""
- #: The proxied URL of the footer icon.
- #:
- #: Note
- #: ----
- #: This field cannot be set by bots or webhooks while sending an embed and
- #: will be ignored during serialization.
- #:
- #:
- #: :type: :obj:`~str`, optional
proxy_icon_url: typing.Optional[str] = marshaller.attrib(
deserializer=str, transient=True, if_undefined=None, default=None
)
+ """The proxied URL of the footer icon.
+
+ !!! note
+ This field cannot be set by bots or webhooks while sending an embed and
+ will be ignored during serialization.
+ """
@marshaller.marshallable()
@@ -75,45 +68,34 @@ class EmbedFooter(bases.HikariEntity, marshaller.Deserializable, marshaller.Seri
class EmbedImage(bases.HikariEntity, marshaller.Deserializable, marshaller.Serializable):
"""Represents an embed image."""
- #: The URL of the image.
- #:
- #: :type: :obj:`~str`, optional
url: typing.Optional[str] = marshaller.attrib(deserializer=str, serializer=str, if_undefined=None, default=None)
+ """The URL of the image."""
- #: The proxied URL of the image.
- #:
- #: Note
- #: ----
- #: This field cannot be set by bots or webhooks while sending an embed and
- #: will be ignored during serialization.
- #:
- #:
- #: :type: :obj:`~str`, optional
proxy_url: typing.Optional[str] = marshaller.attrib(
deserializer=str, transient=True, if_undefined=None, default=None
)
+ """The proxied URL of the image.
+
+ !!! note
+ This field cannot be set by bots or webhooks while sending an embed and
+ will be ignored during serialization.
+ """
- #: The height of the image.
- #:
- #: Note
- #: ----
- #: This field cannot be set by bots or webhooks while sending an embed and
- #: will be ignored during serialization.
- #:
- #:
- #: :type: :obj:`~int`, optional
height: typing.Optional[int] = marshaller.attrib(deserializer=int, transient=True, if_undefined=None, default=None)
+ """The height of the image.
+
+ !!! note
+ This field cannot be set by bots or webhooks while sending an embed and
+ will be ignored during serialization.
+ """
- #: The width of the image.
- #:
- #: Note
- #: ----
- #: This field cannot be set by bots or webhooks while sending an embed and
- #: will be ignored during serialization.
- #:
- #:
- #: :type: :obj:`~int`, optional
width: typing.Optional[int] = marshaller.attrib(deserializer=int, transient=True, if_undefined=None, default=None)
+ """The width of the image.
+
+ !!! note
+ This field cannot be set by bots or webhooks while sending an embed and
+ will be ignored during serialization.
+ """
@marshaller.marshallable()
@@ -121,45 +103,34 @@ class EmbedImage(bases.HikariEntity, marshaller.Deserializable, marshaller.Seria
class EmbedThumbnail(bases.HikariEntity, marshaller.Deserializable, marshaller.Serializable):
"""Represents an embed thumbnail."""
- #: The URL of the thumbnail.
- #:
- #: :type: :obj:`~str`, optional
url: typing.Optional[str] = marshaller.attrib(deserializer=str, serializer=str, if_undefined=None, default=None)
+ """The URL of the thumbnail."""
- #: The proxied URL of the thumbnail.
- #:
- #: Note
- #: ----
- #: This field cannot be set by bots or webhooks while sending an embed and
- #: will be ignored during serialization.
- #:
- #:
- #: :type: :obj:`~str`, optional
proxy_url: typing.Optional[str] = marshaller.attrib(
deserializer=str, transient=True, if_undefined=None, default=None
)
+ """The proxied URL of the thumbnail.
+
+ !!! note
+ This field cannot be set by bots or webhooks while sending an embed and
+ will be ignored during serialization.
+ """
- #: The height of the thumbnail.
- #:
- #: Note
- #: ----
- #: This field cannot be set by bots or webhooks while sending an embed and
- #: will be ignored during serialization.
- #:
- #:
- #: :type: :obj:`~int`, optional
height: typing.Optional[int] = marshaller.attrib(deserializer=int, transient=True, if_undefined=None, default=None)
+ """The height of the thumbnail.
+
+ !!! note
+ This field cannot be set by bots or webhooks while sending an embed and
+ will be ignored during serialization.
+ """
- #: The width of the thumbnail.
- #:
- #: Note
- #: ----
- #: This field cannot be set by bots or webhooks while sending an embed and
- #: will be ignored during serialization.
- #:
- #:
- #: :type: :obj:`~int`, optional
width: typing.Optional[int] = marshaller.attrib(deserializer=int, transient=True, if_undefined=None, default=None)
+ """The width of the thumbnail.
+
+ !!! note
+ This field cannot be set by bots or webhooks while sending an embed and
+ will be ignored during serialization.
+ """
@marshaller.marshallable()
@@ -167,26 +138,20 @@ class EmbedThumbnail(bases.HikariEntity, marshaller.Deserializable, marshaller.S
class EmbedVideo(bases.HikariEntity, marshaller.Deserializable):
"""Represents an embed video.
- Note
- ----
- This embed attached object cannot be sent by bots or webhooks while sending
- an embed and therefore shouldn't be initiated like the other embed objects.
+ !!! note
+ This embed attached object cannot be sent by bots or webhooks while
+ sending an embed and therefore shouldn't be initiated like the other
+ embed objects.
"""
- #: The URL of the video.
- #:
- #: :type: :obj:`~str`, optional
url: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The URL of the video."""
- #: The height of the video.
- #:
- #: :type: :obj:`~int`, optional
height: typing.Optional[int] = marshaller.attrib(deserializer=int, if_undefined=None, default=None)
+ """The height of the video."""
- #: The width of the video.
- #:
- #: :type: :obj:`~int`, optional
width: typing.Optional[int] = marshaller.attrib(deserializer=int, if_undefined=None, default=None)
+ """The width of the video."""
@marshaller.marshallable()
@@ -194,21 +159,17 @@ class EmbedVideo(bases.HikariEntity, marshaller.Deserializable):
class EmbedProvider(bases.HikariEntity, marshaller.Deserializable):
"""Represents an embed provider.
- Note
- ----
- This embed attached object cannot be sent by bots or webhooks while sending
- an embed and therefore shouldn't be initiated like the other embed objects.
+ !!! note
+ This embed attached object cannot be sent by bots or webhooks while
+ sending an embed and therefore shouldn't be initiated like the other
+ embed objects.
"""
- #: The name of the provider.
- #:
- #: :type: :obj:`~str`, optional
name: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The name of the provider."""
- #: The URL of the provider.
- #:
- #: :type: :obj:`~str`, optional
url: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, if_none=None, default=None)
+ """The URL of the provider."""
@marshaller.marshallable()
@@ -216,35 +177,26 @@ class EmbedProvider(bases.HikariEntity, marshaller.Deserializable):
class EmbedAuthor(bases.HikariEntity, marshaller.Deserializable, marshaller.Serializable):
"""Represents an embed author."""
- #: The name of the author.
- #:
- #: :type: :obj:`~str`, optional
name: typing.Optional[str] = marshaller.attrib(deserializer=str, serializer=str, if_undefined=None, default=None)
+ """The name of the author."""
- #: The URL of the author.
- #:
- #: :type: :obj:`~str`, optional
url: typing.Optional[str] = marshaller.attrib(deserializer=str, serializer=str, if_undefined=None, default=None)
+ """The URL of the author."""
- #: The URL of the author icon.
- #:
- #: :type: :obj:`~str`, optional
icon_url: typing.Optional[str] = marshaller.attrib(
deserializer=str, serializer=str, if_undefined=None, default=None
)
+ """The URL of the author icon."""
- #: The proxied URL of the author icon.
- #:
- #: Note
- #: ----
- #: This field cannot be set by bots or webhooks while sending an embed and
- #: will be ignored during serialization.
- #:
- #:
- #: :type: :obj:`~str`, optional
proxy_icon_url: typing.Optional[str] = marshaller.attrib(
deserializer=str, transient=True, if_undefined=None, default=None
)
+ """The proxied URL of the author icon.
+
+ !!! note
+ This field cannot be set by bots or webhooks while sending an embed and
+ will be ignored during serialization.
+ """
@marshaller.marshallable()
@@ -252,22 +204,16 @@ class EmbedAuthor(bases.HikariEntity, marshaller.Deserializable, marshaller.Seri
class EmbedField(bases.HikariEntity, marshaller.Deserializable, marshaller.Serializable):
"""Represents a field in a embed."""
- #: The name of the field.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str, serializer=str)
+ """The name of the field."""
- #: The value of the field.
- #:
- #: :type: :obj:`~str`
value: str = marshaller.attrib(deserializer=str, serializer=str)
+ """The value of the field."""
- #: Whether the field should display inline. Defaults to :obj:`~False`.
- #:
- #: :type: :obj:`~bool`
is_inline: bool = marshaller.attrib(
raw_name="inline", deserializer=bool, serializer=bool, if_undefined=False, default=False
)
+ """Whether the field should display inline. Defaults to `False`."""
@marshaller.marshallable()
@@ -275,97 +221,74 @@ class EmbedField(bases.HikariEntity, marshaller.Deserializable, marshaller.Seria
class Embed(bases.HikariEntity, marshaller.Deserializable, marshaller.Serializable):
"""Represents an embed."""
- #: The title of the embed.
- #:
- #: :type: :obj:`~str`, optional
title: typing.Optional[str] = marshaller.attrib(deserializer=str, serializer=str, if_undefined=None, default=None)
+ """The title of the embed."""
- #: The description of the embed.
- #:
- #: :type: :obj:`~str`, optional
description: typing.Optional[str] = marshaller.attrib(
deserializer=str, serializer=str, if_undefined=None, default=None
)
+ """The description of the embed."""
- #: The URL of the embed.
- #:
- #: :type: :obj:`~str`, optional
url: typing.Optional[str] = marshaller.attrib(deserializer=str, serializer=str, if_undefined=None, default=None)
+ """The URL of the embed."""
- #: The timestamp of the embed.
- #:
- #: :type: :obj:`~datetime.datetime`, optional
timestamp: typing.Optional[datetime.datetime] = marshaller.attrib(
deserializer=conversions.parse_iso_8601_ts,
serializer=lambda timestamp: timestamp.replace(tzinfo=datetime.timezone.utc).isoformat(),
if_undefined=None,
default=None,
)
+ """The timestamp of the embed."""
color: typing.Optional[colors.Color] = marshaller.attrib(
deserializer=colors.Color, serializer=int, if_undefined=None, default=None
)
+ """The colour of this embed's sidebar."""
- #: The footer of the embed.
- #:
- #: :type: :obj:`~EmbedFooter`, optional
footer: typing.Optional[EmbedFooter] = marshaller.attrib(
deserializer=EmbedFooter.deserialize, serializer=EmbedFooter.serialize, if_undefined=None, default=None
)
+ """The footer of the embed."""
- #: The image of the embed.
- #:
- #: :type: :obj:`~EmbedImage`, optional
image: typing.Optional[EmbedImage] = marshaller.attrib(
deserializer=EmbedImage.deserialize, serializer=EmbedImage.serialize, if_undefined=None, default=None
)
+ """The image of the embed."""
- #: The thumbnail of the embed.
- #:
- #: :type: :obj:`~EmbedThumbnail`, optional
thumbnail: typing.Optional[EmbedThumbnail] = marshaller.attrib(
deserializer=EmbedThumbnail.deserialize, serializer=EmbedThumbnail.serialize, if_undefined=None, default=None
)
+ """The thumbnail of the embed."""
- #: The video of the embed.
- #:
- #: Note
- #: ----
- #: This field cannot be set by bots or webhooks while sending an embed and
- #: will be ignored during serialization.
- #:
- #:
- #: :type: :obj:`~EmbedVideo`, optional
video: typing.Optional[EmbedVideo] = marshaller.attrib(
deserializer=EmbedVideo.deserialize, transient=True, if_undefined=None, default=None,
)
+ """The video of the embed.
+
+ !!! note
+ This field cannot be set by bots or webhooks while sending an embed and
+ will be ignored during serialization.
+ """
- #: The provider of the embed.
- #:
- #: Note
- #: ----
- #: This field cannot be set by bots or webhooks while sending an embed and
- #: will be ignored during serialization.
- #:
- #:
- #: :type: :obj:`~EmbedProvider`, optional
provider: typing.Optional[EmbedProvider] = marshaller.attrib(
deserializer=EmbedProvider.deserialize, transient=True, if_undefined=None, default=None
)
+ """The provider of the embed.
+
+ !!! note
+ This field cannot be set by bots or webhooks while sending an embed and
+ will be ignored during serialization.
+ """
- #: The author of the embed.
- #:
- #: :type: :obj:`~EmbedAuthor`, optional
author: typing.Optional[EmbedAuthor] = marshaller.attrib(
deserializer=EmbedAuthor.deserialize, serializer=EmbedAuthor.serialize, if_undefined=None, default=None
)
+ """The author of the embed."""
- #: The fields of the embed.
- #:
- #: :type: :obj:`~typing.Sequence` [ :obj:`~EmbedField` ]
fields: typing.Sequence[EmbedField] = marshaller.attrib(
deserializer=lambda fields: [EmbedField.deserialize(f) for f in fields],
serializer=lambda fields: [f.serialize() for f in fields],
if_undefined=list,
factory=list,
)
+ """The fields of the embed."""
diff --git a/hikari/emojis.py b/hikari/emojis.py
index 2984c17396..962bda87d2 100644
--- a/hikari/emojis.py
+++ b/hikari/emojis.py
@@ -39,10 +39,8 @@ class Emoji(bases.HikariEntity, marshaller.Deserializable):
class UnicodeEmoji(Emoji):
"""Represents a unicode emoji."""
- #: The codepoints that form the emoji.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str)
+ """The codepoints that form the emoji."""
@property
def url_name(self) -> str:
@@ -60,20 +58,17 @@ def mention(self) -> str:
class UnknownEmoji(Emoji, bases.UniqueEntity):
"""Represents a unknown emoji."""
- #: The name of the emoji.
- #:
- #: :type: :obj:`~str`, optional
name: typing.Optional[str] = marshaller.attrib(deserializer=str, if_none=None)
+ """The name of the emoji."""
- #: Whether the emoji is animated.
- #:
- #: Will be :obj:`None` when received in Message Reaction Remove and Message
- #: Reaction Remove Emoji events.
- #:
- #: :type: :obj:`~bool`, optional
is_animated: typing.Optional[bool] = marshaller.attrib(
raw_name="animated", deserializer=bool, if_undefined=False, if_none=None, default=False
)
+ """Whether the emoji is animated.
+
+ Will be `None` when received in Message Reaction Remove and Message
+ Reaction Remove Emoji events.
+ """
@property
def url_name(self) -> str:
@@ -86,44 +81,38 @@ def url_name(self) -> str:
class GuildEmoji(UnknownEmoji):
"""Represents a guild emoji."""
- #: The whitelisted role IDs to use this emoji.
- #:
- #: :type: :obj:`~typing.Set` [ :obj:`~hikari.bases.Snowflake` ]
role_ids: typing.Set[bases.Snowflake] = marshaller.attrib(
raw_name="roles",
deserializer=lambda roles: {bases.Snowflake.deserialize(r) for r in roles},
if_undefined=set,
factory=set,
)
+ """The IDs of the roles that are whitelisted to use this emoji.
+
+ If this is empty than any user can use this emoji regardless of their roles.
+ """
- #: The user that created the emoji.
- #:
- #: Note
- #: ----
- #: This will be :obj:`~None` if you are missing the ``MANAGE_EMOJIS``
- #: permission in the server the emoji is from.
- #:
- #:
- #: :type: :obj:`~hikari.users.User`, optional
user: typing.Optional[users.User] = marshaller.attrib(
deserializer=users.User.deserialize, if_none=None, if_undefined=None, default=None
)
+ """The user that created the emoji.
+
+ !!! note
+ This will be `None` if you are missing the `MANAGE_EMOJIS`
+ permission in the server the emoji is from.
+ """
- #: Whether this emoji must be wrapped in colons.
- #:
- #: :type: :obj:`~bool`
is_colons_required: bool = marshaller.attrib(raw_name="require_colons", deserializer=bool)
+ """Whether this emoji must be wrapped in colons."""
- #: Whether the emoji is managed by an integration.
- #:
- #: :type: :obj:`~bool`
is_managed: bool = marshaller.attrib(raw_name="managed", deserializer=bool)
+ """Whether the emoji is managed by an integration."""
- #: Whether this emoji can currently be used, may be :obj:`False` due to
- #: a loss of Sever Boosts on the emoji's guild.
- #:
- #: :type: :obj:`~bool`
is_available: bool = marshaller.attrib(raw_name="available", deserializer=bool)
+ """Whether this emoji can currently be used.
+
+ May be `False` due to a loss of Sever Boosts on the emoji's guild.
+ """
@property
def mention(self) -> str:
diff --git a/hikari/errors.py b/hikari/errors.py
index 184479c0ee..bf9db63f17 100644
--- a/hikari/errors.py
+++ b/hikari/errors.py
@@ -22,6 +22,7 @@
"HikariWarning",
"NotFoundHTTPError",
"UnauthorizedHTTPError",
+ "ForbiddenHTTPError",
"BadRequestHTTPError",
"ClientHTTPError",
"ServerHTTPError",
@@ -49,9 +50,8 @@ class HikariError(RuntimeError):
Any exceptions should derive from this.
- Note
- ----
- You should never initialize this exception directly.
+ !!! note
+ You should never initialize this exception directly.
"""
__slots__ = ()
@@ -75,14 +75,12 @@ class GatewayError(HikariError):
Parameters
----------
- reason : :obj:`~str`
+ reason : st
A string explaining the issue.
"""
- #: A string to explain the issue.
- #:
- #: :type: :obj:`~str`
reason: str
+ """A string to explain the issue."""
def __init__(self, reason: str) -> None:
super().__init__()
@@ -97,7 +95,7 @@ class GatewayClientClosedError(GatewayError):
Parameters
----------
- reason : :obj:`~str`
+ reason : str
A string explaining the issue.
"""
@@ -110,7 +108,7 @@ class GatewayClientDisconnectedError(GatewayError):
Parameters
----------
- reason : :obj:`~str`
+ reason : str
A string explaining the issue.
"""
@@ -123,9 +121,9 @@ class GatewayServerClosedConnectionError(GatewayError):
Parameters
----------
- close_code : :obj:`~hikari.net.codes.GatewayCloseCode`, :obj:`~int`, optional
+ close_code : typing.Union [ hikari.net.codes.GatewayCloseCode, int ], optional
The close code provided by the server, if there was one.
- reason : :obj:`~str`, optional
+ reason : str, optional
A string explaining the issue.
"""
@@ -163,17 +161,16 @@ class GatewayInvalidSessionError(GatewayServerClosedConnectionError):
Parameters
----------
- can_resume : :obj:`~bool`
- :obj:`~True` if the connection will be able to RESUME next time it starts
- rather than re-IDENTIFYing, or :obj:`~False` if you need to IDENTIFY
+ can_resume : bool
+ `True` if the connection will be able to RESUME next time it starts
+ rather than re-IDENTIFYing, or `False` if you need to IDENTIFY
again instead.
"""
- #: :obj:`~True` if the next reconnection can be RESUMED. :obj:`~False` if it
- #: has to be coordinated by re-IDENFITYing.
- #:
- #: :type: :obj:`~bool`
can_resume: bool
+ """`True` if the next reconnection can be RESUMED,
+ `False` if it has to be coordinated by re-IDENFITYing.
+ """
def __init__(self, can_resume: bool) -> None:
self.can_resume = can_resume
@@ -220,14 +217,12 @@ class HTTPError(HikariError):
Parameters
----------
- reason : :obj:`~str`
+ reason : str
A meaningful explanation of the problem.
"""
- #: A meaningful explanation of the problem.
- #:
- #: :type: :obj:`~str`
reason: str
+ """A meaningful explanation of the problem."""
def __init__(self, reason: str) -> None:
super().__init__()
@@ -242,37 +237,27 @@ class CodedHTTPError(HTTPError):
Parameters
----------
- status : :obj:`~int` or :obj:`~hikari.net.codes.HTTPStatusCode`
+ status : int or hikari.net.codes.HTTPStatusCode
The HTTP status code that was returned by the server.
- route : :obj:`~hikari.net.routes.CompiledRoute`
+ route : hikari.net.routes.CompiledRoute
The HTTP route that was being invoked when this exception occurred.
- message : :obj:`~str`, optional
+ message : str, optional
An optional message if provided in the response payload.
- json_code : :obj:`~hikari.net.codes.JSONErrorCode`, :obj:`~int`, optional
+ json_code : hikari.net.codes.JSONErrorCode, int, optional
An optional error code the server provided us.
"""
- #: The HTTP status code that was returned by the server.
- #:
- #: :type: :obj:`~int` or :obj:`~hikari.net.codes.HTTPStatusCode`
status: typing.Union[int, codes.HTTPStatusCode]
+ """The HTTP status code that was returned by the server."""
- #: The HTTP route that was being invoked when this exception occurred.
- #:
- #: :type: :obj:`~hikari.net.routes.CompiledRoute`
route: routes.CompiledRoute
+ """The HTTP route that was being invoked when this exception occurred."""
- #: An optional contextual message the server provided us with in the
- #: response body.
- #
- #: :type: :obj:`~str`, optional
message: typing.Optional[str]
+ """An optional contextual message the server provided us with in the response body."""
- #: An optional contextual error code the server provided us with in the
- #: response body.
- #
- #: :type: :obj:`~hikari.net.codes.JSONErrorCode` or :obj:`~int`, optional
- json_code: typing.Optional[typing.Union[codes.JSONErrorCode, int]]
+ json_code: typing.Union[codes.JSONErrorCode, int, None]
+ """An optional contextual error code the server provided us with in the response body."""
def __init__(
self,
@@ -311,7 +296,7 @@ class ClientHTTPError(CodedHTTPError):
class BadRequestHTTPError(CodedHTTPError):
- """A specific case of :obj:`~CodedHTTPError`.
+ """A specific case of CodedHTTPError.
This can occur hat occurs when you send Discord information in an unexpected
format, miss required information out, or give bad values for stuff.
@@ -321,11 +306,11 @@ class BadRequestHTTPError(CodedHTTPError):
Parameters
----------
- route : :obj:`~hikari.net.routes.CompiledRoute`
+ route : hikari.net.routes.CompiledRoute
The HTTP route that was being invoked when this exception occurred.
- message : :obj:`~str`, optional
+ message : str, optional
An optional message if provided in the response payload.
- json_code : :obj:`~hikari.net.codes.JSONErrorCode`, :obj:`~int`, optional
+ json_code : hikari.net.codes.JSONErrorCode, int, optional
An optional error code the server provided us.
"""
@@ -339,7 +324,7 @@ def __init__(
class UnauthorizedHTTPError(ClientHTTPError):
- """A specific case of :obj:`~ClientHTTPError`.
+ """A specific case of ClientHTTPError.
This occurs when you have invalid authorization details to access
the given resource.
@@ -348,11 +333,11 @@ class UnauthorizedHTTPError(ClientHTTPError):
Parameters
----------
- route : :obj:`~hikari.net.routes.CompiledRoute`
+ route : hikari.net.routes.CompiledRoute
The HTTP route that was being invoked when this exception occurred.
- message : :obj:`~str`, optional
+ message : str, optional
An optional message if provided in the response payload.
- json_code : :obj:`~hikari.net.codes.JSONErrorCode`, :obj:`~int`, optional
+ json_code : hikari.net.codes.JSONErrorCode, int, optional
An optional error code the server provided us.
"""
@@ -366,7 +351,7 @@ def __init__(
class ForbiddenHTTPError(ClientHTTPError):
- """A specific case of :obj:`~ClientHTTPError`.
+ """A specific case of ClientHTTPError.
This occurs when you are missing permissions, or are using an endpoint that
your account is not allowed to see without being whitelisted.
@@ -375,11 +360,11 @@ class ForbiddenHTTPError(ClientHTTPError):
Parameters
----------
- route : :obj:`~hikari.net.routes.CompiledRoute`
+ route : hikari.net.routes.CompiledRoute
The HTTP route that was being invoked when this exception occurred.
- message : :obj:`~str`, optional
+ message : str, optional
An optional message if provided in the response payload.
- json_code : :obj:`~hikari.net.codes.JSONErrorCode`, :obj:`~int`, optional
+ json_code : hikari.net.codes.JSONErrorCode, int, optional
An optional error code the server provided us.
"""
@@ -393,7 +378,7 @@ def __init__(
class NotFoundHTTPError(ClientHTTPError):
- """A specific case of :obj:`~ClientHTTPError`.
+ """A specific case of ClientHTTPError.
This occurs when you try to refer to something that doesn't exist on Discord.
This might be referring to a user ID, channel ID, guild ID, etc that does
@@ -402,11 +387,11 @@ class NotFoundHTTPError(ClientHTTPError):
Parameters
----------
- route : :obj:`~hikari.net.routes.CompiledRoute`
+ route : hikari.net.routes.CompiledRoute
The HTTP route that was being invoked when this exception occurred.
- message : :obj:`~str`, optional
+ message : str, optional
An optional message if provided in the response payload.
- json_code : :obj:`~hikari.net.codes.JSONErrorCode`, :obj:`~int`, optional
+ json_code : hikari.net.codes.JSONErrorCode, int, optional
An optional error code the server provided us.
"""
diff --git a/hikari/events.py b/hikari/events.py
index 7ac38d4be2..8e27aa3a1f 100644
--- a/hikari/events.py
+++ b/hikari/events.py
@@ -29,6 +29,7 @@
"StoppedEvent",
"ReadyEvent",
"ResumedEvent",
+ "BaseChannelEvent",
"ChannelCreateEvent",
"ChannelUpdateEvent",
"ChannelDeleteEvent",
@@ -37,6 +38,7 @@
"GuildUpdateEvent",
"GuildLeaveEvent",
"GuildUnavailableEvent",
+ "BaseGuildBanEvent",
"GuildBanAddEvent",
"GuildBanRemoveEvent",
"GuildEmojisUpdateEvent",
@@ -108,12 +110,12 @@ def get_required_intents_for(event_type: typing.Type[HikariEvent]) -> typing.Col
Parameters
----------
- event_type : :obj:`~typing.Type` [ :obj:`~HikariEvent` ]
+ event_type : typing.Type [ HikariEvent ]
The event type to get required intents for.
Returns
-------
- :obj:`~typing.Collection` [ :obj:`~hikari.intents.Intent` ]
+ typing.Collection [ hikari.intents.Intent ]
Collection of acceptable subset combinations of intent needed to
be able to receive the given event type.
"""
@@ -127,10 +129,10 @@ def requires_intents(
Parameters
----------
- first : :obj:`~hikari.intents.Intent`
+ first : hikari.intents.Intent
First combination of intents that are acceptable in order to receive
the decorated event type.
- *rest : :obj:`~hikari.intents.Intent`
+ *rest : hikari.intents.Intent
Zero or more additional combinations of intents to require for this
event to be subscribed to.
@@ -148,20 +150,14 @@ def decorator(cls: typing.Type[_HikariEventT]) -> typing.Type[_HikariEventT]:
class ExceptionEvent(HikariEvent):
"""Descriptor for an exception thrown while processing an event."""
- #: The exception that was raised.
- #:
- #: :type: :obj:`~Exception`
exception: Exception
+ """The exception that was raised."""
- #: The event that was being invoked when the exception occurred.
- #:
- #: :type: :obj:`~HikariEvent`
event: HikariEvent
+ """The event that was being invoked when the exception occurred."""
- #: The event that was being invoked when the exception occurred.
- #:
- #: :type: coroutine function ( :obj:`~HikariEvent` ) -> :obj:`~None`
callback: typing.Callable[[HikariEvent], typing.Awaitable[None]]
+ """The event that was being invoked when the exception occurred."""
# Synthetic event, is not deserialized
@@ -192,30 +188,24 @@ class StoppedEvent(HikariEvent):
class ConnectedEvent(HikariEvent, marshaller.Deserializable):
"""Event invoked each time a shard connects."""
- #: The shard that connected.
- #:
- #: :type: :obj:`~hikari.clients.shard_clients.ShardClient`
shard: shards.ShardClient
+ """The shard that connected."""
@attr.s(slots=True, kw_only=True, auto_attribs=True)
class DisconnectedEvent(HikariEvent, marshaller.Deserializable):
"""Event invoked each time a shard disconnects."""
- #: The shard that disconnected.
- #:
- #: :type: :obj:`~hikari.clients.shard_clients.ShardClient`
shard: shards.ShardClient
+ """The shard that disconnected."""
@attr.s(slots=True, kw_only=True, auto_attribs=True)
class ResumedEvent(HikariEvent):
"""Represents a gateway Resume event."""
- #: The shard that reconnected.
- #:
- #: :type: :obj:`~hikari.clients.shard_clients.ShardClient`
shard: shards.ShardClient
+ """The shard that reconnected."""
@marshaller.marshallable()
@@ -226,36 +216,28 @@ class ReadyEvent(HikariEvent, marshaller.Deserializable):
This is received only when IDENTIFYing with the gateway.
"""
- #: The gateway version this is currently connected to.
- #:
- #: :type: :obj:`~int`
gateway_version: int = marshaller.attrib(raw_name="v", deserializer=int)
+ """The gateway version this is currently connected to."""
- #: The object of the current bot account this connection is for.
- #:
- #: :type: :obj:`~hikari.users.MyUser`
my_user: users.MyUser = marshaller.attrib(raw_name="user", deserializer=users.MyUser.deserialize)
+ """The object of the current bot account this connection is for."""
- #: A mapping of the guilds this bot is currently in. All guilds will start
- #: off "unavailable".
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~hikari.guilds.UnavailableGuild` ]
unavailable_guilds: typing.Mapping[bases.Snowflake, guilds.UnavailableGuild] = marshaller.attrib(
raw_name="guilds",
deserializer=lambda guilds_objs: {g.id: g for g in map(guilds.UnavailableGuild.deserialize, guilds_objs)},
)
+ """A mapping of the guilds this bot is currently in.
+
+ All guilds will start off "unavailable".
+ """
- #: The id of the current gateway session, used for reconnecting.
- #:
- #: :type: :obj:`~str`
session_id: str = marshaller.attrib(deserializer=str)
+ """The id of the current gateway session, used for reconnecting."""
- #: Information about the current shard, only provided when IDENTIFYing.
- #:
- #: :type: :obj:`~typing.Tuple` [ :obj:`~int`, :obj:`~int` ], optional
_shard_information: typing.Optional[typing.Tuple[int, int]] = marshaller.attrib(
raw_name="shard", deserializer=tuple, if_undefined=None, default=None
)
+ """Information about the current shard, only provided when IDENTIFYing."""
@property
def shard_id(self) -> typing.Optional[int]:
@@ -280,27 +262,20 @@ def shard_count(self) -> typing.Optional[int]:
class BaseChannelEvent(HikariEvent, bases.UniqueEntity, marshaller.Deserializable, abc.ABC):
"""A base object that Channel events will inherit from."""
- #: The channel's type.
- #:
- #: :type: :obj:`~hikari.channels.ChannelType`
type: channels.ChannelType = marshaller.attrib(deserializer=channels.ChannelType)
+ """The channel's type."""
- #: The ID of the guild this channel is in, will be :obj:`~None` for DMs.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild this channel is in, will be `None` for DMs."""
- #: The sorting position of this channel, will be relative to the
- #: :attr:`parent_id` if set.
- #:
- #: :type: :obj:`~int`, optional
position: typing.Optional[int] = marshaller.attrib(deserializer=int, if_undefined=None, default=None)
+ """The sorting position of this channel.
+
+ This will be relative to the `BaseChannelEvent.parent_id` if set.
+ """
- #: An mapping of the set permission overwrites for this channel, if applicable.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~hikari.channels.PermissionOverwrite` ], optional
permission_overwrites: typing.Optional[
typing.Mapping[bases.Snowflake, channels.PermissionOverwrite]
] = marshaller.attrib(
@@ -308,94 +283,72 @@ class BaseChannelEvent(HikariEvent, bases.UniqueEntity, marshaller.Deserializabl
if_undefined=None,
default=None,
)
+ """An mapping of the set permission overwrites for this channel, if applicable."""
- #: The name of this channel, if applicable.
- #:
- #: :type: :obj:`~str`, optional
name: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The name of this channel, if applicable."""
- #: The topic of this channel, if applicable and set.
- #:
- #: :type: :obj:`~str`, optional
topic: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, if_none=None, default=None)
+ """The topic of this channel, if applicable and set."""
- #: Whether this channel is nsfw, will be :obj:`~None` if not applicable.
- #:
- #: :type: :obj:`~bool`, optional
is_nsfw: typing.Optional[bool] = marshaller.attrib(
raw_name="nsfw", deserializer=bool, if_undefined=None, default=None
)
+ """Whether this channel is nsfw, will be `None` if not applicable."""
- #: The ID of the last message sent, if it's a text type channel.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
last_message_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_none=None, if_undefined=None, default=None
)
+ """The ID of the last message sent, if it's a text type channel."""
- #: The bitrate (in bits) of this channel, if it's a guild voice channel.
- #:
- #: :type: :obj:`~bool`, optional
bitrate: typing.Optional[int] = marshaller.attrib(deserializer=int, if_undefined=None, default=None)
+ """The bitrate (in bits) of this channel, if it's a guild voice channel."""
- #: The user limit for this channel if it's a guild voice channel.
- #:
- #: :type: :obj:`~bool`, optional
user_limit: typing.Optional[int] = marshaller.attrib(deserializer=int, if_undefined=None, default=None)
+ """The user limit for this channel if it's a guild voice channel."""
- #: The rate limit a user has to wait before sending another message in this
- #: channel, if it's a guild text like channel.
- #:
- #: :type: :obj:`~datetime.timedelta`, optional
rate_limit_per_user: typing.Optional[datetime.timedelta] = marshaller.attrib(
deserializer=lambda delta: datetime.timedelta(seconds=delta), if_undefined=None, default=None
)
+ """How long a user has to wait before sending another message in this channel.
+
+ This is only applicable to a guild text like channel.
+ """
- #: A mapping of this channel's recipient users, if it's a DM or group DM.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~hikari.users.User` ], optional
recipients: typing.Optional[typing.Mapping[bases.Snowflake, users.User]] = marshaller.attrib(
deserializer=lambda recipients: {user.id: user for user in map(users.User.deserialize, recipients)},
if_undefined=None,
default=None,
)
+ """A mapping of this channel's recipient users, if it's a DM or group DM."""
- #: The hash of this channel's icon, if it's a group DM channel and is set.
- #:
- #: :type: :obj:`~str`, optional
icon_hash: typing.Optional[str] = marshaller.attrib(
raw_name="icon", deserializer=str, if_undefined=None, if_none=None, default=None
)
+ """The hash of this channel's icon, if it's a group DM channel and is set."""
- #: The ID of this channel's creator, if it's a DM channel.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
owner_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of this channel's creator, if it's a DM channel."""
- #: The ID of the application that created the group DM, if it's a
- #: bot based group DM.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
application_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the application that created the group DM.
+
+ This is only applicable to bot based group DMs.
+ """
- #: The ID of this channels's parent category within guild, if set.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
parent_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, if_none=None, default=None
)
+ """The ID of this channels's parent category within guild, if set."""
- #: The datetime of when the last message was pinned in this channel,
- #: if set and applicable.
- #:
- #: :type: :obj:`~datetime.datetime`, optional
last_pin_timestamp: typing.Optional[datetime.datetime] = marshaller.attrib(
deserializer=conversions.parse_iso_8601_ts, if_undefined=None, default=None
)
+ """The datetime of when the last message was pinned in this channel."""
@requires_intents(intents.Intent.GUILDS)
@@ -433,26 +386,24 @@ class ChannelPinUpdateEvent(HikariEvent, marshaller.Deserializable):
when a pinned message is deleted.
"""
- #: The ID of the guild where this event happened.
- #: Will be :obj:`~None` if this happened in a DM channel.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild where this event happened.
+
+ Will be `None` if this happened in a DM channel.
+ """
- #: The ID of the channel where the message was pinned or unpinned.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel where the message was pinned or unpinned."""
- #: The datetime of when the most recent message was pinned in this channel.
- #: Will be :obj:`~None` if there are no messages pinned after this change.
- #:
- #: :type: :obj:`~datetime.datetime`, optional
last_pin_timestamp: typing.Optional[datetime.datetime] = marshaller.attrib(
deserializer=conversions.parse_iso_8601_ts, if_undefined=None, default=None
)
+ """The datetime of when the most recent message was pinned in this channel.
+
+ Will be `None` if there are no messages pinned after this change.
+ """
@requires_intents(intents.Intent.GUILDS)
@@ -479,9 +430,8 @@ class GuildUpdateEvent(HikariEvent, marshaller.Deserializable):
class GuildLeaveEvent(HikariEvent, bases.UniqueEntity, marshaller.Deserializable):
"""Fired when the current user leaves the guild or is kicked/banned from it.
- Notes
- -----
- This is fired based on Discord's Guild Delete gateway event.
+ !!! note
+ This is fired based on Discord's Guild Delete gateway event.
"""
@@ -491,9 +441,8 @@ class GuildLeaveEvent(HikariEvent, bases.UniqueEntity, marshaller.Deserializable
class GuildUnavailableEvent(HikariEvent, bases.UniqueEntity, marshaller.Deserializable):
"""Fired when a guild becomes temporarily unavailable due to an outage.
- Notes
- -----
- This is fired based on Discord's Guild Delete gateway event.
+ !!! note
+ This is fired based on Discord's Guild Delete gateway event.
"""
@@ -503,15 +452,11 @@ class GuildUnavailableEvent(HikariEvent, bases.UniqueEntity, marshaller.Deserial
class BaseGuildBanEvent(HikariEvent, marshaller.Deserializable, abc.ABC):
"""A base object that guild ban events will inherit from."""
- #: The ID of the guild this ban is in.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild this ban is in."""
- #: The object of the user this ban targets.
- #:
- #: :type: :obj:`~hikari.users.User`
user: users.User = marshaller.attrib(deserializer=users.User.deserialize)
+ """The object of the user this ban targets."""
@requires_intents(intents.Intent.GUILD_BANS)
@@ -534,17 +479,13 @@ class GuildBanRemoveEvent(BaseGuildBanEvent):
class GuildEmojisUpdateEvent(HikariEvent, marshaller.Deserializable):
"""Represents a Guild Emoji Update gateway event."""
- #: The ID of the guild this emoji was updated in.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild this emoji was updated in."""
- #: The updated mapping of emojis by their ID.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~hikari.emojis.GuildEmoji` ]
emojis: typing.Mapping[bases.Snowflake, _emojis.GuildEmoji] = marshaller.attrib(
deserializer=lambda ems: {emoji.id: emoji for emoji in map(_emojis.GuildEmoji.deserialize, ems)}
)
+ """The updated mapping of emojis by their ID."""
@requires_intents(intents.Intent.GUILD_INTEGRATIONS)
@@ -553,10 +494,8 @@ class GuildEmojisUpdateEvent(HikariEvent, marshaller.Deserializable):
class GuildIntegrationsUpdateEvent(HikariEvent, marshaller.Deserializable):
"""Used to represent Guild Integration Update gateway events."""
- #: The ID of the guild the integration was updated in.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild the integration was updated in."""
@requires_intents(intents.Intent.GUILD_MEMBERS)
@@ -565,10 +504,8 @@ class GuildIntegrationsUpdateEvent(HikariEvent, marshaller.Deserializable):
class GuildMemberAddEvent(HikariEvent, guilds.GuildMember):
"""Used to represent a Guild Member Add gateway event."""
- #: The ID of the guild where this member was added.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild where this member was added."""
@requires_intents(intents.Intent.GUILD_MEMBERS)
@@ -580,38 +517,33 @@ class GuildMemberUpdateEvent(HikariEvent, marshaller.Deserializable):
Sent when a guild member or their inner user object is updated.
"""
- #: The ID of the guild this member was updated in.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild this member was updated in."""
- #: A sequence of the IDs of the member's current roles.
- #:
- #: :type: :obj:`~typing.Sequence` [ :obj:`~hikari.bases.Snowflake` ]
role_ids: typing.Sequence[bases.Snowflake] = marshaller.attrib(
raw_name="roles", deserializer=lambda role_ids: [bases.Snowflake.deserialize(rid) for rid in role_ids],
)
+ """A sequence of the IDs of the member's current roles."""
- #: The object of the user who was updated.
- #:
- #: :type: :obj:`~hikari.users.User`
user: users.User = marshaller.attrib(deserializer=users.User.deserialize)
+ """The object of the user who was updated."""
- #: This member's nickname. When set to :obj:`~None`, this has been removed
- #: and when set to :obj:`~hikari.unset.UNSET` this hasn't been acted on.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~str`, :obj:`~hikari.unset.UNSET` ], optional
nickname: typing.Union[None, str, unset.Unset] = marshaller.attrib(
raw_name="nick", deserializer=str, if_none=None, if_undefined=unset.Unset, default=unset.UNSET
)
+ """This member's nickname.
+
+ When set to `None`, this has been removed and when set to
+ `hikari.unset.UNSET` this hasn't been acted on.
+ """
- #: The datetime of when this member started "boosting" this guild.
- #: Will be :obj:`~None` if they aren't boosting.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~datetime.datetime`, :obj:`~hikari.unset.UNSET` ], optional
premium_since: typing.Union[None, datetime.datetime, unset.Unset] = marshaller.attrib(
deserializer=conversions.parse_iso_8601_ts, if_none=None, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The datetime of when this member started "boosting" this guild.
+
+ Will be `None` if they aren't boosting.
+ """
@requires_intents(intents.Intent.GUILD_MEMBERS)
@@ -623,15 +555,11 @@ class GuildMemberRemoveEvent(HikariEvent, marshaller.Deserializable):
Sent when a member is kicked, banned or leaves a guild.
"""
- #: The ID of the guild this user was removed from.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild this user was removed from."""
- #: The object of the user who was removed from this guild.
- #:
- #: :type: :obj:`~hikari.users.User`
user: users.User = marshaller.attrib(deserializer=users.User.deserialize)
+ """The object of the user who was removed from this guild."""
@requires_intents(intents.Intent.GUILDS)
@@ -640,15 +568,11 @@ class GuildMemberRemoveEvent(HikariEvent, marshaller.Deserializable):
class GuildRoleCreateEvent(HikariEvent, marshaller.Deserializable):
"""Used to represent a Guild Role Create gateway event."""
- #: The ID of the guild where this role was created.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild where this role was created."""
- #: The object of the role that was created.
- #:
- #: :type: :obj:`~hikari.guilds.GuildRole`
role: guilds.GuildRole = marshaller.attrib(deserializer=guilds.GuildRole.deserialize)
+ """The object of the role that was created."""
@requires_intents(intents.Intent.GUILDS)
@@ -657,15 +581,11 @@ class GuildRoleCreateEvent(HikariEvent, marshaller.Deserializable):
class GuildRoleUpdateEvent(HikariEvent, marshaller.Deserializable):
"""Used to represent a Guild Role Create gateway event."""
- #: The ID of the guild where this role was updated.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild where this role was updated."""
- #: The updated role object.
- #:
- #: :type: :obj:`~hikari.guilds.GuildRole`
role: guilds.GuildRole = marshaller.attrib(deserializer=guilds.GuildRole.deserialize)
+ """The updated role object."""
@requires_intents(intents.Intent.GUILDS)
@@ -674,15 +594,11 @@ class GuildRoleUpdateEvent(HikariEvent, marshaller.Deserializable):
class GuildRoleDeleteEvent(HikariEvent, marshaller.Deserializable):
"""Represents a gateway Guild Role Delete Event."""
- #: The ID of the guild where this role is being deleted.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild where this role is being deleted."""
- #: The ID of the role being deleted.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
role_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the role being deleted."""
@requires_intents(intents.Intent.GUILD_INVITES)
@@ -691,73 +607,57 @@ class GuildRoleDeleteEvent(HikariEvent, marshaller.Deserializable):
class InviteCreateEvent(HikariEvent, marshaller.Deserializable):
"""Represents a gateway Invite Create event."""
- #: The ID of the channel this invite targets.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel this invite targets."""
- #: The code that identifies this invite
- #:
- #: :type: :obj:`~str`
code: str = marshaller.attrib(deserializer=str)
+ """The code that identifies this invite."""
- #: The datetime of when this invite was created.
- #:
- #: :type: :obj:`~datetime.datetime`
created_at: datetime.datetime = marshaller.attrib(deserializer=conversions.parse_iso_8601_ts)
+ """The datetime of when this invite was created."""
- #: The ID of the guild this invite was created in, if applicable.
- #: Will be :obj:`~None` for group DM invites.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild this invite was created in, if applicable.
+
+ Will be `None` for group DM invites.
+ """
- #: The object of the user who created this invite, if applicable.
- #:
- #: :type: :obj:`~hikari.users.User`, optional
inviter: typing.Optional[users.User] = marshaller.attrib(
deserializer=users.User.deserialize, if_undefined=None, default=None
)
+ """The object of the user who created this invite, if applicable."""
- #: The timedelta of how long this invite will be valid for.
- #: If set to :obj:`~None` then this is unlimited.
- #:
- #: :type: :obj:`~datetime.timedelta`, optional
max_age: typing.Optional[datetime.timedelta] = marshaller.attrib(
deserializer=lambda age: datetime.timedelta(seconds=age) if age > 0 else None,
)
+ """The timedelta of how long this invite will be valid for.
+
+ If set to `None` then this is unlimited.
+ """
- #: The limit for how many times this invite can be used before it expires.
- #: If set to ``0``, or infinity (``float("inf")``) then this is unlimited.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~int`, :obj:`~float` ( ``"inf"`` ) ]
max_uses: typing.Union[int, float] = marshaller.attrib(deserializer=lambda count: count or float("inf"))
+ """The limit for how many times this invite can be used before it expires.
+
+ If set to infinity (`float("inf")`) then this is unlimited.
+ """
- #: The object of the user who this invite targets, if set.
- #:
- #: :type: :obj:`~hikari.users.User`, optional
target_user: typing.Optional[users.User] = marshaller.attrib(
deserializer=users.User.deserialize, if_undefined=None, default=None
)
+ """The object of the user who this invite targets, if set."""
- #: The type of user target this invite is, if applicable.
- #:
- #: :type: :obj:`~hikari.invites.TargetUserType`, optional
target_user_type: typing.Optional[invites.TargetUserType] = marshaller.attrib(
deserializer=invites.TargetUserType, if_undefined=None, default=None
)
+ """The type of user target this invite is, if applicable."""
- #: Whether this invite grants temporary membership.
- #:
- #: :type: :obj:`~bool`
is_temporary: bool = marshaller.attrib(raw_name="temporary", deserializer=bool)
+ """Whether this invite grants temporary membership."""
- #: The amount of times this invite has been used.
- #:
- #: :type: :obj:`~int`
uses: int = marshaller.attrib(deserializer=int)
+ """The amount of times this invite has been used."""
@requires_intents(intents.Intent.GUILD_INVITES)
@@ -769,23 +669,19 @@ class InviteDeleteEvent(HikariEvent, marshaller.Deserializable):
Sent when an invite is deleted for a channel we can access.
"""
- #: The ID of the channel this ID was attached to
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel this ID was attached to."""
- #: The code of this invite.
- #:
- #: :type: :obj:`~str`
code: str = marshaller.attrib(deserializer=str)
+ """The code of this invite."""
- #: The ID of the guild this invite was deleted in.
- #: This will be :obj:`~None` if this invite belonged to a DM channel.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild this invite was deleted in.
+
+ This will be `None` if this invite belonged to a DM channel.
+ """
@requires_intents(intents.Intent.GUILD_MESSAGES, intents.Intent.DIRECT_MESSAGES)
@@ -802,189 +698,146 @@ class MessageCreateEvent(HikariEvent, messages.Message):
class MessageUpdateEvent(HikariEvent, bases.UniqueEntity, marshaller.Deserializable):
"""Represents Message Update gateway events.
- Note
- ----
- All fields on this model except :attr:`channel_id` and :obj:`~`HikariEvent.id`` may be
- set to :obj:`~hikari.unset.UNSET` (a singleton defined in
- ``hikari.bases``) if we have not received information about their
- state from Discord alongside field nullability.
+ !!! note
+ All fields on this model except `MessageUpdateEvent.channel_id` and
+ `MessageUpdateEvent.id` may be set to `hikari.unset.UNSET` (a singleton)
+ we have not received information about their state from Discord
+ alongside field nullability.
"""
- #: The ID of the channel that the message was sent in.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel that the message was sent in."""
- #: The ID of the guild that the message was sent in.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.bases.Snowflake`, :obj:`~hikari.unset.UNSET` ]
guild_id: typing.Union[bases.Snowflake, unset.Unset] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The ID of the guild that the message was sent in."""
- #: The author of this message.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.unset.UNSET` ]
author: typing.Union[users.User, unset.Unset] = marshaller.attrib(
deserializer=users.User.deserialize, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The author of this message."""
- #: The member properties for the message's author.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildMember`, :obj:`~hikari.unset.UNSET` ]
member: typing.Union[guilds.GuildMember, unset.Unset] = marshaller.attrib(
deserializer=guilds.GuildMember.deserialize, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The member properties for the message's author."""
- #: The content of the message.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~str`, :obj:`~hikari.unset.UNSET` ]
content: typing.Union[str, unset.Unset] = marshaller.attrib(
deserializer=str, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The content of the message."""
- #: The timestamp that the message was sent at.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~datetime.datetime`, :obj:`~hikari.unset.UNSET` ]
timestamp: typing.Union[datetime.datetime, unset.Unset] = marshaller.attrib(
deserializer=conversions.parse_iso_8601_ts, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The timestamp that the message was sent at."""
- #: The timestamp that the message was last edited at, or :obj:`~None` if
- #: it wasn't ever edited.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~datetime.datetime`, :obj:`~hikari.unset.UNSET` ], optional
edited_timestamp: typing.Union[datetime.datetime, unset.Unset, None] = marshaller.attrib(
deserializer=conversions.parse_iso_8601_ts, if_none=None, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The timestamp that the message was last edited at.
+
+ Will be `None` if the message wasn't ever edited.
+ """
- #: Whether the message is a TTS message.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~bool`, :obj:`~hikari.unset.UNSET` ]
is_tts: typing.Union[bool, unset.Unset] = marshaller.attrib(
raw_name="tts", deserializer=bool, if_undefined=unset.Unset, default=unset.UNSET
)
+ """Whether the message is a TTS message."""
- #: Whether the message mentions ``@everyone`` or ``@here``.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~bool`, :obj:`~hikari.unset.UNSET` ]
is_mentioning_everyone: typing.Union[bool, unset.Unset] = marshaller.attrib(
raw_name="mention_everyone", deserializer=bool, if_undefined=unset.Unset, default=unset.UNSET
)
+ """Whether the message mentions `@everyone` or `@here`."""
- #: The users the message mentions.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~typing.Set` [ :obj:`~hikari.bases.Snowflake` ], :obj:`~hikari.unset.UNSET` ]
user_mentions: typing.Union[typing.Set[bases.Snowflake], unset.Unset] = marshaller.attrib(
raw_name="mentions",
deserializer=lambda user_mentions: {bases.Snowflake.deserialize(u["id"]) for u in user_mentions},
if_undefined=unset.Unset,
default=unset.UNSET,
)
+ """The users the message mentions."""
- #: The roles the message mentions.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~typing.Set` [ :obj:`~hikari.bases.Snowflake` ], :obj:`~hikari.unset.UNSET` ]
role_mentions: typing.Union[typing.Set[bases.Snowflake], unset.Unset] = marshaller.attrib(
raw_name="mention_roles",
deserializer=lambda role_mentions: {bases.Snowflake.deserialize(r) for r in role_mentions},
if_undefined=unset.Unset,
default=unset.UNSET,
)
+ """The roles the message mentions."""
- #: The channels the message mentions.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~typing.Set` [ :obj:`~hikari.bases.Snowflake` ], :obj:`~hikari.unset.UNSET` ]
channel_mentions: typing.Union[typing.Set[bases.Snowflake], unset.Unset] = marshaller.attrib(
raw_name="mention_channels",
deserializer=lambda channel_mentions: {bases.Snowflake.deserialize(c["id"]) for c in channel_mentions},
if_undefined=unset.Unset,
default=unset.UNSET,
)
+ """The channels the message mentions."""
- #: The message attachments.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~typing.Sequence` [ :obj:`~hikari.messages.Attachment` ], :obj:`~hikari.unset.UNSET` ]
attachments: typing.Union[typing.Sequence[messages.Attachment], unset.Unset] = marshaller.attrib(
deserializer=lambda attachments: [messages.Attachment.deserialize(a) for a in attachments],
if_undefined=unset.Unset,
default=unset.UNSET,
)
+ """The message attachments."""
- #: The message's embeds.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~typing.Sequence` [ :obj:`~hikari.embeds.Embed` ], :obj:`~hikari.unset.UNSET` ]
embeds: typing.Union[typing.Sequence[_embeds.Embed], unset.Unset] = marshaller.attrib(
deserializer=lambda embed_objs: [_embeds.Embed.deserialize(e) for e in embed_objs],
if_undefined=unset.Unset,
default=unset.UNSET,
)
+ """The message's embeds."""
- #: The message's reactions.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~typing.Sequence` [ :obj:`~hikari.messages.Reaction` ], :obj:`~hikari.unset.UNSET` ]
reactions: typing.Union[typing.Sequence[messages.Reaction], unset.Unset] = marshaller.attrib(
deserializer=lambda reactions: [messages.Reaction.deserialize(r) for r in reactions],
if_undefined=unset.Unset,
default=unset.UNSET,
)
+ """The message's reactions."""
- #: Whether the message is pinned.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~bool`, :obj:`~hikari.unset.UNSET` ]
is_pinned: typing.Union[bool, unset.Unset] = marshaller.attrib(
raw_name="pinned", deserializer=bool, if_undefined=unset.Unset, default=unset.UNSET
)
+ """Whether the message is pinned."""
- #: If the message was generated by a webhook, the webhook's id.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.bases.Snowflake`, :obj:`~hikari.unset.UNSET` ]
webhook_id: typing.Union[bases.Snowflake, unset.Unset] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=unset.Unset, default=unset.UNSET
)
+ """If the message was generated by a webhook, the webhook's ID."""
- #: The message's type.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.messages.MessageType`, :obj:`~hikari.unset.UNSET` ]
type: typing.Union[messages.MessageType, unset.Unset] = marshaller.attrib(
deserializer=messages.MessageType, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The message's type."""
- #: The message's activity.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.messages.MessageActivity`, :obj:`~hikari.unset.UNSET` ]
activity: typing.Union[messages.MessageActivity, unset.Unset] = marshaller.attrib(
deserializer=messages.MessageActivity.deserialize, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The message's activity."""
- #: The message's application.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.oauth2.Application`, :obj:`~hikari.unset.UNSET` ]
application: typing.Optional[applications.Application] = marshaller.attrib(
deserializer=applications.Application.deserialize, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The message's application."""
- #: The message's crossposted reference data.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.messages.MessageCrosspost`, :obj:`~hikari.unset.UNSET` ]
message_reference: typing.Union[messages.MessageCrosspost, unset.Unset] = marshaller.attrib(
deserializer=messages.MessageCrosspost.deserialize, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The message's cross-posted reference data."""
- #: The message's flags.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.messages.MessageFlag`, :obj:`~hikari.unset.UNSET` ]
flags: typing.Union[messages.MessageFlag, unset.Unset] = marshaller.attrib(
deserializer=messages.MessageFlag, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The message's flags."""
- #: The message nonce. This is a string used for validating
- #: a message was sent.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.messages.MessageFlag`, :obj:`~hikari.unset.UNSET` ]
nonce: typing.Union[str, unset.Unset] = marshaller.attrib(
deserializer=str, if_undefined=unset.Unset, default=unset.UNSET
)
+ """The message nonce.
+
+ This is a string used for validating a message was sent.
+ """
@requires_intents(intents.Intent.GUILD_MESSAGES, intents.Intent.DIRECT_MESSAGES)
@@ -996,22 +849,19 @@ class MessageDeleteEvent(HikariEvent, marshaller.Deserializable):
Sent when a message is deleted in a channel we have access to.
"""
- #: The ID of the channel where this message was deleted.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel where this message was deleted."""
- #: The ID of the guild where this message was deleted.
- #: Will be :obj:`~None` if this message was deleted in a DM channel.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
- #: The ID of the message that was deleted.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
+ """The ID of the guild where this message was deleted.
+
+ This will be `None` if this message was deleted in a DM channel.
+ """
+
message_id: bases.Snowflake = marshaller.attrib(raw_name="id", deserializer=bases.Snowflake.deserialize)
+ """The ID of the message that was deleted."""
@requires_intents(intents.Intent.GUILD_MESSAGES)
@@ -1023,25 +873,21 @@ class MessageDeleteBulkEvent(HikariEvent, marshaller.Deserializable):
Sent when multiple messages are deleted in a channel at once.
"""
- #: The ID of the channel these messages have been deleted in.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel these messages have been deleted in."""
- #: The ID of the channel these messages have been deleted in.
- #: Will be :obj:`~None` if these messages were bulk deleted in a DM channel.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_none=None
)
+ """The ID of the channel these messages have been deleted in.
+
+ This will be `None` if these messages were bulk deleted in a DM channel.
+ """
- #: A collection of the IDs of the messages that were deleted.
- #:
- #: :type: :obj:`~typing.Set` [ :obj:`~hikari.bases.Snowflake` ]
message_ids: typing.Set[bases.Snowflake] = marshaller.attrib(
raw_name="ids", deserializer=lambda msgs: {bases.Snowflake.deserialize(m) for m in msgs}
)
+ """A collection of the IDs of the messages that were deleted."""
@requires_intents(intents.Intent.GUILD_MESSAGE_REACTIONS, intents.Intent.DIRECT_MESSAGE_REACTIONS)
@@ -1050,43 +896,35 @@ class MessageDeleteBulkEvent(HikariEvent, marshaller.Deserializable):
class MessageReactionAddEvent(HikariEvent, marshaller.Deserializable):
"""Used to represent Message Reaction Add gateway events."""
- #: The ID of the user adding the reaction.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
user_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the user adding the reaction."""
- #: The ID of the channel where this reaction is being added.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel where this reaction is being added."""
- #: The ID of the message this reaction is being added to.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
message_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the message this reaction is being added to."""
- #: The ID of the guild where this reaction is being added, unless this is
- #: happening in a DM channel.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild where this reaction is being added.
+
+ This will be `None` if this is happening in a DM channel.
+ """
- #: The member object of the user who's adding this reaction, if this is
- #: occurring in a guild.
- #:
- #: :type: :obj:`~hikari.guilds.GuildMember`, optional
member: typing.Optional[guilds.GuildMember] = marshaller.attrib(
deserializer=guilds.GuildMember.deserialize, if_undefined=None, default=None
)
+ """The member object of the user who's adding this reaction.
+
+ This will be `None` if this is happening in a DM channel.
+ """
- #: The object of the emoji being added.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.emojis.UnknownEmoji`, :obj:`~hikari.emojis.UnicodeEmoji` ]
emoji: typing.Union[_emojis.UnknownEmoji, _emojis.UnicodeEmoji] = marshaller.attrib(
deserializer=_emojis.deserialize_reaction_emoji,
)
+ """The object of the emoji being added."""
@requires_intents(intents.Intent.GUILD_MESSAGE_REACTIONS, intents.Intent.DIRECT_MESSAGE_REACTIONS)
@@ -1095,35 +933,27 @@ class MessageReactionAddEvent(HikariEvent, marshaller.Deserializable):
class MessageReactionRemoveEvent(HikariEvent, marshaller.Deserializable):
"""Used to represent Message Reaction Remove gateway events."""
- #: The ID of the user who is removing their reaction.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
user_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the user who is removing their reaction."""
- #: The ID of the channel where this reaction is being removed.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel where this reaction is being removed."""
- #: The ID of the message this reaction is being removed from.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
message_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the message this reaction is being removed from."""
- #: The ID of the guild where this reaction is being removed, unless this is
- #: happening in a DM channel.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild where this reaction is being removed
+
+ This will be `None` if this event is happening in a DM channel.
+ """
- #: The object of the emoji being removed.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.emojis.UnknownEmoji`, :obj:`~hikari.emojis.UnicodeEmoji` ]
emoji: typing.Union[_emojis.UnicodeEmoji, _emojis.UnknownEmoji] = marshaller.attrib(
deserializer=_emojis.deserialize_reaction_emoji,
)
+ """The object of the emoji being removed."""
@requires_intents(intents.Intent.GUILD_MESSAGE_REACTIONS, intents.Intent.DIRECT_MESSAGE_REACTIONS)
@@ -1135,22 +965,16 @@ class MessageReactionRemoveAllEvent(HikariEvent, marshaller.Deserializable):
Sent when all the reactions are removed from a message, regardless of emoji.
"""
- #: The ID of the channel where the targeted message is.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel where the targeted message is."""
- #: The ID of the message all reactions are being removed from.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
message_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the message all reactions are being removed from."""
- #: The ID of the guild where the targeted message is, if applicable.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild where the targeted message is, if applicable."""
@requires_intents(intents.Intent.GUILD_MESSAGE_REACTIONS, intents.Intent.DIRECT_MESSAGE_REACTIONS)
@@ -1162,29 +986,21 @@ class MessageReactionRemoveEmojiEvent(HikariEvent, marshaller.Deserializable):
Sent when all the reactions for a single emoji are removed from a message.
"""
- #: The ID of the channel where the targeted message is.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel where the targeted message is."""
- #: The ID of the guild where the targeted message is, if applicable.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild where the targeted message is, if applicable."""
- #: The ID of the message the reactions are being removed from.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
message_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the message the reactions are being removed from."""
- #: The object of the emoji that's being removed.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.emojis.UnknownEmoji`, :obj:`~hikari.emojis.UnicodeEmoji` ]
emoji: typing.Union[_emojis.UnicodeEmoji, _emojis.UnknownEmoji] = marshaller.attrib(
deserializer=_emojis.deserialize_reaction_emoji,
)
+ """The object of the emoji that's being removed."""
@requires_intents(intents.Intent.GUILD_PRESENCES)
@@ -1206,38 +1022,32 @@ class TypingStartEvent(HikariEvent, marshaller.Deserializable):
Received when a user or bot starts "typing" in a channel.
"""
- #: The ID of the channel this typing event is occurring in.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel this typing event is occurring in."""
- #: The ID of the guild this typing event is occurring in.
- #: Will be :obj:`~None` if this event is happening in a DM channel.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild this typing event is occurring in.
+
+ Will be `None` if this event is happening in a DM channel.
+ """
- #: The ID of the user who triggered this typing event.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
user_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the user who triggered this typing event."""
- #: The datetime of when this typing event started.
- #:
- #: :type: :obj:`~datetime.datetime`
timestamp: datetime.datetime = marshaller.attrib(
deserializer=lambda date: datetime.datetime.fromtimestamp(date, datetime.timezone.utc)
)
+ """The datetime of when this typing event started."""
- #: The member object of the user who triggered this typing event,
- #: if this was triggered in a guild.
- #:
- #: :type: :obj:`~hikari.guilds.GuildMember`, optional
member: typing.Optional[guilds.GuildMember] = marshaller.attrib(
deserializer=guilds.GuildMember.deserialize, if_undefined=None, default=None
)
+ """The member object of the user who triggered this typing event.
+
+ Will be `None` if this was triggered in a DM.
+ """
@marshaller.marshallable()
@@ -1268,20 +1078,14 @@ class VoiceServerUpdateEvent(HikariEvent, marshaller.Deserializable):
falls over to a new server.
"""
- #: The voice connection's token
- #:
- #: :type: :obj:`~str`
token: str = marshaller.attrib(deserializer=str)
+ """The voice connection's string token."""
- #: The ID of the guild this voice server update is for
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild this voice server update is for."""
- #: The uri for this voice server host.
- #:
- #: :type: :obj:`~str`
endpoint: str = marshaller.attrib(deserializer=str)
+ """The uri for this voice server host."""
@requires_intents(intents.Intent.GUILD_WEBHOOKS)
@@ -1293,12 +1097,8 @@ class WebhookUpdateEvent(HikariEvent, marshaller.Deserializable):
Sent when a webhook is updated, created or deleted in a guild.
"""
- #: The ID of the guild this webhook is being updated in.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild this webhook is being updated in."""
- #: The ID of the channel this webhook is being updated in.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel this webhook is being updated in."""
diff --git a/hikari/gateway_entities.py b/hikari/gateway_entities.py
index 950b455f8c..ab40340e0f 100644
--- a/hikari/gateway_entities.py
+++ b/hikari/gateway_entities.py
@@ -17,7 +17,7 @@
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
"""Entities directly related to creating and managing gateway shards."""
-__all__ = ["GatewayBot", "Activity"]
+__all__ = ["Activity", "GatewayBot", "SessionStartLimit"]
import datetime
import typing
@@ -34,23 +34,19 @@
class SessionStartLimit(bases.HikariEntity, marshaller.Deserializable):
"""Used to represent information about the current session start limits."""
- #: The total number of session starts the current bot is allowed.
- #:
- #: :type: :obj:`~int`
total: int = marshaller.attrib(deserializer=int)
+ """The total number of session starts the current bot is allowed."""
- #: The remaining number of session starts this bot has.
- #:
- #: :type: :obj:`~int`
remaining: int = marshaller.attrib(deserializer=int)
+ """The remaining number of session starts this bot has."""
- #: The timedelta of when :attr:`remaining` will reset back to :attr:`total`
- #: for the current bot.
- #:
- #: :type: :obj:`~datetime.timedelta`
reset_after: datetime.timedelta = marshaller.attrib(
deserializer=lambda after: datetime.timedelta(milliseconds=after),
)
+ """When `SessionStartLimit.remaining` will reset for the current bot.
+
+ After it resets it will be set to `SessionStartLimit.total`.
+ """
@marshaller.marshallable()
@@ -58,20 +54,14 @@ class SessionStartLimit(bases.HikariEntity, marshaller.Deserializable):
class GatewayBot(bases.HikariEntity, marshaller.Deserializable):
"""Used to represent gateway information for the connected bot."""
- #: The WSS URL that can be used for connecting to the gateway.
- #:
- #: :type: :obj:`~str`
url: str = marshaller.attrib(deserializer=str)
+ """The WSS URL that can be used for connecting to the gateway."""
- #: The recommended number of shards to use when connecting to the gateway.
- #:
- #: :type: :obj:`~int`
shard_count: int = marshaller.attrib(raw_name="shards", deserializer=int)
+ """The recommended number of shards to use when connecting to the gateway."""
- #: Information about the bot's current session start limit.
- #:
- #: :type: :obj:`~SessionStartLimit`
session_start_limit: SessionStartLimit = marshaller.attrib(deserializer=SessionStartLimit.deserialize)
+ """Information about the bot's current session start limit."""
@marshaller.marshallable()
@@ -82,24 +72,18 @@ class Activity(marshaller.Deserializable, marshaller.Serializable):
This will show the activity as the bot's presence.
"""
- #: The activity name.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str, serializer=str)
+ """The activity name."""
- #: The activity URL. Only valid for ``STREAMING`` activities.
- #:
- #: :type: :obj:`~str`, optional
url: typing.Optional[str] = marshaller.attrib(
deserializer=str, serializer=str, if_none=None, if_undefined=None, default=None
)
+ """The activity URL. Only valid for `STREAMING` activities."""
- #: The activity type.
- #:
- #: :type: :obj:`~hikari.guilds.ActivityType`
type: guilds.ActivityType = marshaller.attrib(
deserializer=guilds.ActivityType,
serializer=int,
if_undefined=lambda: guilds.ActivityType.PLAYING,
default=guilds.ActivityType.PLAYING,
)
+ """The activity type."""
diff --git a/hikari/guilds.py b/hikari/guilds.py
index 15599a3c68..671f9311a3 100644
--- a/hikari/guilds.py
+++ b/hikari/guilds.py
@@ -16,14 +16,17 @@
#
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
-"""Components and entities that are used to describe guilds on Discord.
-
-.. inheritance-diagram::
- hikari.guilds
-"""
+"""Components and entities that are used to describe guilds on Discord."""
__all__ = [
+ "ActivityAssets",
"ActivityFlag",
+ "ActivitySecret",
+ "ActivityTimestamps",
"ActivityType",
+ "ActivityParty",
+ "ClientStatus",
+ "Guild",
+ "GuildEmbed",
"GuildRole",
"GuildFeature",
"GuildSystemChannelFlag",
@@ -32,15 +35,20 @@
"GuildMFALevel",
"GuildVerificationLevel",
"GuildPremiumTier",
- "Guild",
+ "GuildPreview",
"GuildMember",
"GuildMemberPresence",
"GuildIntegration",
"GuildMemberBan",
+ "IntegrationAccount",
+ "IntegrationExpireBehaviour",
"PartialGuild",
"PartialGuildIntegration",
"PartialGuildRole",
+ "PresenceActivity",
"PresenceStatus",
+ "PresenceUser",
+ "UnavailableGuild",
]
import datetime
@@ -65,135 +73,137 @@
class GuildExplicitContentFilterLevel(enum.IntEnum):
"""Represents the explicit content filter setting for a guild."""
- #: No explicit content filter.
DISABLED = 0
+ """No explicit content filter."""
- #: Filter posts from anyone without a role.
MEMBERS_WITHOUT_ROLES = 1
+ """Filter posts from anyone without a role."""
- #: Filter all posts.
ALL_MEMBERS = 2
+ """Filter all posts."""
@enum.unique
class GuildFeature(str, enum.Enum):
"""Features that a guild can provide."""
- #: Guild has access to set an animated guild icon.
ANIMATED_ICON = "ANIMATED_ICON"
+ """Guild has access to set an animated guild icon."""
- #: Guild has access to set a guild banner image.
BANNER = "BANNER"
+ """Guild has access to set a guild banner image."""
- #: Guild has access to use commerce features (i.e. create store channels).
COMMERCE = "COMMERCE"
+ """Guild has access to use commerce features (i.e. create store channels)."""
- #: Guild is able to be discovered in the directory.
DISCOVERABLE = "DISCOVERABLE"
+ """Guild is able to be discovered in the directory."""
- #: Guild is able to be featured in the directory.
FEATURABLE = "FEATURABLE"
+ """Guild is able to be featured in the directory."""
- #: Guild has access to set an invite splash background.
INVITE_SPLASH = "INVITE_SPLASH"
+ """Guild has access to set an invite splash background."""
- #: More emojis can be hosted in this guild than normal.
MORE_EMOJI = "MORE_EMOJI"
+ """More emojis can be hosted in this guild than normal."""
- #: Guild has access to create news channels.
NEWS = "NEWS"
+ """Guild has access to create news channels."""
- #: People can view channels in this guild without joining.
LURKABLE = "LURKABLE"
+ """People can view channels in this guild without joining."""
- #: Guild is partnered.
PARTNERED = "PARTNERED"
+ """Guild is partnered."""
- #: Guild is public, go figure.
PUBLIC = "PUBLIC"
+ """Guild is public, go figure."""
- #: Guild cannot be public. Who would have guessed?
PUBLIC_DISABLED = "PUBLIC_DISABLED"
+ """Guild cannot be public. Who would have guessed?"""
- #: Guild has access to set a vanity URL.
VANITY_URL = "VANITY_URL"
+ """Guild has access to set a vanity URL."""
- #: Guild is verified.
VERIFIED = "VERIFIED"
+ """Guild is verified."""
- #: Guild has access to set 384kbps bitrate in voice (previously
- #: VIP voice servers).
VIP_REGIONS = "VIP_REGIONS"
+ """Guild has access to set 384kbps bitrate in voice.
+
+ Previously gave access to VIP voice servers.
+ """
@enum.unique
class GuildMessageNotificationsLevel(enum.IntEnum):
"""Represents the default notification level for new messages in a guild."""
- #: Notify users when any message is sent.
ALL_MESSAGES = 0
+ """Notify users when any message is sent."""
- #: Only notify users when they are @mentioned.
ONLY_MENTIONS = 1
+ """Only notify users when they are @mentioned."""
@enum.unique
class GuildMFALevel(enum.IntEnum):
"""Represents the multi-factor authorization requirement for a guild."""
- #: No MFA requirement.
NONE = 0
+ """No MFA requirement."""
- #: MFA requirement.
ELEVATED = 1
+ """MFA requirement."""
@enum.unique
class GuildPremiumTier(enum.IntEnum):
"""Tier for Discord Nitro boosting in a guild."""
- #: No Nitro boosts.
NONE = 0
+ """No Nitro boost level."""
- #: Level 1 Nitro boost.
TIER_1 = 1
+ """Level 1 Nitro boost."""
- #: Level 2 Nitro boost.
TIER_2 = 2
+ """Level 2 Nitro boost."""
- #: Level 3 Nitro boost.
TIER_3 = 3
+ """Level 3 Nitro boost."""
@enum.unique
class GuildSystemChannelFlag(enum.IntFlag):
"""Defines which features are suppressed in the system channel."""
- #: Display a message about new users joining.
SUPPRESS_USER_JOIN = 1 << 0
+ """Display a message about new users joining."""
- #: Display a message when the guild is Nitro boosted.
SUPPRESS_PREMIUM_SUBSCRIPTION = 1 << 1
+ """Display a message when the guild is Nitro boosted."""
@enum.unique
class GuildVerificationLevel(enum.IntEnum):
"""Represents the level of verification of a guild."""
- #: Unrestricted
NONE = 0
+ """Unrestricted"""
- #: Must have a verified email on their account.
LOW = 1
+ """Must have a verified email on their account."""
- #: Must have been registered on Discord for more than 5 minutes.
MEDIUM = 2
+ """Must have been registered on Discord for more than 5 minutes."""
- #: (╯°□°）╯︵ ┻━┻ - must be a member of the guild for longer than 10 minutes.
HIGH = 3
+ """(╯°□°）╯︵ ┻━┻ - must be a member of the guild for longer than 10 minutes."""
- #: ┻━┻ミヽ(ಠ益ಠ)ﾉ彡┻━┻ - must have a verified phone number.
VERY_HIGH = 4
+ """┻━┻ミヽ(ಠ益ಠ)ﾉ彡┻━┻ - must have a verified phone number."""
@marshaller.marshallable()
@@ -201,17 +211,13 @@ class GuildVerificationLevel(enum.IntEnum):
class GuildEmbed(bases.HikariEntity, marshaller.Deserializable):
"""Represents a guild embed."""
- #: The ID of the channel the invite for this embed targets, if enabled
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
channel_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, serializer=str, if_none=None
)
+ """The ID of the channel the invite for this embed targets, if enabled."""
- #: Whether this embed is enabled.
- #:
- #: :type: :obj:`~bool`
is_enabled: bool = marshaller.attrib(raw_name="enabled", deserializer=bool, serializer=bool)
+ """Whether this embed is enabled."""
@marshaller.marshallable()
@@ -219,50 +225,40 @@ class GuildEmbed(bases.HikariEntity, marshaller.Deserializable):
class GuildMember(bases.HikariEntity, marshaller.Deserializable):
"""Used to represent a guild bound member."""
- #: This member's user object, will be :obj:`~None` when attached to Message
- #: Create and Update gateway events.
- #:
- #: :type: :obj:`~hikari.users.User`, optional
user: typing.Optional[users.User] = marshaller.attrib(
deserializer=users.User.deserialize, if_undefined=None, default=None
)
+ """This member's user object.
+
+ This will be `None` when attached to Message Create and Update gateway events.
+ """
- #: This member's nickname, if set.
- #:
- #: :type: :obj:`~str`, optional
nickname: typing.Optional[str] = marshaller.attrib(
raw_name="nick", deserializer=str, if_none=None, if_undefined=None, default=None
)
+ """This member's nickname, if set."""
- #: A sequence of the IDs of the member's current roles.
- #:
- #: :type: :obj:`~typing.Sequence` [ :obj:`~hikari.bases.Snowflake` ]
role_ids: typing.Sequence[bases.Snowflake] = marshaller.attrib(
raw_name="roles", deserializer=lambda role_ids: [bases.Snowflake.deserialize(rid) for rid in role_ids],
)
+ """A sequence of the IDs of the member's current roles."""
- #: The datetime of when this member joined the guild they belong to.
- #:
- #: :type: :obj:`~datetime.datetime`
joined_at: datetime.datetime = marshaller.attrib(deserializer=conversions.parse_iso_8601_ts)
+ """The datetime of when this member joined the guild they belong to."""
- #: The datetime of when this member started "boosting" this guild.
- #: Will be :obj:`~None` if they aren't boosting.
- #:
- #: :type: :obj:`~datetime.datetime`, optional
premium_since: typing.Optional[datetime.datetime] = marshaller.attrib(
deserializer=conversions.parse_iso_8601_ts, if_none=None, if_undefined=None, default=None
)
+ """The datetime of when this member started "boosting" this guild.
+
+ This will be `None` if they aren't boosting.
+ """
- #: Whether this member is deafened by this guild in it's voice channels.
- #:
- #: :type: :obj:`~bool`
is_deaf: bool = marshaller.attrib(raw_name="deaf", deserializer=bool)
+ """Whether this member is deafened by this guild in it's voice channels."""
- #: Whether this member is muted by this guild in it's voice channels.
- #:
- #: :type: :obj:`~bool`
is_mute: bool = marshaller.attrib(raw_name="mute", deserializer=bool)
+ """Whether this member is muted by this guild in it's voice channels."""
@marshaller.marshallable()
@@ -270,10 +266,8 @@ class GuildMember(bases.HikariEntity, marshaller.Deserializable):
class PartialGuildRole(bases.UniqueEntity, marshaller.Deserializable):
"""Represents a partial guild bound Role object."""
- #: The role's name.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str, serializer=str)
+ """The role's name."""
@marshaller.marshallable()
@@ -281,71 +275,60 @@ class PartialGuildRole(bases.UniqueEntity, marshaller.Deserializable):
class GuildRole(PartialGuildRole, marshaller.Serializable):
"""Represents a guild bound Role object."""
- #: The colour of this role, will be applied to a member's name in chat
- #: if it's their top coloured role.
- #:
- #: :type: :obj:`~hikari.colors.Color`
color: colors.Color = marshaller.attrib(deserializer=colors.Color, serializer=int, default=colors.Color(0))
+ """The colour of this role.
+
+ This will be applied to a member's name in chat if it's their top coloured role."""
- #: Whether this role is hoisting the members it's attached to in the member
- #: list, members will be hoisted under their highest role where
- #: :attr:`is_hoisted` is true.
- #:
- #: :type: :obj:`~bool`
is_hoisted: bool = marshaller.attrib(raw_name="hoist", deserializer=bool, serializer=bool, default=False)
+ """Whether this role is hoisting the members it's attached to in the member list.
+
+ members will be hoisted under their highest role where this is set to `True`."""
- #: The position of this role in the role hierarchy.
- #:
- #: :type: :obj:`~int`
position: int = marshaller.attrib(deserializer=int, serializer=int, default=None)
+ """The position of this role in the role hierarchy."""
- #: The guild wide permissions this role gives to the members it's attached
- #: to, may be overridden by channel overwrites.
- #:
- #: :type: :obj:`~hikari.permissions.Permission`
permissions: _permissions.Permission = marshaller.attrib(
deserializer=_permissions.Permission, serializer=int, default=_permissions.Permission(0)
)
+ """The guild wide permissions this role gives to the members it's attached to,
+
+ This may be overridden by channel overwrites.
+ """
- #: Whether this role is managed by an integration.
- #:
- #: :type: :obj:`~bool`
is_managed: bool = marshaller.attrib(raw_name="managed", deserializer=bool, transient=True, default=None)
+ """Whether this role is managed by an integration."""
- #: Whether this role can be mentioned by all, regardless of the
- #: ``MENTION_EVERYONE`` permission.
- #:
- #: :type: :obj:`~bool`
is_mentionable: bool = marshaller.attrib(raw_name="mentionable", deserializer=bool, serializer=bool, default=False)
+ """Whether this role can be mentioned by all regardless of permissions."""
@enum.unique
class ActivityType(enum.IntEnum):
"""The activity type."""
- #: Shows up as ``Playing ``
PLAYING = 0
+ """Shows up as `Playing `"""
- #: Shows up as ``Streaming ``.
- #:
- #: Warning
- #: -------
- #: Corresponding presences must be associated with VALID Twitch or YouTube
- #: stream URLS!
STREAMING = 1
- #: Shows up as ``Listening to ``.
LISTENING = 2
+ """Shows up as `Listening to `."""
- #: Shows up as ``Watching ``. Note that this is not officially
- #: documented, so will be likely removed in the near future.
WATCHING = 3
+ """Shows up as `Watching `.
+
+ !!! note
+ this is not officially documented, so will be likely removed in the near
+ future.
+ """
- #: A custom status.
- #:
- #: To set an emoji with the status, place a unicode emoji or Discord emoji
- #: (``:smiley:``) as the first part of the status activity name.
CUSTOM = 4
+ """A custom status.
+
+ To set an emoji with the status, place a unicode emoji or Discord emoji
+ (`:smiley:`) as the first part of the status activity name.
+ """
@marshaller.marshallable()
@@ -353,19 +336,15 @@ class ActivityType(enum.IntEnum):
class ActivityTimestamps(bases.HikariEntity, marshaller.Deserializable):
"""The datetimes for the start and/or end of an activity session."""
- #: When this activity's session was started, if applicable.
- #:
- #: :type: :obj:`~datetime.datetime`, optional
start: typing.Optional[datetime.datetime] = marshaller.attrib(
deserializer=conversions.unix_epoch_to_datetime, if_undefined=None, default=None
)
+ """When this activity's session was started, if applicable."""
- #: When this activity's session will end, if applicable.
- #:
- #: :type: :obj:`~datetime.datetime`, optional
end: typing.Optional[datetime.datetime] = marshaller.attrib(
deserializer=conversions.unix_epoch_to_datetime, if_undefined=None, default=None
)
+ """When this activity's session will end, if applicable."""
@marshaller.marshallable()
@@ -373,17 +352,13 @@ class ActivityTimestamps(bases.HikariEntity, marshaller.Deserializable):
class ActivityParty(bases.HikariEntity, marshaller.Deserializable):
"""Used to represent activity groups of users."""
- #: The string id of this party instance, if set.
- #:
- #: :type: :obj:`~str`, optional
id: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The string id of this party instance, if set."""
- #: The size metadata of this party, if applicable.
- #:
- #: :type: :obj:`~typing.Tuple` [ :obj:`~int`, :obj:`~int` ], optional
_size_information: typing.Optional[typing.Tuple[int, int]] = marshaller.attrib(
raw_name="size", deserializer=tuple, if_undefined=None, default=None
)
+ """The size metadata of this party, if applicable."""
# Ignore docstring not starting in an imperative mood
@property
@@ -402,25 +377,17 @@ def max_size(self) -> typing.Optional[int]:
class ActivityAssets(bases.HikariEntity, marshaller.Deserializable):
"""Used to represent possible assets for an activity."""
- #: The ID of the asset's large image, if set.
- #:
- #: :type: :obj:`~str`, optional
large_image: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The ID of the asset's large image, if set."""
- #: The text that'll appear when hovering over the large image, if set.
- #:
- #: :type: :obj:`~str`, optional
large_text: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The text that'll appear when hovering over the large image, if set."""
- #: The ID of the asset's small image, if set.
- #:
- #: :type: :obj:`~str`, optional
small_image: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The ID of the asset's small image, if set."""
- #: The text that'll appear when hovering over the small image, if set.
- #:
- #: :type: :obj:`~str`, optional
small_text: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The text that'll appear when hovering over the small image, if set."""
@marshaller.marshallable()
@@ -428,20 +395,14 @@ class ActivityAssets(bases.HikariEntity, marshaller.Deserializable):
class ActivitySecret(bases.HikariEntity, marshaller.Deserializable):
"""The secrets used for interacting with an activity party."""
- #: The secret used for joining a party, if applicable.
- #:
- #: :type: :obj:`~str`, optional
join: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The secret used for joining a party, if applicable."""
- #: The secret used for spectating a party, if applicable.
- #:
- #: :type: :obj:`~str`, optional
spectate: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The secret used for spectating a party, if applicable."""
- #: The secret used for joining a party, if applicable.
- #:
- #: :type: :obj:`~str`, optional
match: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The secret used for joining a party, if applicable."""
@enum.unique
@@ -451,23 +412,23 @@ class ActivityFlag(enum.IntFlag):
This can be more than one using bitwise-combinations.
"""
- #: Instance
INSTANCE = 1 << 0
+ """Instance"""
- #: Join
JOIN = 1 << 1
+ """Join"""
- #: Spectate
SPECTATE = 1 << 2
+ """Spectate"""
- #: Join Request
JOIN_REQUEST = 1 << 3
+ """Join Request"""
- #: Sync
SYNC = 1 << 4
+ """Sync"""
- #: Play
PLAY = 1 << 5
+ """Play"""
@marshaller.marshallable()
@@ -475,109 +436,82 @@ class ActivityFlag(enum.IntFlag):
class PresenceActivity(bases.HikariEntity, marshaller.Deserializable):
"""Represents an activity that will be attached to a member's presence."""
- #: The activity's name.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str)
+ """The activity's name."""
- #: The activity's type.
- #:
- #: :type: :obj:`~ActivityType`
type: ActivityType = marshaller.attrib(deserializer=ActivityType)
+ """The activity's type."""
- #: The URL for a ``STREAM`` type activity, if applicable.
- #:
- #: :type: :obj:`~str`, optional
url: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, if_none=None, default=None)
+ """The URL for a `STREAM` type activity, if applicable."""
- #: When this activity was added to the user's session.
- #:
- #: :type: :obj:`~datetime.datetime`
created_at: datetime.datetime = marshaller.attrib(deserializer=conversions.unix_epoch_to_datetime)
+ """When this activity was added to the user's session."""
- #: The timestamps for when this activity's current state will start and
- #: end, if applicable.
- #:
- #: :type: :obj:`~ActivityTimestamps`, optional
timestamps: typing.Optional[ActivityTimestamps] = marshaller.attrib(
deserializer=ActivityTimestamps.deserialize, if_undefined=None, default=None
)
+ """The timestamps for when this activity's current state will start and
+ end, if applicable.
+ """
- #: The ID of the application this activity is for, if applicable.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
application_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the application this activity is for, if applicable."""
- #: The text that describes what the activity's target is doing, if set.
- #:
- #: :type: :obj:`~str`, optional
details: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, if_none=None, default=None)
+ """The text that describes what the activity's target is doing, if set."""
- #: The current status of this activity's target, if set.
- #:
- #: :type: :obj:`~str`, optional
state: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, if_none=None, default=None)
+ """The current status of this activity's target, if set."""
- #: The emoji of this activity, if it is a custom status and set.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.emojis.UnicodeEmoji`, :obj:`~hikari.emojis.UnknownEmoji` ], optional
emoji: typing.Union[None, _emojis.UnicodeEmoji, _emojis.UnknownEmoji] = marshaller.attrib(
deserializer=_emojis.deserialize_reaction_emoji, if_undefined=None, default=None
)
+ """The emoji of this activity, if it is a custom status and set."""
- #: Information about the party associated with this activity, if set.
- #:
- #: :type: :obj:`~ActivityParty`, optional
party: typing.Optional[ActivityParty] = marshaller.attrib(
deserializer=ActivityParty.deserialize, if_undefined=None, default=None
)
+ """Information about the party associated with this activity, if set."""
- #: Images and their hover over text for the activity.
- #:
- #: :type: :obj:`~ActivityAssets`, optional
assets: typing.Optional[ActivityAssets] = marshaller.attrib(
deserializer=ActivityAssets.deserialize, if_undefined=None, default=None
)
+ """Images and their hover over text for the activity."""
- #: Secrets for Rich Presence joining and spectating.
- #:
- #: :type: :obj:`~ActivitySecret`, optional
secrets: typing.Optional[ActivitySecret] = marshaller.attrib(
deserializer=ActivitySecret.deserialize, if_undefined=None, default=None
)
+ """Secrets for Rich Presence joining and spectating."""
- #: Whether this activity is an instanced game session.
- #:
- #: :type: :obj:`~bool`, optional
is_instance: typing.Optional[bool] = marshaller.attrib(
raw_name="instance", deserializer=bool, if_undefined=None, default=None
)
+ """Whether this activity is an instanced game session."""
- #: Flags that describe what the activity includes.
- #:
- #: :type: :obj:`~ActivityFlag`
flags: ActivityFlag = marshaller.attrib(deserializer=ActivityFlag, if_undefined=None, default=None)
+ """Flags that describe what the activity includes."""
class PresenceStatus(str, enum.Enum):
"""The status of a member."""
- #: Online/green.
ONLINE = "online"
+ """Online/green."""
- #: Idle/yellow.
IDLE = "idle"
+ """Idle/yellow."""
- #: Do not disturb/red.
DND = "dnd"
+ """Do not disturb/red."""
- #: An alias for :attr:`DND`
DO_NOT_DISTURB = DND
+ """An alias for `PresenceStatus.DND`"""
- #: Offline or invisible/grey.
OFFLINE = "offline"
+ """Offline or invisible/grey."""
@marshaller.marshallable()
@@ -585,26 +519,20 @@ class PresenceStatus(str, enum.Enum):
class ClientStatus(bases.HikariEntity, marshaller.Deserializable):
"""The client statuses for this member."""
- #: The status of the target user's desktop session.
- #:
- #: :type: :obj:`~PresenceStatus`
desktop: PresenceStatus = marshaller.attrib(
deserializer=PresenceStatus, if_undefined=lambda: PresenceStatus.OFFLINE, default=PresenceStatus.OFFLINE
)
+ """The status of the target user's desktop session."""
- #: The status of the target user's mobile session.
- #:
- #: :type: :obj:`~PresenceStatus`
mobile: PresenceStatus = marshaller.attrib(
deserializer=PresenceStatus, if_undefined=lambda: PresenceStatus.OFFLINE, default=PresenceStatus.OFFLINE
)
+ """The status of the target user's mobile session."""
- #: The status of the target user's web session.
- #:
- #: :type: :obj:`~PresenceStatus`
web: PresenceStatus = marshaller.attrib(
deserializer=PresenceStatus, if_undefined=lambda: PresenceStatus.OFFLINE, default=PresenceStatus.OFFLINE
)
+ """The status of the target user's web session."""
@marshaller.marshallable()
@@ -612,62 +540,48 @@ class ClientStatus(bases.HikariEntity, marshaller.Deserializable):
class PresenceUser(users.User):
"""A user representation specifically used for presence updates.
- Warnings
- --------
- Every attribute except ``id`` may be received as :obj:`~hikari.unset.UNSET`
- unless it is specifically being modified for this update.
+ !!! warning
+ Every attribute except `PresenceUser.id` may be as `hikari.unset.UNSET`
+ unless it is specifically being modified for this update.
"""
- #: This user's discriminator.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~str`, :obj:`~hikari.unset.UNSET` ]
discriminator: typing.Union[str, unset.Unset] = marshaller.attrib(
deserializer=str, if_undefined=unset.Unset, default=unset.UNSET
)
+ """This user's discriminator."""
- #: This user's username.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~str`, :obj:`~hikari.unset.UNSET` ]
username: typing.Union[str, unset.Unset] = marshaller.attrib(
deserializer=str, if_undefined=unset.Unset, default=unset.UNSET
)
+ """This user's username."""
- #: This user's avatar hash, if set.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~str`, :obj:`~hikari.unset.UNSET` ], optional
avatar_hash: typing.Union[None, str, unset.Unset] = marshaller.attrib(
raw_name="avatar", deserializer=str, if_none=None, if_undefined=unset.Unset, default=unset.UNSET
)
+ """This user's avatar hash, if set."""
- #: Whether this user is a bot account.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~bool`, :obj:`~hikari.unset.UNSET` ]
is_bot: typing.Union[bool, unset.Unset] = marshaller.attrib(
raw_name="bot", deserializer=bool, if_undefined=unset.Unset, default=unset.UNSET
)
+ """Whether this user is a bot account."""
- #: Whether this user is a system account.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~bool`, :obj:`~hikari.unset.UNSET` ]
is_system: typing.Union[bool, unset.Unset] = marshaller.attrib(
raw_name="system", deserializer=bool, if_undefined=unset.Unset, default=unset.UNSET
)
+ """Whether this user is a system account."""
- #: The public flags for this user.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.users.UserFlag`, :obj:`~hikari.unset.UNSET` ]
flags: typing.Union[users.UserFlag, unset.Unset] = marshaller.attrib(
raw_name="public_flags", deserializer=users.UserFlag, if_undefined=unset.Unset
)
+ """The public flags for this user."""
@property
def avatar_url(self) -> typing.Union[str, unset.Unset]:
"""URL for this user's avatar if the relevant info is available.
- Note
- ----
- This will be :obj:`~hikari.unset.UNSET` if both :attr:`avatar_hash`
- and :attr:`discriminator` are :obj:`~hikari.unset.UNSET`.
+ !!! note
+ This will be `hikari.unset.UNSET` if both `PresenceUser.avatar_hash`
+ and `PresenceUser.discriminator` are `hikari.unset.UNSET`.
"""
return self.format_avatar_url()
@@ -676,27 +590,26 @@ def format_avatar_url(self, fmt: typing.Optional[str] = None, size: int = 4096)
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png`` or ``gif``.
- Supports ``png``, ``jpeg``, ``jpg``, ``webp`` and ``gif`` (when
- animated). Will be ignored for default avatars which can only be
- ``png``.
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``.
+ fmt : str
+ The format to use for this URL, defaults to `png` or `gif`.
+ Supports `png`, `jpeg`, `jpg`, `webp` and `gif` (when animated).
+ Will be ignored for default avatars which can only be `png`.
+ size : int
+ The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Will be ignored for default avatars.
Returns
-------
- :obj:`~typing.Union` [ :obj:`~str`, :obj:`~hikari.unset.UNSET` ]
+ typing.Union [ str, hikari.unset.UNSET ]
The string URL of the user's custom avatar if
- either :attr:`avatar_hash` is set or their default avatar if
- :attr:`discriminator` is set, else :obj:`~hikari.unset.UNSET`.
+ either `PresenceUser.avatar_hash` is set or their default avatar if
+ `PresenceUser.discriminator` is set, else `hikari.unset.UNSET`.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if self.discriminator is unset.UNSET and self.avatar_hash is unset.UNSET:
return unset.UNSET
@@ -706,10 +619,9 @@ def format_avatar_url(self, fmt: typing.Optional[str] = None, size: int = 4096)
def default_avatar(self) -> typing.Union[int, unset.Unset]:
"""Integer representation of this user's default avatar.
- Note
- ----
- This will be :obj:`~hikari.unset.UNSET` if :attr:`discriminator` is
- :obj:`~hikari.unset.UNSET`.
+ !!! note
+ This will be `hikari.unset.UNSET` if `PresenceUser.discriminator` is
+ `hikari.unset.UNSET`.
"""
if self.discriminator is not unset.UNSET:
return int(self.discriminator) % 5
@@ -721,69 +633,59 @@ def default_avatar(self) -> typing.Union[int, unset.Unset]:
class GuildMemberPresence(bases.HikariEntity, marshaller.Deserializable):
"""Used to represent a guild member's presence."""
- #: The object of the user who this presence is for, only `id` is guaranteed
- #: for this partial object, with other attributes only being included when
- #: when they are being changed in an event.
- #:
- #: :type: :obj:`~PresenceUser`
user: PresenceUser = marshaller.attrib(deserializer=PresenceUser.deserialize)
+ """The object of the user who this presence is for.
+
+ !!! info
+ Only `PresenceUser.id` is guaranteed for this partial object,
+ with other attributes only being included when when they are being
+ changed in an event.
+ """
- #: A sequence of the ids of the user's current roles in the guild this
- #: presence belongs to.
- #:
- #: :type: :obj:`~typing.Sequence` [ :obj:`~hikari.bases.Snowflake` ]
role_ids: typing.Sequence[bases.Snowflake] = marshaller.attrib(
raw_name="roles", deserializer=lambda roles: [bases.Snowflake.deserialize(rid) for rid in roles],
)
+ """The ids of the user's current roles in the guild this presence belongs to."""
- #: The ID of the guild this presence belongs to.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
guild_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the guild this presence belongs to."""
- #: This user's current status being displayed by the client.
- #:
- #: :type: :obj:`~PresenceStatus`
visible_status: PresenceStatus = marshaller.attrib(raw_name="status", deserializer=PresenceStatus)
+ """This user's current status being displayed by the client."""
- #: An array of the user's activities, with the top one will being
- #: prioritised by the client.
- #:
- #: :type: :obj:`~typing.Sequence` [ :obj:`~PresenceActivity` ]
activities: typing.Sequence[PresenceActivity] = marshaller.attrib(
deserializer=lambda activities: [PresenceActivity.deserialize(a) for a in activities]
)
+ """An array of the user's activities, with the top one will being
+ prioritised by the client.
+ """
- #: An object of the target user's client statuses.
- #:
- #: :type: :obj:`~ClientStatus`
client_status: ClientStatus = marshaller.attrib(deserializer=ClientStatus.deserialize)
+ """An object of the target user's client statuses."""
- #: The datetime of when this member started "boosting" this guild.
- #: Will be :obj:`~None` if they aren't boosting.
- #:
- #: :type: :obj:`~datetime.datetime`, optional
premium_since: typing.Optional[datetime.datetime] = marshaller.attrib(
deserializer=conversions.parse_iso_8601_ts, if_undefined=None, if_none=None, default=None
)
+ """The datetime of when this member started "boosting" this guild.
+
+ This will be `None` if they aren't boosting.
+ """
- #: This member's nickname, if set.
- #:
- #: :type: :obj:`~str`, optional
nick: typing.Optional[str] = marshaller.attrib(
raw_name="nick", deserializer=str, if_undefined=None, if_none=None, default=None
)
+ """This member's nickname, if set."""
@enum.unique
class IntegrationExpireBehaviour(enum.IntEnum):
"""Behavior for expiring integration subscribers."""
- #: Remove the role.
REMOVE_ROLE = 0
+ """Remove the role."""
- #: Kick the subscriber.
KICK = 1
+ """Kick the subscriber."""
@marshaller.marshallable()
@@ -791,15 +693,11 @@ class IntegrationExpireBehaviour(enum.IntEnum):
class IntegrationAccount(bases.HikariEntity, marshaller.Deserializable):
"""An account that's linked to an integration."""
- #: The string ID of this (likely) third party account.
- #:
- #: :type: :obj:`~str`
id: str = marshaller.attrib(deserializer=str)
+ """The string ID of this (likely) third party account."""
- #: The name of this account.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str)
+ """The name of this account."""
@marshaller.marshallable()
@@ -807,20 +705,14 @@ class IntegrationAccount(bases.HikariEntity, marshaller.Deserializable):
class PartialGuildIntegration(bases.UniqueEntity, marshaller.Deserializable):
"""A partial representation of an integration, found in audit logs."""
- #: The name of this integration.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str)
+ """The name of this integration."""
- #: The type of this integration.
- #:
- #: :type: :obj:`~str`
type: str = marshaller.attrib(deserializer=str)
+ """The type of this integration."""
- #: The account connected to this integration.
- #:
- #: :type: :obj:`~IntegrationAccount`
account: IntegrationAccount = marshaller.attrib(deserializer=IntegrationAccount.deserialize)
+ """The account connected to this integration."""
@marshaller.marshallable()
@@ -828,54 +720,41 @@ class PartialGuildIntegration(bases.UniqueEntity, marshaller.Deserializable):
class GuildIntegration(bases.UniqueEntity, marshaller.Deserializable):
"""Represents a guild integration object."""
- #: Whether this integration is enabled.
- #:
- #: :type: :obj:`~bool`
is_enabled: bool = marshaller.attrib(raw_name="enabled", deserializer=bool)
+ """Whether this integration is enabled."""
- #: Whether this integration is syncing subscribers/emojis.
- #:
- #: :type: :obj:`~bool`
is_syncing: bool = marshaller.attrib(raw_name="syncing", deserializer=bool)
+ """Whether this integration is syncing subscribers/emojis."""
- #: The ID of the managed role used for this integration's subscribers.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
role_id: typing.Optional[bases.Snowflake] = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the managed role used for this integration's subscribers."""
- #: Whether users under this integration are allowed to use it's custom
- #: emojis.
- #:
- #: :type: :obj:`~bool`, optional
is_emojis_enabled: typing.Optional[bool] = marshaller.attrib(
raw_name="enable_emoticons", deserializer=bool, if_undefined=None, default=None
)
+ """Whether users under this integration are allowed to use it's custom emojis."""
- #: How members should be treated after their connected subscription expires
- #: This won't be enacted until after :attr:`expire_grace_period` passes.
- #:
- #: :type: :obj:`~IntegrationExpireBehaviour`
expire_behavior: IntegrationExpireBehaviour = marshaller.attrib(deserializer=IntegrationExpireBehaviour)
+ """How members should be treated after their connected subscription expires.
+
+ This won't be enacted until after `GuildIntegration.expire_grace_period`
+ passes.
+ """
- #: The time delta for how many days users with expired subscriptions are
- #: given until :attr:`expire_behavior` is enacted out on them
- #:
- #: :type: :obj:`~datetime.timedelta`
expire_grace_period: datetime.timedelta = marshaller.attrib(
deserializer=lambda delta: datetime.timedelta(days=delta),
)
+ """How many days users with expired subscriptions are given until
+ `GuildIntegration.expire_behavior` is enacted out on them
+ """
- #: The user this integration belongs to.
- #:
- #: :type: :obj:`~hikari.users.User`
user: users.User = marshaller.attrib(deserializer=users.User.deserialize)
+ """The user this integration belongs to."""
- #: The datetime of when this integration's subscribers were last synced.
- #:
- #: :type: :obj:`~datetime.datetime`
last_synced_at: datetime.datetime = marshaller.attrib(
raw_name="synced_at", deserializer=conversions.parse_iso_8601_ts, if_none=None
)
+ """The datetime of when this integration's subscribers were last synced."""
@marshaller.marshallable()
@@ -883,15 +762,11 @@ class GuildIntegration(bases.UniqueEntity, marshaller.Deserializable):
class GuildMemberBan(bases.HikariEntity, marshaller.Deserializable):
"""Used to represent guild bans."""
- #: The reason for this ban, will be :obj:`~None` if no reason was given.
- #:
- #: :type: :obj:`~str`, optional
reason: str = marshaller.attrib(deserializer=str, if_none=None)
+ """The reason for this ban, will be `None` if no reason was given."""
- #: The object of the user this ban targets.
- #:
- #: :type: :obj:`~hikari.users.User`
user: users.User = marshaller.attrib(deserializer=users.User.deserialize)
+ """The object of the user this ban targets."""
@marshaller.marshallable()
@@ -906,9 +781,9 @@ class UnavailableGuild(bases.UniqueEntity, marshaller.Deserializable):
# Ignore docstring not starting in an imperative mood
@property
def is_unavailable(self) -> bool: # noqa: D401
- """:obj:`~True` if this guild is unavailable, else :obj:`~False`.
+ """`True` if this guild is unavailable, else `False`.
- This value is always :obj:`~True`, and is only provided for consistency.
+ This value is always `True`, and is only provided for consistency.
"""
return True
@@ -918,45 +793,39 @@ def is_unavailable(self) -> bool: # noqa: D401
class PartialGuild(bases.UniqueEntity, marshaller.Deserializable):
"""Base object for any partial guild objects."""
- #: The name of the guild.
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str)
+ """The name of the guild."""
- #: The hash for the guild icon, if there is one.
- #:
- #: :type: :obj:`~str`, optional
icon_hash: typing.Optional[str] = marshaller.attrib(raw_name="icon", deserializer=str, if_none=None)
+ """The hash for the guild icon, if there is one."""
- #: A set of the features in this guild.
- #:
- #: :type: :obj:`~typing.Set` [ :obj:`~GuildFeature` ]
features: typing.Set[GuildFeature] = marshaller.attrib(
deserializer=lambda features: {conversions.try_cast(f, GuildFeature, f) for f in features},
)
+ """A set of the features in this guild."""
def format_icon_url(self, fmt: typing.Optional[str] = None, size: int = 4096) -> typing.Optional[str]:
"""Generate the URL for this guild's custom icon, if set.
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png`` or ``gif``.
- Supports ``png``, ``jpeg``, `jpg`, ``webp`` and ``gif`` (when
+ fmt : str
+ The format to use for this URL, defaults to `png` or `gif`.
+ Supports `png`, `jpeg`, `jpg`, `webp` and `gif` (when
animated).
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``.
+ size : int
+ The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
- :obj:`~str`, optional
+ str, optional
The string URL.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if self.icon_hash:
if fmt is None and self.icon_hash.startswith("a_"):
@@ -975,66 +844,51 @@ def icon_url(self) -> typing.Optional[str]:
@marshaller.marshallable()
@attr.s(slots=True, kw_only=True)
class GuildPreview(PartialGuild):
- """A preview of a guild with the :obj:`~GuildFeature.PUBLIC` feature."""
+ """A preview of a guild with the `GuildFeature.PUBLIC` feature."""
- #: The hash of the splash for the guild, if there is one.
- #:
- #: :type: :obj:`~str`, optional
splash_hash: typing.Optional[str] = marshaller.attrib(raw_name="splash", deserializer=str, if_none=None)
+ """The hash of the splash for the guild, if there is one."""
- #: The hash of the discovery splash for the guild, if there is one.
- #:
- #: :type: :obj:`~str`, optional
discovery_splash_hash: typing.Optional[str] = marshaller.attrib(
raw_name="discovery_splash", deserializer=str, if_none=None
)
+ """The hash of the discovery splash for the guild, if there is one."""
- #: The emojis that this guild provides, represented as a mapping of ID to
- #: emoji object.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~hikari.emojis.GuildEmoji` ]
emojis: typing.Mapping[bases.Snowflake, _emojis.GuildEmoji] = marshaller.attrib(
deserializer=lambda emojis: {e.id: e for e in map(_emojis.GuildEmoji.deserialize, emojis)},
)
+ """The mapping of IDs to the emojis this guild provides."""
+
+ approximate_presence_count: int = marshaller.attrib(deserializer=int)
+ """The approximate amount of presences in guild."""
+
+ approximate_member_count: int = marshaller.attrib(deserializer=int)
+ """The approximate amount of members in this guild."""
- #: The approximate amount of presences in this invite's guild, only present
- #: when ``with_counts`` is passed as ``True`` to the GET Invites endpoint.
- #:
- #: :type: :obj:`~int`, optional
- approximate_presence_count: typing.Optional[int] = marshaller.attrib(deserializer=int)
-
- #: The approximate amount of members in this invite's guild, only present
- #: when ``with_counts`` is passed as ``True`` to the GET Invites endpoint.
- #:
- #: :type: :obj:`~int`, optional
- approximate_member_count: typing.Optional[int] = marshaller.attrib(deserializer=int)
-
- #: The guild's description, if set.
- #:
- #: :type: :obj:`~str`, optional
description: typing.Optional[str] = marshaller.attrib(if_none=None, deserializer=str)
+ """The guild's description, if set."""
def format_splash_url(self, fmt: str = "png", size: int = 4096) -> typing.Optional[str]:
"""Generate the URL for this guild's splash image, if set.
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png``.
- Supports ``png``, ``jpeg``, ``jpg`` and ``webp``.
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``.
+ fmt : str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : int
+ The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
- :obj:`~str`, optional
+ str, optional
The string URL.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if self.splash_hash:
return urls.generate_cdn_url("splashes", str(self.id), self.splash_hash, fmt=fmt, size=size)
@@ -1050,22 +904,22 @@ def format_discovery_splash_url(self, fmt: str = "png", size: int = 4096) -> typ
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png``.
- Supports ``png``, ``jpeg``, ``jpg`` and ``webp``.
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``.
+ fmt : str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : int
+ The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
- :obj:`~str`, optional
+ str, optional
The string URL.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if self.discovery_splash_hash:
return urls.generate_cdn_url(
@@ -1084,384 +938,332 @@ def discovery_splash_url(self) -> typing.Optional[str]:
class Guild(PartialGuild):
"""A representation of a guild on Discord.
- Note
- ----
- If a guild object is considered to be unavailable, then the state of any
- other fields other than the :attr:`is_unavailable` and ``id`` are outdated
- or incorrect. If a guild is unavailable, then the contents of any other
- fields should be ignored.
+ !!! note
+ If a guild object is considered to be unavailable, then the state of any
+ other fields other than the `Guild.is_unavailable` and `Guild.id` are
+ outdated or incorrect. If a guild is unavailable, then the contents of
+ any other fields should be ignored.
"""
- #: The hash of the splash for the guild, if there is one.
- #:
- #: :type: :obj:`~str`, optional
splash_hash: typing.Optional[str] = marshaller.attrib(raw_name="splash", deserializer=str, if_none=None)
+ """The hash of the splash for the guild, if there is one."""
- #: The hash of the discovery splash for the guild, if there is one.
- #:
- #: :type: :obj:`~str`, optional
discovery_splash_hash: typing.Optional[str] = marshaller.attrib(
raw_name="discovery_splash", deserializer=str, if_none=None
)
+ """The hash of the discovery splash for the guild, if there is one."""
- #: The ID of the owner of this guild.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
owner_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the owner of this guild."""
- #: The guild level permissions that apply to the bot user,
- #: Will be :obj:`~None` when this object is retrieved through a REST request
- #: rather than from the gateway.
- #:
- #: :type: :obj:`~hikari.permissions.Permission`
my_permissions: _permissions.Permission = marshaller.attrib(
raw_name="permissions", deserializer=_permissions.Permission, if_undefined=None, default=None
)
+ """The guild level permissions that apply to the bot user.
+
+ This will be `None` when this object is retrieved through a REST request
+ rather than from the gateway.
+ """
- #: The voice region for the guild.
- #:
- #: :type: :obj:`~str`
region: str = marshaller.attrib(deserializer=str)
+ """The voice region for the guild."""
- #: The ID for the channel that AFK voice users get sent to, if set for the
- #: guild.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
afk_channel_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_none=None
)
+ """The ID for the channel that AFK voice users get sent to, if set."""
- #: How long a voice user has to be AFK for before they are classed as being
- #: AFK and are moved to the AFK channel (:attr:`afk_channel_id`).
- #:
- #: :type: :obj:`~datetime.timedelta`
afk_timeout: datetime.timedelta = marshaller.attrib(
deserializer=lambda seconds: datetime.timedelta(seconds=seconds)
)
+ """How long a voice user has to be AFK for before they are classed as being
+ AFK and are moved to the AFK channel (`Guild.afk_channel_id`).
+ """
# TODO: document when this is not specified.
- #: Defines if the guild embed is enabled or not.
- #:
- #: This information may not be present, in which case,
- #: it will be :obj:`~None` instead.
- #:
- #: :type: :obj:`~bool`, optional
is_embed_enabled: typing.Optional[bool] = marshaller.attrib(
raw_name="embed_enabled", deserializer=bool, if_undefined=False, default=False
)
+ """Defines if the guild embed is enabled or not.
+
+ This information may not be present, in which case, it will be `None`
+ instead.
+ """
- #: The channel ID that the guild embed will generate an invite to, if
- #: enabled for this guild.
- #:
- #: Will be :obj:`~None` if invites are disabled for this guild's embed.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
embed_channel_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, if_none=None, default=None
)
+ """The channel ID that the guild embed will generate an invite to.
+
+ Will be `None` if invites are disabled for this guild's embed.
+ """
- #: The verification level required for a user to participate in this guild.
- #:
- #: :type: :obj:`~GuildVerificationLevel`
verification_level: GuildVerificationLevel = marshaller.attrib(deserializer=GuildVerificationLevel)
+ """The verification level required for a user to participate in this guild."""
- #: The default setting for message notifications in this guild.
- #:
- #: :type: :obj:`~GuildMessageNotificationsLevel`
default_message_notifications: GuildMessageNotificationsLevel = marshaller.attrib(
deserializer=GuildMessageNotificationsLevel
)
+ """The default setting for message notifications in this guild."""
- #: The setting for the explicit content filter in this guild.
- #:
- #: :type: :obj:`~GuildExplicitContentFilterLevel`
explicit_content_filter: GuildExplicitContentFilterLevel = marshaller.attrib(
deserializer=GuildExplicitContentFilterLevel
)
+ """The setting for the explicit content filter in this guild."""
- #: The roles in this guild, represented as a mapping of ID to role object.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~GuildRole` ]
roles: typing.Mapping[bases.Snowflake, GuildRole] = marshaller.attrib(
deserializer=lambda roles: {r.id: r for r in map(GuildRole.deserialize, roles)},
)
+ """The roles in this guild, represented as a mapping of ID to role object."""
- #: The emojis that this guild provides, represented as a mapping of ID to
- #: emoji object.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~hikari.emojis.GuildEmoji` ]
emojis: typing.Mapping[bases.Snowflake, _emojis.GuildEmoji] = marshaller.attrib(
deserializer=lambda emojis: {e.id: e for e in map(_emojis.GuildEmoji.deserialize, emojis)},
)
+ """A mapping of IDs to the objects of the emojis this guild provides."""
- #: The required MFA level for users wishing to participate in this guild.
- #:
- #: :type: :obj:`~GuildMFALevel`
mfa_level: GuildMFALevel = marshaller.attrib(deserializer=GuildMFALevel)
+ """The required MFA level for users wishing to participate in this guild."""
- #: The ID of the application that created this guild, if it was created by
- #: a bot. If not, this is always :obj:`~None`.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
application_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_none=None
)
+ """The ID of the application that created this guild.
+
+ This will always be `None` for guilds that weren't created by a bot.
+ """
- #: Whether the guild is unavailable or not.
- #:
- #: This information is only available if the guild was sent via a
- #: ``GUILD_CREATE`` event. If the guild is received from any other place,
- #: this will always be :obj:`~None`.
- #:
- #: An unavailable guild cannot be interacted with, and most information may
- #: be outdated if that is the case.
- #:
- #: :type: :obj:`~bool`, optional
is_unavailable: typing.Optional[bool] = marshaller.attrib(
raw_name="unavailable", deserializer=bool, if_undefined=None, default=None
)
+ """Whether the guild is unavailable or not.
+
+ This information is only available if the guild was sent via a
+ `GUILD_CREATE` event. If the guild is received from any other place, this
+ will always be `None`.
+
+ An unavailable guild cannot be interacted with, and most information may
+ be outdated if that is the case.
+ """
# TODO: document in which cases this information is not available.
- #: Describes whether the guild widget is enabled or not. If this information
- #: is not present, this will be :obj:`~None`.
- #:
- #: :type: :obj:`~bool`, optional
is_widget_enabled: typing.Optional[bool] = marshaller.attrib(
raw_name="widget_enabled", deserializer=bool, if_undefined=None, default=None
)
+ """Describes whether the guild widget is enabled or not.
+
+ If this information is not present, this will be `None`.
+ """
- #: The channel ID that the widget's generated invite will send the user to,
- #: if enabled. If this information is unavailable, this will be :obj:`~None`.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
widget_channel_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, if_none=None, default=None
)
+ """The channel ID that the widget's generated invite will send the user to.
+
+ If this information is unavailable or this isn't enabled for the guild then
+ this will be `None`.
+ """
- #: The ID of the system channel (where welcome messages and Nitro boost
- #: messages are sent), or :obj:`~None` if it is not enabled.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
system_channel_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
if_none=None, deserializer=bases.Snowflake.deserialize
)
+ """The ID of the system channel or `None` if it is not enabled.
+
+ Welcome messages and Nitro boost messages may be sent to this channel.
+ """
- #: Flags for the guild system channel to describe which notification
- #: features are suppressed.
- #:
- #: :type: :obj:`~GuildSystemChannelFlag`
system_channel_flags: GuildSystemChannelFlag = marshaller.attrib(deserializer=GuildSystemChannelFlag)
+ """Flags for the guild system channel to describe which notifications are suppressed."""
- #: The ID of the channel where guilds with the :obj:`~GuildFeature.PUBLIC`
- #: ``features`` display rules and guidelines.
- #:
- #: If the :obj:`~GuildFeature.PUBLIC` feature is not defined, then this is
- #: :obj:`~None`.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
rules_channel_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
if_none=None, deserializer=bases.Snowflake.deserialize
)
+ """The ID of the channel where guilds with the `GuildFeature.PUBLIC`
+ `features` display rules and guidelines.
+
+ If the `GuildFeature.PUBLIC` feature is not defined, then this is `None`.
+ """
- #: The date and time that the bot user joined this guild.
- #:
- #: This information is only available if the guild was sent via a
- #: ``GUILD_CREATE`` event. If the guild is received from any other place,
- #: this will always be :obj:`~None`.
- #:
- #: :type: :obj:`~datetime.datetime`, optional
joined_at: typing.Optional[datetime.datetime] = marshaller.attrib(
deserializer=conversions.parse_iso_8601_ts, if_undefined=None, default=None
)
+ """The date and time that the bot user joined this guild.
+
+ This information is only available if the guild was sent via a `GUILD_CREATE`
+ event. If the guild is received from any other place, this will always be
+ `None`.
+ """
- #: Whether the guild is considered to be large or not.
- #:
- #: This information is only available if the guild was sent via a
- #: ``GUILD_CREATE`` event. If the guild is received from any other place,
- #: this will always be :obj:`~None`.
- #:
- #: The implications of a large guild are that presence information will
- #: not be sent about members who are offline or invisible.
- #:
- #: :type: :obj:`~bool`, optional
is_large: typing.Optional[bool] = marshaller.attrib(
raw_name="large", deserializer=bool, if_undefined=None, default=None
)
+ """Whether the guild is considered to be large or not.
+
+ This information is only available if the guild was sent via a `GUILD_CREATE`
+ event. If the guild is received from any other place, this will always b
+ `None`.
+
+ The implications of a large guild are that presence information will not be
+ sent about members who are offline or invisible.
+ """
- #: The number of members in this guild.
- #:
- #: This information is only available if the guild was sent via a
- #: ``GUILD_CREATE`` event. If the guild is received from any other place,
- #: this will always be :obj:`~None`.
- #:
- #: :type: :obj:`~int`, optional
member_count: typing.Optional[int] = marshaller.attrib(deserializer=int, if_undefined=None, default=None)
+ """The number of members in this guild.
+
+ This information is only available if the guild was sent via a `GUILD_CREATE`
+ event. If the guild is received from any other place, this will always be
+ `None`.
+ """
- #: A mapping of ID to the corresponding guild members in this guild.
- #:
- #: This information is only available if the guild was sent via a
- #: ``GUILD_CREATE`` event. If the guild is received from any other place,
- #: this will always be :obj:`~None`.
- #:
- #: Additionally, any offline members may not be included here, especially
- #: if there are more members than the large threshold set for the gateway
- #: this object was send with.
- #:
- #: This information will only be updated if your shards have the correct
- #: intents set for any update events.
- #:
- #: Essentially, you should not trust the information here to be a full
- #: representation. If you need complete accurate information, you should
- #: query the members using the appropriate API call instead.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~GuildMember` ], optional
members: typing.Optional[typing.Mapping[bases.Snowflake, GuildMember]] = marshaller.attrib(
deserializer=lambda members: {m.user.id: m for m in map(GuildMember.deserialize, members)},
if_undefined=None,
default=None,
)
+ """A mapping of ID to the corresponding guild members in this guild.
+
+ This information is only available if the guild was sent via a `GUILD_CREATE`
+ event. If the guild is received from any other place, this will always be
+ `None`.
+
+ Additionally, any offline members may not be included here, especially if
+ there are more members than the large threshold set for the gateway this
+ object was send with.
+
+ This information will only be updated if your shards have the correct
+ intents set for any update events.
+
+ Essentially, you should not trust the information here to be a full
+ representation. If you need complete accurate information, you should
+ query the members using the appropriate API call instead.
+ """
- #: A mapping of ID to the corresponding guild channels in this guild.
- #:
- #: This information is only available if the guild was sent via a
- #: ``GUILD_CREATE`` event. If the guild is received from any other place,
- #: this will always be :obj:`~None`.
- #:
- #: Additionally, any channels that you lack permissions to see will not be
- #: defined here.
- #:
- #: This information will only be updated if your shards have the correct
- #: intents set for any update events.
- #:
- #: To retrieve a list of channels in any other case, you should make an
- #: appropriate API call to retrieve this information.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~hikari.channels.GuildChannel` ], optional
channels: typing.Optional[typing.Mapping[bases.Snowflake, _channels.GuildChannel]] = marshaller.attrib(
deserializer=lambda guild_channels: {c.id: c for c in map(_channels.deserialize_channel, guild_channels)},
if_undefined=None,
default=None,
)
+ """A mapping of ID to the corresponding guild channels in this guild.
+
+ This information is only available if the guild was sent via a `GUILD_CREATE`
+ event. If the guild is received from any other place, this will always be
+ `None`.
+
+ Additionally, any channels that you lack permissions to see will not be
+ defined here.
+
+ This information will only be updated if your shards have the correct
+ intents set for any update events.
+
+ To retrieve a list of channels in any other case, you should make an
+ appropriate API call to retrieve this information.
+ """
- #: A mapping of member ID to the corresponding presence information for
- #: the given member, if available.
- #:
- #: This information is only available if the guild was sent via a
- #: ``GUILD_CREATE`` event. If the guild is received from any other place,
- #: this will always be :obj:`~None`.
- #:
- #: Additionally, any channels that you lack permissions to see will not be
- #: defined here.
- #:
- #: This information will only be updated if your shards have the correct
- #: intents set for any update events.
- #:
- #: To retrieve a list of presences in any other case, you should make an
- #: appropriate API call to retrieve this information.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~hikari.bases.Snowflake`, :obj:`~GuildMemberPresence` ], optional
presences: typing.Optional[typing.Mapping[bases.Snowflake, GuildMemberPresence]] = marshaller.attrib(
deserializer=lambda presences: {p.user.id: p for p in map(GuildMemberPresence.deserialize, presences)},
if_undefined=None,
default=None,
)
+ """A mapping of member ID to the corresponding presence information for
+ the given member, if available.
+
+ This information is only available if the guild was sent via a `GUILD_CREATE`
+ event. If the guild is received from any other place, this will always be
+ `None`.
+
+ Additionally, any channels that you lack permissions to see will not be
+ defined here.
+
+ This information will only be updated if your shards have the correct
+ intents set for any update events.
+
+ To retrieve a list of presences in any other case, you should make an
+ appropriate API call to retrieve this information.
+ """
- #: The maximum number of presences for the guild.
- #:
- #: If this is :obj:`~None`, then the default value is used (currently 5000).
- #:
- #: :type: :obj:`~int`, optional
max_presences: typing.Optional[int] = marshaller.attrib(
deserializer=int, if_undefined=None, if_none=None, default=None
)
+ """The maximum number of presences for the guild.
+
+ If this is `None`, then the default value is used (currently 5000).
+ """
- #: The maximum number of members allowed in this guild.
- #:
- #: This information may not be present, in which case, it will be :obj:`~None`.
- #:
- #: :type: :obj:`~int`, optional
max_members: typing.Optional[int] = marshaller.attrib(deserializer=int, if_undefined=None, default=None)
+ """The maximum number of members allowed in this guild.
+
+ This information may not be present, in which case, it will be `None`.
+ """
- #: The vanity URL code for the guild's vanity URL.
- #:
- #: This is only present if :obj:`~GuildFeature.VANITY_URL` is in the
- #: ``features`` for this guild. If not, this will always be :obj:`~None`.
- #:
- #: :type: :obj:`~str`, optional
vanity_url_code: typing.Optional[str] = marshaller.attrib(deserializer=str, if_none=None)
+ """The vanity URL code for the guild's vanity URL.
+
+ This is only present if `GuildFeature.VANITY_URL` is in `Guild.features` for
+ this guild. If not, this will always be `None`.
+ """
- #: The guild's description.
- #:
- #: This is only present if certain :obj:`~GuildFeature`'s are set in the
- #: ``features`` for this guild. Otherwise, this will always be :obj:`~None`.
- #:
- #: :type: :obj:`~str`, optional
description: typing.Optional[str] = marshaller.attrib(if_none=None, deserializer=str)
+ """The guild's description.
+
+ This is only present if certain `GuildFeature`'s are set in
+ `Guild.features` for this guild. Otherwise, this will always be `None`.
+ """
- #: The hash for the guild's banner.
- #:
- #: This is only present if the guild has :obj:`~GuildFeature.BANNER` in the
- #: ``features`` for this guild. For all other purposes, it is
- # :obj:`~None`.
- #:
- #: :type: :obj:`~str`, optional
banner_hash: typing.Optional[str] = marshaller.attrib(raw_name="banner", if_none=None, deserializer=str)
+ """The hash for the guild's banner.
+
+ This is only present if the guild has `GuildFeature.BANNER` in
+ `Guild.features` for this guild. For all other purposes, it is `None`.
+ """
- #: The premium tier for this guild.
- #:
- #: :type: :obj:`~GuildPremiumTier`
premium_tier: GuildPremiumTier = marshaller.attrib(deserializer=GuildPremiumTier)
+ """The premium tier for this guild."""
- #: The number of nitro boosts that the server currently has.
- #:
- #: This information may not be present, in which case, it will be :obj:`~None`.
- #:
- #: :type: :obj:`~int`, optional
premium_subscription_count: typing.Optional[int] = marshaller.attrib(
deserializer=int, if_undefined=None, default=None
)
+ """The number of nitro boosts that the server currently has.
+
+ This information may not be present, in which case, it will be `None`.
+ """
- #: The preferred locale to use for this guild.
- #:
- #: This can only be change if :obj:`~GuildFeature.PUBLIC` is in the
- #: ``features`` for this guild and will otherwise default to ``en-US```.
- #:
- #: :type: :obj:`~str`
preferred_locale: str = marshaller.attrib(deserializer=str)
+ """The preferred locale to use for this guild.
+
+ This can only be change if `GuildFeature.PUBLIC` is in `Guild.features`
+ for this guild and will otherwise default to `en-US`.
+ """
- #: The channel ID of the channel where admins and moderators receive notices
- #: from Discord.
- #:
- #: This is only present if :obj:`~GuildFeature.PUBLIC` is in the
- #: ``features`` for this guild. For all other purposes, it should be
- #: considered to be :obj:`~None`.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
public_updates_channel_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
if_none=None, deserializer=bases.Snowflake.deserialize
)
+ """The channel ID of the channel where admins and moderators receive notices
+ from Discord.
+
+ This is only present if `GuildFeature.PUBLIC` is in `Guild.features` for
+ this guild. For all other purposes, it should be considered to be `None`.
+ """
def format_splash_url(self, fmt: str = "png", size: int = 4096) -> typing.Optional[str]:
"""Generate the URL for this guild's splash image, if set.
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png``.
- Supports ``png``, ``jpeg``, ``jpg`` and ``webp``.
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``.
+ fmt : str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : int
+ The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
- :obj:`~str`, optional
+ str, optional
The string URL.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if self.splash_hash:
return urls.generate_cdn_url("splashes", str(self.id), self.splash_hash, fmt=fmt, size=size)
@@ -1477,22 +1279,22 @@ def format_discovery_splash_url(self, fmt: str = "png", size: int = 4096) -> typ
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png``.
- Supports ``png``, ``jpeg``, ``jpg`` and ``webp``.
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``.
+ fmt : str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : int
+ The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
- :obj:`~str`, optional
+ str, optional
The string URL.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if self.discovery_splash_hash:
return urls.generate_cdn_url(
@@ -1510,22 +1312,22 @@ def format_banner_url(self, fmt: str = "png", size: int = 4096) -> typing.Option
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png``.
- Supports ``png``, ``jpeg``, ``jpg`` and ``webp``.
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``.
+ fmt : str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : int
+ The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
- :obj:`~str`, optional
+ str, optional
The string URL.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if self.banner_hash:
return urls.generate_cdn_url("banners", str(self.id), self.banner_hash, fmt=fmt, size=size)
diff --git a/hikari/intents.py b/hikari/intents.py
index 688a30ae1d..9c8030bea1 100644
--- a/hikari/intents.py
+++ b/hikari/intents.py
@@ -34,121 +34,146 @@ class Intent(more_enums.FlagMixin, enum.IntFlag):
Any events not in an intent category will be fired regardless of what
intents you provide.
- Warnings
- --------
- If you are using the V7 Gateway, you will be REQUIRED to provide some form
- of intent value when you connect. Failure to do so may result in immediate
- termination of the session server-side.
-
- Notes
- -----
- Discord now places limits on certain events you can receive without
- whitelisting your bot first. On the ``Bot`` tab in the developer's portal
- for your bot, you should now have the option to enable functionality
- for receiving these events.
-
- If you attempt to request an intent type that you have not whitelisted
- your bot for, you will be disconnected on startup with a ``4014`` closure
- code.
+ !!! info
+ Discord now places limits on certain events you can receive without
+ whitelisting your bot first. On the `Bot` tab in the developer's portal
+ for your bot, you should now have the option to enable functionality
+ for receiving these events.
+
+ If you attempt to request an intent type that you have not whitelisted
+ your bot for, you will be disconnected on startup with a `4014` closure
+ code.
+
+ !!! warning
+ If you are using the V7 Gateway, you will be REQUIRED to provide some
+ form of intent value when you connect. Failure to do so may result in
+ immediate termination of the session server-side.
"""
- #: Subscribes to the following events:
- #: * GUILD_CREATE
- #: * GUILD_UPDATE
- #: * GUILD_DELETE
- #: * GUILD_ROLE_CREATE
- #: * GUILD_ROLE_UPDATE
- #: * GUILD_ROLE_DELETE
- #: * CHANNEL_CREATE
- #: * CHANNEL_UPDATE
- #: * CHANNEL_DELETE
- #: * CHANNEL_PINS_UPDATE
GUILDS = 1 << 0
+ """Subscribes to the following events:
+
+ * GUILD_CREATE
+ * GUILD_UPDATE
+ * GUILD_DELETE
+ * GUILD_ROLE_CREATE
+ * GUILD_ROLE_UPDATE
+ * GUILD_ROLE_DELETE
+ * CHANNEL_CREATE
+ * CHANNEL_UPDATE
+ * CHANNEL_DELETE
+ * CHANNEL_PINS_UPDATE
+ """
- #: Subscribes to the following events:
- #: * GUILD_MEMBER_ADD
- #: * GUILD_MEMBER_UPDATE
- #: * GUILD_MEMBER_REMOVE
- #:
- #: Warnings
- #: --------
- #: This intent is privileged, and requires enabling/whitelisting to use.
GUILD_MEMBERS = 1 << 1
+ """Subscribes to the following events:
+
+ * GUILD_MEMBER_ADD
+ * GUILD_MEMBER_UPDATE
+ * GUILD_MEMBER_REMOVE
+
+ !!! warning
+ This intent is privileged, and requires enabling/whitelisting to use.
+ """
- #: Subscribes to the following events:
- #: * GUILD_BAN_ADD
- #: * GUILD_BAN_REMOVE
GUILD_BANS = 1 << 2
+ """Subscribes to the following events:
+
+ * GUILD_BAN_ADD
+ * GUILD_BAN_REMOVE
+ """
- #: Subscribes to the following events:
- #: * GUILD_EMOJIS_UPDATE
GUILD_EMOJIS = 1 << 3
+ """Subscribes to the following events:
+
+ * GUILD_EMOJIS_UPDATE
+ """
- #: Subscribes to the following events:
- #: * GUILD_INTEGRATIONS_UPDATE
GUILD_INTEGRATIONS = 1 << 4
+ """Subscribes to the following events:
+
+ * GUILD_INTEGRATIONS_UPDATE
+ """
- #: Subscribes to the following events:
- #: * WEBHOOKS_UPDATE
GUILD_WEBHOOKS = 1 << 5
+ """Subscribes to the following events:
+
+ * WEBHOOKS_UPDATE
+ """
- #: Subscribes to the following events:
- #: * INVITE_CREATE
- #: * INVITE_DELETE
GUILD_INVITES = 1 << 6
+ """Subscribes to the following events:
+
+ * INVITE_CREATE
+ * INVITE_DELETE
+ """
- #: Subscribes to the following events:
- #: * VOICE_STATE_UPDATE
GUILD_VOICE_STATES = 1 << 7
+ """Subscribes to the following events:
+
+ * VOICE_STATE_UPDATE
+ """
- #: Subscribes to the following events:
- #: * PRESENCE_UPDATE
- #:
- #: Warnings
- #: --------
- #: This intent is privileged, and requires enabling/whitelisting to use.
GUILD_PRESENCES = 1 << 8
+ """Subscribes to the following events:
+
+ * PRESENCE_UPDATE
+
+ !!! warning
+ This intent is privileged, and requires enabling/whitelisting to use."""
- #: Subscribes to the following events:
- #: * MESSAGE_CREATE
- #: * MESSAGE_UPDATE
- #: * MESSAGE_DELETE
- #: * MESSAGE_BULK
GUILD_MESSAGES = 1 << 9
+ """Subscribes to the following events:
+
+ * MESSAGE_CREATE
+ * MESSAGE_UPDATE
+ * MESSAGE_DELETE
+ * MESSAGE_BULK
+ """
- #: Subscribes to the following events:
- #: * MESSAGE_REACTION_ADD
- #: * MESSAGE_REACTION_REMOVE
- #: * MESSAGE_REACTION_REMOVE_ALL
- #: * MESSAGE_REACTION_REMOVE_EMOJI
GUILD_MESSAGE_REACTIONS = 1 << 10
+ """Subscribes to the following events:
+
+ * MESSAGE_REACTION_ADD
+ * MESSAGE_REACTION_REMOVE
+ * MESSAGE_REACTION_REMOVE_ALL
+ * MESSAGE_REACTION_REMOVE_EMOJI
+ """
- #: Subscribes to the following events:
- #: * TYPING_START
GUILD_MESSAGE_TYPING = 1 << 11
+ """Subscribes to the following events:
+
+ * TYPING_START
+ """
- #: Subscribes to the following events:
- #: * CHANNEL_CREATE
- #: * MESSAGE_CREATE
- #: * MESSAGE_UPDATE
- #: * MESSAGE_DELETE
DIRECT_MESSAGES = 1 << 12
+ """Subscribes to the following events:
+
+ * CHANNEL_CREATE
+ * MESSAGE_CREATE
+ * MESSAGE_UPDATE
+ * MESSAGE_DELETE
+ """
- #: Subscribes to the following events:
- #: * MESSAGE_REACTION_ADD
- #: * MESSAGE_REACTION_REMOVE
- #: * MESSAGE_REACTION_REMOVE_ALL
DIRECT_MESSAGE_REACTIONS = 1 << 13
+ """Subscribes to the following events:
+
+ * MESSAGE_REACTION_ADD
+ * MESSAGE_REACTION_REMOVE
+ * MESSAGE_REACTION_REMOVE_ALL
+ """
- #: Subscribes to the following events
- #: * TYPING_START
DIRECT_MESSAGE_TYPING = 1 << 14
+ """Subscribes to the following events
+
+ * TYPING_START
+ """
@property
def is_privileged(self) -> bool:
"""Whether the intent requires elevated privileges.
- If this is ``True``, you will be required to opt-in to using this intent
+ If this is `True`, you will be required to opt-in to using this intent
on the Discord Developer Portal before you can utilise it in your
application.
"""
diff --git a/hikari/internal/__init__.py b/hikari/internal/__init__.py
index a8944f790e..638a2d5a11 100644
--- a/hikari/internal/__init__.py
+++ b/hikari/internal/__init__.py
@@ -16,7 +16,4 @@
#
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
-"""Various utilities used internally within this API.
-
-|internal|
-"""
+"""Various utilities used internally within this API."""
diff --git a/hikari/internal/assertions.py b/hikari/internal/assertions.py
index 3883f5c054..5976516d62 100644
--- a/hikari/internal/assertions.py
+++ b/hikari/internal/assertions.py
@@ -21,8 +21,6 @@
These are functions that validate a value, and are expected to return the value
on success but error on any failure. This allows for quick checking of
conditions that might break the function or cause it to misbehave.
-
-|internal|
"""
__all__ = [
"assert_that",
@@ -39,7 +37,7 @@
def assert_that(condition: bool, message: str = None, error_type: type = ValueError) -> None:
- """If the given condition is falsified, raise a :obj:`~ValueError`.
+ """If the given condition is falsified, raise a `ValueError`.
Will be raised with the optional description if provided.
"""
@@ -48,7 +46,7 @@ def assert_that(condition: bool, message: str = None, error_type: type = ValueEr
def assert_not_none(value: ValueT, message: typing.Optional[str] = None) -> ValueT:
- """If the given value is :obj:`~None`, raise a :obj:`~ValueError`.
+ """If the given value is `None`, raise a `ValueError`.
Will be raised with the optional description if provided.
"""
@@ -58,13 +56,13 @@ def assert_not_none(value: ValueT, message: typing.Optional[str] = None) -> Valu
def assert_in_range(value, min_inclusive, max_inclusive, name: str = None):
- """If a value is not in the range [min, max], raise a :obj:`~ValueError`."""
+ """If a value is not in the range [min, max], raise a `ValueError`."""
if not (min_inclusive <= value <= max_inclusive):
name = name or "The value"
raise ValueError(f"{name} must be in the inclusive range of {min_inclusive} and {max_inclusive}")
def assert_is_int_power(value: int, power: int) -> bool:
- """If a value is not a power the given int, raise :obj:`~ValueError`."""
+ """If a value is not a power the given int, raise `ValueError`."""
logarithm = math.log(value, power)
assert_that(logarithm.is_integer(), f"value must be an integer power of {power}")
diff --git a/hikari/internal/conversions.py b/hikari/internal/conversions.py
index a2f720a223..d8cac674ec 100644
--- a/hikari/internal/conversions.py
+++ b/hikari/internal/conversions.py
@@ -64,10 +64,10 @@
def nullable_cast(value: CastInputT, cast: TypeCastT, /) -> ResultT:
- """Attempt to cast the given ``value`` with the given ``cast``.
+ """Attempt to cast the given `value` with the given `cast`.
- This will only succeed if ``value`` is not :obj:`~None`. If it is
- :obj:`~None`, then :obj:`~None` is returned instead.
+ This will only succeed if `value` is not `None`. If it is `None`, then
+ `None` is returned instead.
"""
if value is None:
return None
@@ -77,7 +77,7 @@ def nullable_cast(value: CastInputT, cast: TypeCastT, /) -> ResultT:
def try_cast(value: CastInputT, cast: TypeCastT, default: DefaultT = None, /) -> ResultT:
"""Try to cast the given value to the given cast.
- If it throws a :obj:`~Exception` or derivative, it will return ``default``
+ If it throws a `Exception` or derivative, it will return `default`
instead of the cast value instead.
"""
with contextlib.suppress(Exception):
@@ -90,7 +90,7 @@ def try_cast_or_defer_unary_operator(type_: typing.Type, /):
Parameters
----------
- type_ : :obj:`~typing.Callable` [ ..., ``output type`` ]
+ type_ : typing.Callable [ ..., `output type` ]
The type to cast to.
"""
return lambda data: try_cast(data, type_, data)
@@ -103,17 +103,17 @@ def put_if_specified(
type_after: typing.Optional[TypeCastT] = None,
/,
) -> None:
- """Add a value to the mapping under the given key as long as the value is not ``...``.
+ """Add a value to the mapping under the given key as long as the value is not `...`.
Parameters
----------
- mapping : :obj:`~typing.Dict` [ :obj:`~typing.Hashable`, :obj:`~typing.Any` ]
+ mapping : typing.Dict [ typing.Hashable, typing.Any ]
The mapping to add to.
- key : :obj:`~typing.Hashable`
+ key : typing.Hashable
The key to add the value under.
- value : :obj:`~typing.Any`
+ value : typing.Any
The value to add.
- type_after : :obj:`~typing.Callable` [ [ ``input type`` ], ``output type`` ], optional
+ type_after : typing.Callable [ [ `input type` ], `output type` ], optional
Type to apply to the value when added.
"""
if value is not ...:
@@ -128,23 +128,22 @@ def image_bytes_to_image_data(img_bytes: typing.Optional[bytes] = None, /) -> ty
Parameters
----------
- img_bytes : :obj:`~bytes`, optional
+ img_bytes : bytes, optional
The image bytes.
Raises
------
- :obj:`~ValueError`
+ ValueError
If the image type passed is not supported.
Returns
-------
- :obj:`~str`, optional
- The ``image_bytes`` given encoded into an image data string or
- :obj:`~None`.
+ str, optional
+ The `image_bytes` given encoded into an image data string or
+ `None`.
- Note
- ----
- Supported image types: ``.png``, ``.jpeg``, ``.jfif``, ``.gif``, ``.webp``
+ !!! note
+ Supported image types: `.png`, `.jpeg`, `.jfif`, `.gif`, `.webp`
"""
if img_bytes is None:
return None
@@ -170,12 +169,12 @@ def parse_http_date(date_str: str, /) -> datetime.datetime:
Parameters
----------
- date_str : :obj:`~str`
+ date_str : str
The RFC-2822 (section 3.3) compliant date string to parse.
Returns
-------
- :obj:`~datetime.datetime`
+ datetime.datetime
The HTTP date as a datetime object.
See Also
@@ -186,21 +185,21 @@ def parse_http_date(date_str: str, /) -> datetime.datetime:
def parse_iso_8601_ts(date_string: str, /) -> datetime.datetime:
- """Parse an ISO 8601 date string into a :obj:`~datetime.datetime` object.
+ """Parse an ISO 8601 date string into a `datetime.datetime` object.
Parameters
----------
- date_string : :obj:`~str`
+ date_string : str
The ISO 8601 compliant date string to parse.
Returns
-------
- :obj:`~datetime.datetime`
+ datetime.datetime
The ISO 8601 date string as a datetime object.
See Also
--------
- ``_
+ https://en.wikipedia.org/wiki/ISO_8601
"""
year, month, day = map(int, ISO_8601_DATE_PART.findall(date_string)[0])
@@ -224,32 +223,32 @@ def parse_iso_8601_ts(date_string: str, /) -> datetime.datetime:
def discord_epoch_to_datetime(epoch: int, /) -> datetime.datetime:
- """Parse a Discord epoch into a :obj:`~datetime.datetime` object.
+ """Parse a Discord epoch into a `datetime.datetime` object.
Parameters
----------
- epoch : :obj:`~int`
+ epoch : int
Number of milliseconds since 1/1/2015 (UTC)
Returns
-------
- :obj:`~datetime.datetime`
+ datetime.datetime
Number of seconds since 1/1/1970 within a datetime object (UTC).
"""
return datetime.datetime.fromtimestamp(epoch / 1000 + DISCORD_EPOCH, datetime.timezone.utc)
def unix_epoch_to_datetime(epoch: int, /) -> datetime.datetime:
- """Parse a UNIX epoch to a :obj:`~datetime.datetime` object.
+ """Parse a UNIX epoch to a `datetime.datetime` object.
Parameters
----------
- epoch : :obj:`~int`
+ epoch : int
Number of milliseconds since 1/1/1970 (UTC)
Returns
-------
- :obj:`~datetime.datetime`
+ datetime.datetime
Number of seconds since 1/1/1970 within a datetime object (UTC).
"""
return datetime.datetime.fromtimestamp(epoch / 1000, datetime.timezone.utc)
@@ -265,12 +264,12 @@ def seek(
Parameters
----------
- offset : :obj:`~int`
+ offset : int
The offset to seek to.
- whence : :obj:`~int`
- If ``0``, as the default, then use absolute file positioning.
- If ``1``, then seek to the current position.
- If ``2``, then seek relative to the end of the file.
+ whence : int
+ If `0`, as the default, then use absolute file positioning.
+ If `1`, then seek to the current position.
+ If `2`, then seek relative to the end of the file.
"""
def tell(self) -> int:
@@ -278,7 +277,7 @@ def tell(self) -> int:
Returns
-------
- :obj:`~int`
+ int
The stream position.
"""
@@ -287,7 +286,7 @@ def read(self) -> typing.AnyStr:
Returns
-------
- :obj:`~str`
+ str
The string that was read.
"""
@@ -298,17 +297,17 @@ def close(self) -> None:
def make_resource_seekable(resource: typing.Any, /) -> Seekable:
"""Make a seekable resource to use off some representation of data.
- This supports :obj:`~bytes`, :obj:`~bytearray`, :obj:`~memoryview`, and
- :obj:`~str`. Anything else is just returned.
+ This supports `bytes`,`bytearray`, `memoryview`, and
+ `str`. Anything else is just returned.
Parameters
----------
- resource : :obj:`~typing.Any`
+ resource : typing.Any
The resource to check.
Returns
-------
- :obj:`~typing.Union` [ :obj:`~io.BytesIO`, :obj:`~io.StringIO` ]
+ typing.Union [ io.BytesIO, io.StringIO` ]
An stream-compatible resource where possible.
"""
if isinstance(resource, (bytes, bytearray)):
@@ -324,17 +323,17 @@ def make_resource_seekable(resource: typing.Any, /) -> Seekable:
def get_bytes_from_resource(resource: typing.Any) -> bytes:
"""Take in any file-like object and return the raw bytes data from it.
- Supports any ``FileLikeT`` type that isn't string based.
+ Supports any `FileLikeT` type that isn't string based.
Anything else is just returned.
Parameters
----------
- resource : ``FileLikeT``
+ resource : FileLikeT
The resource to get bytes from.
Returns
-------
- :obj:`~bytes`
+ byte
The resulting bytes.
"""
if isinstance(resource, bytearray):
@@ -359,46 +358,45 @@ def snoop_typehint_from_scope(frame: types.FrameType, typehint: typing.Union[str
This snoops around the local and global scope for the given frame to find
the given attribute name, taking into account nested function calls. The
reason to do this is that if a string type hint is used, or the
- ``from __future__ import annotations`` directive is used, the physical thing
+ `from __future__ import annotations` directive is used, the physical thing
that the type hint represents will no longer be evaluated by the
interpreter. This is an implementation that does not require the use of
- :obj:`~eval`, and thus reduces the risk of arbitrary code execution as a
+ `eval`, and thus reduces the risk of arbitrary code execution as a
result.
- Nested parameters such as :obj:`~typing.Sequence` should also be able to be
+ Nested parameters such as `typing.Sequence` should also be able to be
resolved correctly.
Parameters
----------
- frame : :obj:`~types.FrameType`
+ frame : types.FrameType
The stack frame that the element with the typehint was defined in.
- This is retrieved using :obj:`~inspect.stack` ``(frame_no)[0][0]``,
- where ``frame_no`` is the number of frames from this invocation that
+ This is retrieved using `inspect.stack` `(frame_no)[0][0]`,
+ where `frame_no` is the number of frames from this invocation that
you want to snoop the scope at.
- typehint : :obj:`~typing.Union` [ :obj:`~str`, :obj:`~typing.Any` ]
- The type hint to resolve. If a non-:obj:`~str` is passed, then this is
+ typehint : typing.Union [ str, typing.Any ]
+ The type hint to resolve. If a non-`str` is passed, then this is
returned immediately as the result.
Returns
-------
- :obj:`~typing.Any`
+ typing.Any
The physical representation of the given type hint.
Raises
------
- :obj:`~NameError`
+ NameError
If the attribute was not found.
- Warnings
- --------
- The input frame must be manually dereferenced using the ``del`` keyword
- after use. Any functions that are decorated and wrapped when using this
- lookup must use :obj:`~functools.wraps` to ensure that the correct scope is
- identified on the stack.
-
- This is incredibly unpythonic and baremetal, but due to
- `PEP 563 ` there is no other
- consistent way of making this work correctly.
+ !!! warning
+ The input frame must be manually dereferenced using the `del` keyword
+ after use. Any functions that are decorated and wrapped when using this
+ lookup must use `functools.wraps` to ensure that the correct scope is
+ identified on the stack.
+
+ This is incredibly unpythonic and baremetal, but due to
+ [PEP 563](https://www.python.org/dev/peps/pep-0563/) there is no other
+ consistent way of making this work correctly.
"""
if not isinstance(typehint, str):
return typehint
@@ -420,33 +418,32 @@ def dereference_int_flag(
int_flag_type: typing.Type[IntFlagT],
raw_value: typing.Union[RawIntFlagValueT, typing.Collection[RawIntFlagValueT]],
) -> IntFlagT:
- """Cast to the provided :obj:`~enum.IntFlag` type.
+ """Cast to the provided `enum.IntFlag` type.
This supports resolving bitfield integers as well as decoding a sequence
of case insensitive flag names into one combined value.
Parameters
----------
- int_flag_type : :obj:`~typing.Type` [ :obj:`~enum.IntFlag` ]
+ int_flag_type : typing.Type [ enum.IntFlag ]
The type of the int flag to check.
- raw_value : ``Castable Value``
+ raw_value : Castable Value
The raw value to convert.
Returns
-------
- :obj:`~enum.IntFlag`
+ enum.IntFlag
The cast value as a flag.
- Notes
- -----
- Types that are a ``Castable Value`` include:
- - :obj:`~str`
- - :obj:`~int`
- - :obj:`~typing.SupportsInt`
- - :obj:`~typing.Collection` [ ``Castable Value`` ]
+ !!! note
+ Types that are a `Castable Value` include:
+ - `str`
+ - `int`
+ - `typing.SupportsInt`
+ - `typing.Collection` [ `Castable Value` ]
- When a collection is passed, values will be combined using functional
- reduction via the :obj:operator.or_` operator.
+ When a collection is passed, values will be combined using functional
+ reduction via the `operator.or_` operator.
"""
if isinstance(raw_value, str) and raw_value.isdigit():
raw_value = int(raw_value)
diff --git a/hikari/internal/helpers.py b/hikari/internal/helpers.py
index b70a18d8fd..cc6fd89039 100644
--- a/hikari/internal/helpers.py
+++ b/hikari/internal/helpers.py
@@ -37,11 +37,11 @@ def warning(message: str, category: typing.Type[Warning], stack_level: int = 1)
Parameters
----------
- message : :obj:`~str`
+ message : str
The message to display.
- category : :obj:`~typing.Type` [ :obj:`~Warning` ]
+ category : typing.Type [ Warning ]
The type of warning to raise.
- stack_level : :obj:`int`
+ stack_level : int
How many stack frames to go back to find the user's invocation.
"""
@@ -57,28 +57,28 @@ def generate_allowed_mentions(
Parameters
----------
- mentions_everyone : :obj:`~bool`
- Whether ``@everyone`` and ``@here`` mentions should be resolved by
+ mentions_everyone : bool
+ Whether `@everyone` and `@here` mentions should be resolved by
discord and lead to actual pings.
- user_mentions : :obj:`~typing.Union` [ :obj:`~typing.Collection` [ :obj:`~typing.Union` [ :obj:`~hikari.users.User`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ], :obj:`~bool` ]
+ user_mentions : typing.Union [ typing.Collection [ typing.Union [ hikari.users.User, hikari.bases.Snowflake, int ], bool ]
Either an array of user objects/IDs to allow mentions for,
- :obj:`~True` to allow all user mentions or :obj:`~False` to block all
+ `True` to allow all user mentions or `False` to block all
user mentions from resolving.
- role_mentions : :obj:`~typing.Union` [ :obj:`~typing.Collection` [ :obj:`~typing.Union` [ :obj:`~hikari.guilds.GuildRole`, :obj:`~hikari.bases.Snowflake`, :obj:`~int` ] ], :obj:`~bool` ]
+ role_mentions : typing.Union [ typing.Collection [ typing.Union [ hikari.guilds.GuildRole, hikari.bases.Snowflake, int ] ], bool ]
Either an array of guild role objects/IDs to allow mentions for,
- :obj:`~True` to allow all role mentions or :obj:`~False` to block all
+ `True` to allow all role mentions or `False` to block all
role mentions from resolving.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Sequence` [ :obj:`~str` ] ]
+ typing.Dict [ str, typing.Sequence [ str ] ]
The resulting allowed mentions dict object.
Raises
------
- :obj:`~ValueError`
+ ValueError
If more than 100 unique objects/entities are passed for
- ``role_mentions`` or ``user_mentions.
+ `role_mentions` or `user_mentions.
"""
parsed_mentions = []
allowed_mentions = {}
@@ -128,40 +128,39 @@ async def pagination_handler(
) -> typing.AsyncIterator[typing.Any]:
"""Generate an async iterator for handling paginated endpoints.
- This will handle Discord's ``before`` and ``after`` pagination.
+ This will handle Discord's `before` and `after` pagination.
Parameters
----------
- deserializer : :obj:`~typing.Callable` [ [ :obj:`~typing.Any` ], :obj:`~typing.Any` ]
+ deserializer : typing.Callable [ [ typing.Any ], typing.Any ]
The deserializer to use to deserialize raw elements.
- direction : :obj:`~typing.Union` [ ``"before"``, ``"after"`` ]
+ direction : typing.Union [ `"before"`, `"after"` ]
The direction that this paginator should go in.
- request : :obj:`~typing.Callable` [ ``...``, :obj:`~typing.Coroutine` [ :obj:`~typing.Any`, :obj:`~typing.Any`, :obj:`~typing.Any` ] ]
- The :obj:`hikari.net.rest_sessions.LowLevelRestfulClient` method that should be
+ request : typing.Callable [ ..., typing.Coroutine [ typing.Any, typing.Any, typing.Any ] ]
+ The `hikari.net.rest.REST` method that should be
called to make requests for this paginator.
- reversing : :obj:`~bool`
+ reversing : bool
Whether the retrieved array of objects should be reversed before
iterating through it, this is needed for certain endpoints like
- ``fetch_messages_before`` where the order is static regardless of
- if you're using ``before`` or ``after``.
- start : :obj:`~int`, optional
- The snowflake ID that this paginator should start at, ``0`` may be
- passed for ``forward`` pagination to start at the first created
- entity and :obj:`~None` may be passed for ``before`` pagination to
+ `fetch_messages_before` where the order is static regardless of
+ if you're using `before` or `after`.
+ start : int, optional
+ The snowflake ID that this paginator should start at, `0` may be
+ passed for `forward` pagination to start at the first created
+ entity and `None` may be passed for `before` pagination to
start at the newest entity (based on when it's snowflake timestamp).
- limit : :obj:`~int`, optional
+ limit : int, optional
The amount of deserialized entities that the iterator should return
- total, will be unlimited if set to :obj:`~None`.
- id_getter : :obj:`~typing.Callable` [ [ :obj:`~typing.Any` ], :obj:`~str` ]
+ total, will be unlimited if set to `None`.
+ id_getter : typing.Callable [ [ typing.Any ], str ]
**kwargs
- Kwargs to pass through to ``request`` for every request made along
+ Kwargs to pass through to `request` for every request made along
with the current decided limit and direction snowflake.
Returns
-------
- :obj:`~typing.AsyncIterator` [ :obj:`~typing.Any` ]
+ typing.AsyncIterator [ typing.Any ]
An async iterator of the found deserialized found objects.
-
"""
while payloads := await request(
limit=100 if limit is None or limit > 100 else limit,
diff --git a/hikari/internal/marshaller.c b/hikari/internal/marshaller.c
index cb7a689b31..b4fd0dec1b 100644
--- a/hikari/internal/marshaller.c
+++ b/hikari/internal/marshaller.c
@@ -39,12 +39,9 @@ PyDoc_STRVAR(
module_doc,
"An internal marshalling utility used by internal API components.\n"
"\n"
- "Warning\n"
- "-------\n"
- "You should not change anything in this file, if you do, you will likely get\n"
- "unexpected behaviour elsewhere.\n"
- "\n"
- "|internal|\n"
+ "!!! warning\n"
+ " You should not change anything in this file, if you do, you will likely get\n"
+ " unexpected behaviour elsewhere.\n"
);
@@ -92,27 +89,34 @@ PyDoc_STRVAR(
"\n"
"Parameters\n"
"----------\n"
- "handle_string : :obj:`str`\n"
+ "handle_string : str\n"
" The handle to the object to refer to. This is in the format\n"
- " ``fully.qualified.module.name#object.attribute``. If no ``#`` is\n"
+ " `fully.qualified.module.name#object.attribute`. If no `#` is\n"
" input, then the reference will be made to the module itself.\n"
"\n"
"Returns\n"
"-------\n"
- ":obj:`typing.Any`\n"
+ "typing.Any\n"
" The thing that is referred to from this reference.\n"
"\n"
"Examples\n"
"--------\n"
- "``\"collections#deque\"``:\n"
- " Refers to :obj:`collections.deque`\n"
- "``\"asyncio.tasks#Task\"``:\n"
- " Refers to ``asyncio.tasks.Task``\n"
- "``\"hikari.net\"``:\n"
- " Refers to :obj:`hikari.net`\n"
- "``\"foo.bar#baz.bork.qux\"``:\n"
- " Would refer to a theoretical ``qux`` attribute on a ``bork``\n"
- " attribute on a ``baz`` object in the ``foo.bar`` module.\n"
+ "* `\"collections#deque\":\n"
+ "\n"
+ " Refers to `collections.deque`\n"
+ "\n"
+ "* `\"asyncio.tasks#Task\"`:\n"
+ "\n"
+ " Refers to `asyncio.tasks.Task`\n"
+ "\n"
+ "* `\"hikari.net\"`:\n"
+ "\n"
+ " Refers to `hikari.net`\n"
+ "\n"
+ "* `\"foo.bar#baz.bork.qux\"`:\n"
+ "\n"
+ " Would refer to a theoretical `qux` attribute on a `bork`\n"
+ " attribute on a `baz` object in the `foo.bar` module.\n"
);
diff --git a/hikari/internal/marshaller.py b/hikari/internal/marshaller.py
index 40492f95c6..723afbe057 100644
--- a/hikari/internal/marshaller.py
+++ b/hikari/internal/marshaller.py
@@ -18,12 +18,9 @@
# along with Hikari. If not, see .
"""An internal marshalling utility used by internal API components.
-Warning
--------
-You should not change anything in this file, if you do, you will likely get
-unexpected behaviour elsewhere.
-
-|internal|
+!!! warning
+ You should not change anything in this file, if you do, you will likely get
+ unexpected behaviour elsewhere.
"""
__all__ = [
"RAISE",
@@ -61,27 +58,34 @@ def dereference_handle(handle_string: str) -> typing.Any:
Parameters
----------
- handle_string : :obj:`~str`
+ handle_string : str
The handle to the object to refer to. This is in the format
- ``fully.qualified.module.name#object.attribute``. If no ``#`` is
+ `fully.qualified.module.name#object.attribute`. If no `#` is
input, then the reference will be made to the module itself.
Returns
-------
- :obj:`~typing.Any`
+ typing.Any
The thing that is referred to from this reference.
Examples
--------
- ``"collections#deque"``:
- Refers to :obj:`~collections.deque`
- ``"asyncio.tasks#Task"``:
- Refers to ``asyncio.tasks.Task``
- ``"hikari.net"``:
- Refers to :obj:`~hikari.net`
- ``"foo.bar#baz.bork.qux"``:
- Would refer to a theoretical ``qux`` attribute on a ``bork``
- attribute on a ``baz`` object in the ``foo.bar`` module.
+ * `"collections#deque"`:
+
+ Refers to `collections.deque`
+
+ * `"asyncio.tasks#Task"`:
+
+ Refers to `asyncio.tasks.Task`
+
+ * `"hikari.net"`:
+
+ Refers to `hikari.net`
+
+ * `"foo.bar#baz.bork.qux"`:
+
+ Would refer to a theoretical `qux` attribute on a `bork`
+ attribute on a `baz` object in the `foo.bar` module.
"""
if "#" not in handle_string:
module, attribute_names = handle_string, ()
@@ -112,42 +116,38 @@ def attrib(
serializer: typing.Optional[typing.Callable[[typing.Any], typing.Any]] = None,
**kwargs,
) -> attr.Attribute:
- """Create an :func:`attr.ib` with marshaller metadata attached.
+ """Create an `attr.ib` with marshaller metadata attached.
Parameters
----------
- deserializer : :obj:`~typing.Callable` [ [ :obj:`~typing.Any` ], :obj:`~typing.Any` ], optional
+ deserializer : typing.Callable [ [ typing.Any ], typing.Any ], optional
The deserializer to use to deserialize raw elements.
- raw_name : :obj:`~str`, optional
+ raw_name : str, optional
The raw name of the element in its raw serialized form. If not provided,
then this will use the field's default name later.
- transient : :obj:`~bool`
- If :obj:`~True`, the field is marked as transient, meaning it will not be
- serialized. Defaults to :obj:`~False`.
+ transient : bool
+ If `True`, the field is marked as transient, meaning it will not be
+ serialized. Defaults to `False`.
if_none
Either a default factory function called to get the default for when
- this field is :obj:`~None` or one of :obj:`~None`, :obj:`~False` or
- :obj:`~True` to specify that this should default to the given singleton.
- Will raise an exception when :obj:`~None` is received for this field
- later if this isn't specified.
+ this field is `None` or one of `None`, `False` or `True` to specify that
+ this should default to the given singleton. Will raise an exception when
+ `None` is received for this field later if this isn't specified.
if_undefined
Either a default factory function called to get the default for when
- this field isn't defined or one of :obj:`~None`, :obj:`~False` or
- :obj:`~True` to specify that this should default to the given singleton.
- Will raise an exception when this field is undefined later on if this
- isn't specified.
- serializer : :obj:`~typing.Callable` [ [ :obj:`~typing.Any` ], :obj:`~typing.Any` ], optional
+ this field isn't defined or one of `None`, `False` or `True` to specify
+ that this should default to the given singleton. Will raise an exception
+ when this field is undefined later on if this isn't specified.
+ serializer : typing.Callable [ [ typing.Any ], typing.Any ], optional
The serializer to use. If not specified, then serializing the entire
- class that this attribute is in will trigger a :obj:`~TypeError`
- later.
+ class that this attribute is in will trigger a `TypeError` later.
**kwargs :
- Any kwargs to pass to :func:`attr.ib`.
+ Any kwargs to pass to `attr.ib`.
Returns
-------
- :obj:`~typing.Any`
- The result of :func:`attr.ib` internally being called with additional
- metadata.
+ typing.Any
+ The result of `attr.ib` internally being called with additional metadata.
"""
# Sphinx decides to be really awkward and inject the wrong default values
# by default. Not helpful when it documents non-optional shit as defaulting
@@ -267,9 +267,8 @@ class HikariEntityMarshaller:
"""Hikari's utility to manage automated serialization and deserialization.
It can deserialize and serialize any internal components that that are
- decorated with the :obj:`~marshallable` decorator, and that are
- :func:`attr.s` classes using fields with the :obj:`~attrib` function call
- descriptor.
+ decorated with the `marshallable` decorator, and that are
+ `attr.s` classes using fields with the`attrib` function call descriptor.
"""
__slots__ = ("_registered_entities",)
@@ -282,19 +281,19 @@ def register(self, cls: typing.Type[EntityT]) -> typing.Type[EntityT]:
Parameters
----------
- cls : :obj:`~typing.Type` [ :obj:`~typing.Any` ]
+ cls : typing.Type [ typing.Any ]
The type to register.
Returns
-------
- :obj:`~typing.Type` [ :obj:`~typing.Any` ]
+ typing.Type [ typing.Any ]
The input argument. This enables this to be used as a decorator if
desired.
Raises
------
- :obj:`~TypeError`
- If the class is not an :obj:`~attr.s` class.
+ TypeError
+ If the class is not an `attr.s` class.
"""
entity_descriptor = _construct_entity_descriptor(cls)
self._registered_entities[cls] = entity_descriptor
@@ -305,24 +304,24 @@ def deserialize(self, raw_data: more_typing.JSONObject, target_type: typing.Type
Parameters
----------
- raw_data : :obj:`~typing.Mapping` [ :obj:`~str`, :obj:`~typing.Any` ]
+ raw_data : typing.Mapping [ str, typing.Any ]
The raw data to deserialize.
- target_type : :obj:`~typing.Type` [ :obj:`~typing.Any` ]
+ target_type : typing.Type [ typing.Any ]
The type to deserialize to.
Returns
-------
- :obj:`~typing.Any`
+ typing.Any
The deserialized instance.
Raises
------
- :obj:`~LookupError`
+ LookupError
If the entity is not registered.
- :obj:`~AttributeError`
+ AttributeError
If the field is not optional, but the field was not present in the
- raw payload, or it was present, but it was assigned :obj:`~None`.
- :obj:`~TypeError`
+ raw payload, or it was present, but it was assigned `None`.
+ TypeError
If the deserialization call failed for some reason.
"""
try:
@@ -378,17 +377,17 @@ def serialize(self, obj: typing.Optional[typing.Any]) -> more_typing.NullableJSO
Parameters
----------
- obj : :obj:`~typing.Any`, optional
+ obj : typing.Any, optional
The entity to serialize.
Returns
-------
- :obj:`~typing.Mapping` [ :obj:`~str`, :obj:`~typing.Any` ], optional
+ typing.Mapping [ str, typing.Any ], optional
The serialized raw data item.
Raises
------
- :obj:`~LookupError`
+ LookupError
If the entity is not registered.
"""
if obj is None:
@@ -417,11 +416,11 @@ def serialize(self, obj: typing.Optional[typing.Any]) -> more_typing.NullableJSO
def marshallable(*, marshaller: HikariEntityMarshaller = HIKARI_ENTITY_MARSHALLER):
- """Create a decorator for a class to make it into an :obj:`~attr.s` class.
+ """Create a decorator for a class to make it into an `attr.s` class.
Parameters
----------
- marshaller : :obj:`~HikariEntityMarshaller`
+ marshaller : HikariEntityMarshaller
If specified, this should be an instance of a marshaller to use. For
most internal purposes, you want to not specify this, since it will
then default to the hikari-global marshaller instead. This is
@@ -429,25 +428,20 @@ def marshallable(*, marshaller: HikariEntityMarshaller = HIKARI_ENTITY_MARSHALLE
Returns
-------
- ``decorator(T) -> T``
+ `decorator(T) -> T`
A decorator to decorate a class with.
- Notes
- -----
- The ``auto_attribs`` functionality provided by :obj:`~attr.s` is not
- supported by this marshaller utility. Do not attempt to use it!
-
- Example
- -------
-
- .. code-block:: python
+ !!! note
+ The `auto_attribs` functionality provided by `attr.s` is not
+ supported by this marshaller utility. Do not attempt to use it!
+ Examples
+ --------
@attrs()
class MyEntity:
id: int = attrib(deserializer=int, serializer=str)
password: str = attrib(deserializer=int, transient=True)
...
-
"""
def decorator(cls):
diff --git a/hikari/internal/meta.py b/hikari/internal/meta.py
index a5027e7b0d..1c9690b366 100644
--- a/hikari/internal/meta.py
+++ b/hikari/internal/meta.py
@@ -16,10 +16,7 @@
#
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
-"""Various functional types and metatypes.
-
-|internal|
-"""
+"""Various functional types and metatypes."""
__all__ = ["SingletonMeta", "Singleton"]
import abc
@@ -35,25 +32,21 @@ class SingletonMeta(type):
Once an instance has been defined at runtime, it will exist until the
interpreter that created it is terminated.
- Example
- -------
- .. code-block:: python
-
+ Examples
+ --------
>>> class Unknown(metaclass=SingletonMeta):
... def __init__(self):
... print("Initialized an Unknown!")
>>> Unknown() is Unknown() # True
- Note
- ----
- The constructors of instances of this metaclass must not take any arguments
- other than ``self``.
+ !!! note
+ The constructors of instances of this metaclass must not take any
+ arguments other than `self`.
- Warning
- -------
- Constructing instances of class instances of this metaclass may not be
- thread safe.
+ !!! warning
+ Constructing instances of class instances of this metaclass may not be
+ thread safe.
"""
# pylint: disable=E1136
@@ -69,29 +62,25 @@ def __call__(cls):
class Singleton(metaclass=SingletonMeta):
- """Base type for anything implementing the :obj:`~SingletonMeta` metaclass.
+ """Base type for anything implementing the `SingletonMeta` metaclass.
Once an instance has been defined at runtime, it will exist until the
interpreter that created it is terminated.
- Example
- -------
- .. code-block:: python
-
+ Examples
+ --------
>>> class MySingleton(Singleton):
... pass
>>> assert MySingleton() is MySingleton()
- Note
- ----
- The constructors of child classes must not take any arguments other than
- ``self``.
+ !!! note
+ The constructors of child classes must not take any arguments other than
+ `self`.
- Warning
- -------
- Constructing instances of this class or derived classes may not be thread
- safe.
+ !!! warning
+ Constructing instances of this class or derived classes may not be
+ thread safe.
"""
@@ -102,10 +91,9 @@ class UniqueFunctionMeta(abc.ABCMeta):
mixins provide the same function, a type error is raised when the class is
defined.
- Note
- ----
- This metaclass derives from :obj:`~abc.ABCMeta`, and thus is compatible
- with abstract method conduit.
+ !!! note
+ This metaclass derives from `abc.ABCMeta`, and thus is compatible with
+ abstract method conduit.
"""
@classmethod
diff --git a/hikari/internal/more_asyncio.py b/hikari/internal/more_asyncio.py
index 4bd02e05dc..d8ca5b3871 100644
--- a/hikari/internal/more_asyncio.py
+++ b/hikari/internal/more_asyncio.py
@@ -16,13 +16,10 @@
#
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
-"""Asyncio extensions and utilities.
-
-|internal|
-"""
+"""Asyncio extensions and utilities."""
from __future__ import annotations
-__all__ = ["completed_future"]
+__all__ = ["completed_future", "wait"]
import asyncio
import typing
@@ -45,12 +42,12 @@ def completed_future(result=None, /):
Parameters
----------
- result : :obj:`~typing.Any`
+ result : typing.Any
The value to set for the result of the future.
Returns
-------
- :obj:`~asyncio.Future`
+ asyncio.Future
The completed future.
"""
future = asyncio.get_event_loop().create_future()
@@ -67,8 +64,8 @@ def wait(
Returns
-------
- :obj:`~typing.Tuple` with two :obj:`~typing.Set` of futures.
- The coroutine returned by :obj:`~asyncio.wait` of two sets of
+ `typing.Tuple with two typing.Set of futures`
+ The coroutine returned by `asyncio.wait` of two sets of
Tasks/Futures (done, pending).
"""
# noinspection PyTypeChecker
diff --git a/hikari/internal/more_collections.py b/hikari/internal/more_collections.py
index ea1263de09..cad8cea367 100644
--- a/hikari/internal/more_collections.py
+++ b/hikari/internal/more_collections.py
@@ -16,10 +16,7 @@
#
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
-"""Special data structures and utilities.
-
-|internal|
-"""
+"""Special data structures and utilities."""
__all__ = [
"EMPTY_SEQUENCE",
@@ -49,18 +46,15 @@
class WeakKeyDictionary(typing.Generic[_K, _V], weakref.WeakKeyDictionary, typing.MutableMapping[_K, _V]):
"""A dictionary that has weak references to the keys.
- This is a type-safe version of :obj:`~weakref.WeakKeyDictionary` which
- is subscriptable.
-
- Example
- -------
- .. code-block:: python
+ This is a type-safe version of `weakref.WeakKeyDictionary` which is
+ subscriptable.
+ Examples
+ --------
@attr.s(auto_attribs=True)
class Commands:
instances: Set[Command]
aliases: WeakKeyDictionary[Command, str]
-
"""
__slots__ = ()
diff --git a/hikari/internal/more_enums.py b/hikari/internal/more_enums.py
index 84eadf9406..2b3206cb75 100644
--- a/hikari/internal/more_enums.py
+++ b/hikari/internal/more_enums.py
@@ -25,17 +25,15 @@
class EnumMixin:
"""Mixin for a non-flag enum type.
- This gives a more meaningful ``__str__`` implementation.
+ This gives a more meaningful `__str__` implementation.
- The class should inherit this mixin before any type defined in :mod:`~enum`.
+ The class should inherit this mixin before any type defined in `enum`.
"""
__slots__ = ()
- #: The name of the enum member.
- #:
- #: :obj:`~str`
name: str
+ """The name of the enum member."""
def __str__(self) -> str:
return self.name
@@ -44,17 +42,15 @@ def __str__(self) -> str:
class FlagMixin:
"""Mixin for a flag enum type.
- This gives a more meaningful ``__str__`` implementation.
+ This gives a more meaningful `__str__` implementation.
- The class should inherit this mixin before any type defined in :mod:`~enum`.
+ The class should inherit this mixin before any type defined in `enum`.
"""
__slots__ = ()
- #: The name of the enum member.
- #:
- #: :obj:`~str`
name: str
+ """The name of the enum member."""
def __str__(self) -> str:
return ", ".join(flag.name for flag in typing.cast(typing.Iterable, type(self)) if flag & self)
diff --git a/hikari/internal/more_typing.py b/hikari/internal/more_typing.py
index f5790d3ac8..a37b1223d0 100644
--- a/hikari/internal/more_typing.py
+++ b/hikari/internal/more_typing.py
@@ -20,8 +20,18 @@
# pylint:disable=unused-variable
from __future__ import annotations
-# Don't export anything.
-__all__ = []
+__all__ = [
+ "JSONType",
+ "NullableJSONArray",
+ "JSONObject",
+ "NullableJSONObject",
+ "JSONArray",
+ "NullableJSONType",
+ "Headers",
+ "Coroutine",
+ "Future",
+ "Task",
+]
import asyncio
import contextvars
@@ -50,78 +60,78 @@
# HTTP TYPE HINT HELPERS #
##########################
-#: Any JSON type.
JSONType = _Union[
_Mapping[str, "NullableJSONType"], _Sequence["NullableJSONType"], _AnyStr, int, float, bool,
]
+"""Any JSON type."""
-#: Any JSON type, including ``null``.
NullableJSONType = _Optional[JSONType]
+"""Any JSON type, including `null`."""
-#: A mapping produced from a JSON object.
JSONObject = _Mapping[str, NullableJSONType]
+"""A mapping produced from a JSON object."""
-#: A mapping produced from a JSON object that may or may not be present.
NullableJSONObject = _Optional[JSONObject]
+"""A mapping produced from a JSON object that may or may not be present."""
-#: A sequence produced from a JSON array.
JSONArray = _Sequence[NullableJSONType]
+"""A sequence produced from a JSON array."""
-#: A sequence produced from a JSON array that may or may not be present.
NullableJSONArray = _Optional[JSONArray]
+"""A sequence produced from a JSON array that may or may not be present."""
-#: HTTP headers.
Headers = _Mapping[str, _Union[_Sequence[str], str]]
+"""HTTP headers."""
#############################
# ASYNCIO TYPE HINT HELPERS #
#############################
-#: A coroutine object.
-#:
-#: This is awaitable but MUST be awaited somewhere to be
-#: completed correctly.
Coroutine = _Coroutine[_Any, _Any, T_co]
+"""A coroutine object.
+
+This is awaitable but MUST be awaited somewhere to be completed correctly.
+"""
@_runtime_checkable
class Future(_Protocol[T_contra]):
- """Typed protocol representation of an :obj:`~asyncio.Future`.
+ """Typed protocol representation of an `asyncio.Future`.
- You should consult the documentation for :obj:`~asyncio.Future` for usage.
+ You should consult the documentation for `asyncio.Future` for usage.
"""
def result(self) -> T_contra:
- """See :meth:`asyncio.Future.result`."""
+ """See `asyncio.Future.result`."""
def set_result(self, result: T_contra, /) -> None:
- """See :meth:`asyncio.Future.set_result`."""
+ """See `asyncio.Future.set_result`."""
def set_exception(self, exception: Exception, /) -> None:
- """See :meth:`asyncio.Future.set_exception`."""
+ """See `asyncio.Future.set_exception`."""
def done(self) -> bool:
- """See :meth:`asyncio.Future.done`."""
+ """See `asyncio.Future.done`."""
def cancelled(self) -> bool:
- """See :meth:`asyncio.Future.cancelled`."""
+ """See `asyncio.Future.cancelled`."""
def add_done_callback(
self, callback: _Callable[[Future[T_contra]], None], /, *, context: _Optional[contextvars.Context],
) -> None:
- """See :meth:`asyncio.Future.add_done_callback`."""
+ """See `asyncio.Future.add_done_callback`."""
def remove_done_callback(self, callback: _Callable[[Future[T_contra]], None], /) -> None:
- """See :meth:`asyncio.Future.remove_done_callback`."""
+ """See `asyncio.Future.remove_done_callback`."""
def cancel(self) -> bool:
- """See :meth:`asyncio.Future.cancel`."""
+ """See `asyncio.Future.cancel`."""
def exception(self) -> _Optional[Exception]:
- """See :meth:`asyncio.Future.exception`."""
+ """See `asyncio.Future.exception`."""
def get_loop(self) -> asyncio.AbstractEventLoop:
- """See :meth:`asyncio.Future.get_loop`."""
+ """See `asyncio.Future.get_loop`."""
def __await__(self) -> Coroutine[T_contra]:
...
@@ -129,54 +139,54 @@ def __await__(self) -> Coroutine[T_contra]:
@_runtime_checkable
class Task(_Protocol[T_contra]):
- """Typed protocol representation of an :obj:`~asyncio.Task`.
+ """Typed protocol representation of an `asyncio.Task`.
- You should consult the documentation for :obj:`~asyncio.Task` for usage.
+ You should consult the documentation for `asyncio.Task` for usage.
"""
def result(self) -> T_contra:
- """See :meth:`asyncio.Future.result`."""
+ """See`asyncio.Future.result`."""
def set_result(self, result: T_contra, /) -> None:
- """See :meth:`asyncio.Future.set_result`."""
+ """See `asyncio.Future.set_result`."""
def set_exception(self, exception: Exception, /) -> None:
- """See :meth:`asyncio.Future.set_exception`."""
+ """See `asyncio.Future.set_exception`."""
def done(self) -> bool:
- """See :meth:`asyncio.Future.done`."""
+ """See `asyncio.Future.done`."""
def cancelled(self) -> bool:
- """See :meth:`asyncio.Future.cancelled`."""
+ """See `asyncio.Future.cancelled`."""
def add_done_callback(
self, callback: _Callable[[Future[T_contra]], None], /, *, context: _Optional[contextvars.Context],
) -> None:
- """See :meth:`asyncio.Future.add_done_callback`."""
+ """See `asyncio.Future.add_done_callback`."""
def remove_done_callback(self, callback: _Callable[[Future[T_contra]], None], /) -> None:
- """See :meth:`asyncio.Future.remove_done_callback`."""
+ """See `asyncio.Future.remove_done_callback`."""
def cancel(self) -> bool:
- """See :meth:`asyncio.Future.cancel`."""
+ """See `asyncio.Future.cancel`."""
def exception(self) -> _Optional[Exception]:
- """See :meth:`asyncio.Future.exception`."""
+ """See `asyncio.Future.exception`."""
def get_loop(self) -> asyncio.AbstractEventLoop:
- """See :meth:`asyncio.Future.get_loop`."""
+ """See `asyncio.Future.get_loop`."""
def get_stack(self, *, limit: _Optional[int] = None) -> _Sequence[_FrameType]:
- """See :meth:`asyncio.Task.get_stack`."""
+ """See `asyncio.Task.get_stack`."""
def print_stack(self, *, limit: _Optional[int] = None, file: _Optional[_IO] = None) -> None:
- """See :meth:`asyncio.Task.print_stack`."""
+ """See `asyncio.Task.print_stack`."""
def get_name(self) -> str:
- """See :meth:`asyncio.Task.get_name`."""
+ """See `asyncio.Task.get_name`."""
def set_name(self, value: str, /) -> None:
- """See :meth:`asyncio.Task.set_name`."""
+ """See `asyncio.Task.set_name`."""
def __await__(self) -> Coroutine[T_contra]:
...
diff --git a/hikari/internal/urls.py b/hikari/internal/urls.py
index f5ba2d37de..9a78accf0f 100644
--- a/hikari/internal/urls.py
+++ b/hikari/internal/urls.py
@@ -16,10 +16,7 @@
#
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
-"""Discord-specific URIs that have to be hard-coded.
-
-|internal|
-"""
+"""Discord-specific URIs that have to be hard-coded."""
__all__ = [
"generate_cdn_url",
@@ -30,16 +27,13 @@
from hikari.internal import assertions
-#: The URL for the CDN.
-#:
-#: :type: :obj:`~str`
BASE_CDN_URL: typing.Final[str] = "https://cdn.discordapp.com"
+"""The URL for the CDN."""
-#: The URL for the REST API. This contains a version number parameter that
-#: should be interpolated.
-#:
-#: :type: :obj:`~str`
REST_API_URL: typing.Final[str] = "https://discordapp.com/api/v{0.version}"
+"""The URL for the REST API. This contains a version number parameter that
+should be interpolated.
+"""
def generate_cdn_url(*route_parts: str, fmt: str, size: typing.Optional[int]) -> str:
@@ -47,26 +41,26 @@ def generate_cdn_url(*route_parts: str, fmt: str, size: typing.Optional[int]) ->
Parameters
----------
- route_parts : :obj:`~str`
+ route_parts : str
The string route parts that will be used to form the link.
- fmt : :obj:`~str`
+ fmt : str
The format to use for the wanted cdn entity, will usually be one of
- ``webp``, ``png``, ``jpeg``, ``jpg`` or ``gif`` (which will be invalid
+ `webp`, `png`, `jpeg`, `jpg` or `gif` (which will be invalid
if the target entity doesn't have an animated version available).
- size : :obj:`~int`, optional
+ size : int, optional
The size to specify for the image in the query string if applicable,
- should be passed through as :obj:`~None` to avoid the param being set.
+ should be passed through as None to avoid the param being set.
Must be any power of two between 16 and 4096.
Returns
-------
- :obj:`~str`
+ str
The URL to the resource on the Discord CDN.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if size:
assertions.assert_in_range(size, 16, 4096)
diff --git a/hikari/invites.py b/hikari/invites.py
index 7478ed5c11..3fab4abe1c 100644
--- a/hikari/invites.py
+++ b/hikari/invites.py
@@ -38,8 +38,8 @@
class TargetUserType(enum.IntEnum):
"""The reason a invite targets a user."""
- #: This invite is targeting a "Go Live" stream.
STREAM = 1
+ """This invite is targeting a "Go Live" stream."""
@marshaller.marshallable()
@@ -47,15 +47,11 @@ class TargetUserType(enum.IntEnum):
class VanityUrl(bases.HikariEntity, marshaller.Deserializable):
"""A special case invite object, that represents a guild's vanity url."""
- #: The code for this invite.
- #:
- #: :type: :obj:`~str`
code: str = marshaller.attrib(deserializer=str)
+ """The code for this invite."""
- #: The amount of times this invite has been used.
- #:
- #: :type: :obj:`~int`
uses: int = marshaller.attrib(deserializer=int)
+ """The amount of times this invite has been used."""
@marshaller.marshallable()
@@ -63,64 +59,54 @@ class VanityUrl(bases.HikariEntity, marshaller.Deserializable):
class InviteGuild(guilds.PartialGuild):
"""Represents the partial data of a guild that'll be attached to invites."""
- #: The hash of the splash for the guild, if there is one.
- #:
- #: :type: :obj:`~str`, optional
splash_hash: typing.Optional[str] = marshaller.attrib(raw_name="splash", deserializer=str, if_none=None)
+ """The hash of the splash for the guild, if there is one."""
- #: The hash for the guild's banner.
- #:
- #: This is only present if :obj:`~hikari.guilds.GuildFeature.BANNER`
- #: is in the ``features`` for this guild. For all other purposes, it is
- #: :obj:`~None`.
- #:
- #: :type: :obj:`~str`, optional
banner_hash: typing.Optional[str] = marshaller.attrib(raw_name="banner", if_none=None, deserializer=str)
+ """The hash for the guild's banner.
+
+ This is only present if `hikari.guilds.GuildFeature.BANNER` is in the
+ `features` for this guild. For all other purposes, it is `None`.
+ """
- #: The guild's description.
- #:
- #: This is only present if certain ``features`` are set in this guild.
- #: Otherwise, this will always be :obj:`~None`. For all other purposes, it is
- #: :obj:`~None`.
- #:
- #: :type: :obj:`~str`, optional
description: typing.Optional[str] = marshaller.attrib(if_none=None, deserializer=str)
+ """The guild's description.
+
+ This is only present if certain `features` are set in this guild.
+ Otherwise, this will always be `None`. For all other purposes, it is `None`.
+ """
- #: The verification level required for a user to participate in this guild.
- #:
- #: :type: :obj:`~hikari.guilds.GuildVerificationLevel`
verification_level: guilds.GuildVerificationLevel = marshaller.attrib(deserializer=guilds.GuildVerificationLevel)
+ """The verification level required for a user to participate in this guild."""
- #: The vanity URL code for the guild's vanity URL.
- #:
- #: This is only present if :obj:`~hikari.guilds.GuildFeature.VANITY_URL`
- #: is in the ``features`` for this guild. If not, this will always be
- #: :obj:`~None`.
- #:
- #: :type: :obj:`~str`, optional
vanity_url_code: typing.Optional[str] = marshaller.attrib(if_none=None, deserializer=str)
+ """The vanity URL code for the guild's vanity URL.
+
+ This is only present if `hikari.guilds.GuildFeature.VANITY_URL` is in the
+ `features` for this guild. If not, this will always be `None`.
+ """
def format_splash_url(self, fmt: str = "png", size: int = 4096) -> typing.Optional[str]:
"""Generate the URL for this guild's splash, if set.
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png``.
- Supports ``png``, ``jpeg``, ``jpg` and ``webp``.
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``.
+ fmt : str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : int
+ The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
- :obj:`~str`, optional
+ str, optional
The string URL.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if self.splash_hash:
return urls.generate_cdn_url("splashes", str(self.id), self.splash_hash, fmt=fmt, size=size)
@@ -136,22 +122,22 @@ def format_banner_url(self, fmt: str = "png", size: int = 4096) -> typing.Option
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png``.
- Supports ``png``, ``jpeg``, ``jpg`` and ``webp``.
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``.
+ fmt : str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : int
+ The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
- :obj:`~str`, optional
+ str, optional
The string URL.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if self.banner_hash:
return urls.generate_cdn_url("banners", str(self.id), self.banner_hash, fmt=fmt, size=size)
@@ -168,104 +154,91 @@ def banner_url(self) -> typing.Optional[str]:
class Invite(bases.HikariEntity, marshaller.Deserializable):
"""Represents an invite that's used to add users to a guild or group dm."""
- #: The code for this invite.
- #:
- #: :type: :obj:`~str`
code: str = marshaller.attrib(deserializer=str)
+ """The code for this invite."""
- #: The partial object of the guild this dm belongs to.
- #: Will be :obj:`~None` for group dm invites.
- #:
- #: :type: :obj:`~InviteGuild`, optional
guild: typing.Optional[InviteGuild] = marshaller.attrib(
deserializer=InviteGuild.deserialize, if_undefined=None, default=None
)
- #: The partial object of the channel this invite targets.
- #:
- #: :type: :obj:`~hikari.channels.PartialChannel`
+ """The partial object of the guild this dm belongs to.
+
+ Will be `None` for group dm invites.
+ """
+
channel: channels.PartialChannel = marshaller.attrib(deserializer=channels.PartialChannel.deserialize)
+ """The partial object of the channel this invite targets."""
- #: The object of the user who created this invite.
- #:
- #: :type: :obj:`~hikari.users.User`, optional
inviter: typing.Optional[users.User] = marshaller.attrib(
deserializer=users.User.deserialize, if_undefined=None, default=None
)
+ """The object of the user who created this invite."""
- #: The object of the user who this invite targets, if set.
- #:
- #: :type: :obj:`~hikari.users.User`, optional
target_user: typing.Optional[users.User] = marshaller.attrib(
deserializer=users.User.deserialize, if_undefined=None, default=None
)
+ """The object of the user who this invite targets, if set."""
- #: The type of user target this invite is, if applicable.
- #:
- #: :type: :obj:`~TargetUserType`, optional
target_user_type: typing.Optional[TargetUserType] = marshaller.attrib(
deserializer=TargetUserType, if_undefined=None, default=None
)
+ """The type of user target this invite is, if applicable."""
- #: The approximate amount of presences in this invite's guild, only present
- #: when ``with_counts`` is passed as :obj:`~True` to the GET Invites endpoint.
- #:
- #: :type: :obj:`~int`, optional
approximate_presence_count: typing.Optional[int] = marshaller.attrib(
deserializer=int, if_undefined=None, default=None
)
+ """The approximate amount of presences in this invite's guild.
+
+ This is only present when `with_counts` is passed as `True` to the GET
+ Invites endpoint.
+ """
- #: The approximate amount of members in this invite's guild, only present
- #: when ``with_counts`` is passed as :obj:`~True` to the GET Invites endpoint.
- #:
- #: :type: :obj:`~int`, optional
approximate_member_count: typing.Optional[int] = marshaller.attrib(
deserializer=int, if_undefined=None, default=None
)
+ """The approximate amount of members in this invite's guild, only present
+
+ This is only present when `with_counts` is passed as `True` to the GET
+ Invites endpoint.
+ """
@marshaller.marshallable()
@attr.s(slots=True, kw_only=True)
class InviteWithMetadata(Invite):
- """Extends the base :obj:`~Invite` object with metadata.
+ """Extends the base `Invite` object with metadata.
The metadata is only returned when getting an invite with
guild permissions, rather than it's code.
"""
- #: The amount of times this invite has been used.
- #:
- #: :type: :obj:`~int`
uses: int = marshaller.attrib(deserializer=int)
+ """The amount of times this invite has been used."""
- #: The limit for how many times this invite can be used before it expires.
- #: If set to ``0`` then this is unlimited.
- #:
- #: :type: :obj:`~int`
max_uses: int = marshaller.attrib(deserializer=int)
+ """The limit for how many times this invite can be used before it expires.
+
+ If set to `0` then this is unlimited.
+ """
- #: The timedelta of how long this invite will be valid for.
- #: If set to :obj:`~None` then this is unlimited.
- #:
- #: :type: :obj:`~datetime.timedelta`, optional
max_age: typing.Optional[datetime.timedelta] = marshaller.attrib(
deserializer=lambda age: datetime.timedelta(seconds=age) if age > 0 else None
)
+ """The timedelta of how long this invite will be valid for.
+
+ If set to `None` then this is unlimited.
+ """
- #: Whether this invite grants temporary membership.
- #:
- #: :type: :obj:`~bool`
is_temporary: bool = marshaller.attrib(raw_name="temporary", deserializer=bool)
+ """Whether this invite grants temporary membership."""
- #: When this invite was created.
- #:
- #: :type: :obj:`~datetime.datetime`
created_at: datetime.datetime = marshaller.attrib(deserializer=conversions.parse_iso_8601_ts)
+ """When this invite was created."""
@property
def expires_at(self) -> typing.Optional[datetime.datetime]:
- """When this invite should expire, if ``max_age`` is set.
+ """When this invite should expire, if `InviteWithMetadata.max_age` is set.
- If this invite doesn't have a set expiry then this will be :obj:`~None`.
+ If this invite doesn't have a set expiry then this will be `None`.
"""
if self.max_age:
return self.created_at + self.max_age
diff --git a/hikari/media.py b/hikari/media.py
index 6dceecb966..a6b60baca6 100644
--- a/hikari/media.py
+++ b/hikari/media.py
@@ -43,5 +43,5 @@
async def safe_read_file(file: IO) -> typing.Tuple[str, conversions.FileLikeT]:
- """Safely read an ``IO`` like object."""
+ """Safely read an `IO` like object."""
raise NotImplementedError # TODO: Nekokatt: update this.
diff --git a/hikari/messages.py b/hikari/messages.py
index f3911b5a7b..ec0573cade 100644
--- a/hikari/messages.py
+++ b/hikari/messages.py
@@ -48,67 +48,67 @@
class MessageType(enum.IntEnum):
"""The type of a message."""
- #: A normal message.
DEFAULT = 0
+ """A normal message."""
- #: A message to denote a new recipient in a group.
RECIPIENT_ADD = 1
+ """A message to denote a new recipient in a group."""
- #: A message to denote that a recipient left the group.
RECIPIENT_REMOVE = 2
+ """A message to denote that a recipient left the group."""
- #: A message to denote a VoIP call.
CALL = 3
+ """A message to denote a VoIP call."""
- #: A message to denote that the name of a channel changed.
CHANNEL_NAME_CHANGE = 4
+ """A message to denote that the name of a channel changed."""
- #: A message to denote that the icon of a channel changed.
CHANNEL_ICON_CHANGE = 5
+ """A message to denote that the icon of a channel changed."""
- #: A message to denote that a message was pinned.
CHANNEL_PINNED_MESSAGE = 6
+ """A message to denote that a message was pinned."""
- #: A message to denote that a member joined the guild.
GUILD_MEMBER_JOIN = 7
+ """A message to denote that a member joined the guild."""
- #: A message to denote a Nitro subscription.
USER_PREMIUM_GUILD_SUBSCRIPTION = 8
+ """A message to denote a Nitro subscription."""
- #: A message to denote a tier 1 Nitro subscription.
USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_1 = 9
+ """A message to denote a tier 1 Nitro subscription."""
- #: A message to denote a tier 2 Nitro subscription.
USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_2 = 10
+ """A message to denote a tier 2 Nitro subscription."""
- #: A message to denote a tier 3 Nitro subscription.
USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_3 = 11
+ """A message to denote a tier 3 Nitro subscription."""
- #: Channel follow add.
CHANNEL_FOLLOW_ADD = 12
+ """Channel follow add."""
@enum.unique
class MessageFlag(enum.IntFlag):
"""Additional flags for message options."""
- #: None
NONE = 0
+ """None"""
- #: This message has been published to subscribed channels via channel following.
CROSSPOSTED = 1 << 0
+ """This message has been published to subscribed channels via channel following."""
- #: This message originated from a message in another channel via channel following.
IS_CROSSPOST = 1 << 1
+ """This message originated from a message in another channel via channel following."""
- #: Any embeds on this message should be omitted when serializing the message.
SUPPRESS_EMBEDS = 1 << 2
+ """Any embeds on this message should be omitted when serializing the message."""
- #: The message this crosspost originated from was deleted via channel following.
SOURCE_MESSAGE_DELETED = 1 << 3
+ """The message this crosspost originated from was deleted via channel following."""
- #: This message came from the urgent message system.
URGENT = 1 << 4
+ """This message came from the urgent message system."""
@enum.unique
@@ -116,18 +116,19 @@ class MessageActivityType(enum.IntEnum):
"""The type of a rich presence message activity."""
NONE = 0
+ """No activity."""
- #: Join an activity.
JOIN = 1
+ """Join an activity."""
- #: Spectating something.
SPECTATE = 2
+ """Spectating something."""
- #: Listening to something.
LISTEN = 3
+ """Listening to something."""
- #: Request to join an activity.
JOIN_REQUEST = 5
+ """Request to join an activity."""
@marshaller.marshallable()
@@ -135,35 +136,23 @@ class MessageActivityType(enum.IntEnum):
class Attachment(bases.UniqueEntity, marshaller.Deserializable):
"""Represents a file attached to a message."""
- #: The name of the file.
- #:
- #: :type: :obj:`~str`
filename: str = marshaller.attrib(deserializer=str)
+ """The name of the file."""
- #: The size of the file in bytes.
- #:
- #: :type: :obj:`~int`
size: int = marshaller.attrib(deserializer=int)
+ """The size of the file in bytes."""
- #: The source URL of file.
- #:
- #: :type: :obj:`~str`
url: str = marshaller.attrib(deserializer=str)
+ """The source URL of file."""
- #: The proxied URL of file.
- #:
- #: :type: :obj:`~str`
proxy_url: str = marshaller.attrib(deserializer=str)
+ """The proxied URL of file."""
- #: The height of the image (if the file is an image).
- #:
- #: :type: :obj:`~int`, optional
height: typing.Optional[int] = marshaller.attrib(deserializer=int, if_undefined=None, default=None)
+ """The height of the image (if the file is an image)."""
- #: The width of the image (if the file is an image).
- #:
- #: :type: :obj:`~int`, optional
width: typing.Optional[int] = marshaller.attrib(deserializer=int, if_undefined=None, default=None)
+ """The width of the image (if the file is an image)."""
@marshaller.marshallable()
@@ -171,22 +160,16 @@ class Attachment(bases.UniqueEntity, marshaller.Deserializable):
class Reaction(bases.HikariEntity, marshaller.Deserializable):
"""Represents a reaction in a message."""
- #: The amount of times the emoji has been used to react.
- #:
- #: :type: :obj:`~int`
count: int = marshaller.attrib(deserializer=int)
+ """The amount of times the emoji has been used to react."""
- #: The emoji used to react.
- #:
- #: :type: :obj:`~typing.Union` [ :obj:`~hikari.emojis.UnicodeEmoji`, :obj:`~hikari.emojis.UnknownEmoji`]
emoji: typing.Union[_emojis.UnicodeEmoji, _emojis.UnknownEmoji] = marshaller.attrib(
deserializer=_emojis.deserialize_reaction_emoji
)
+ """The emoji used to react."""
- #: Whether the current user reacted using this emoji.
- #:
- #: :type: :obj:`~bool`
is_reacted_by_me: bool = marshaller.attrib(raw_name="me", deserializer=bool)
+ """Whether the current user reacted using this emoji."""
@marshaller.marshallable()
@@ -194,15 +177,11 @@ class Reaction(bases.HikariEntity, marshaller.Deserializable):
class MessageActivity(bases.HikariEntity, marshaller.Deserializable):
"""Represents the activity of a rich presence-enabled message."""
- #: The type of message activity.
- #:
- #: :type: :obj:`~MessageActivityType`
type: MessageActivityType = marshaller.attrib(deserializer=MessageActivityType)
+ """The type of message activity."""
- #: The party ID of the message activity.
- #:
- #: :type: :obj:`~str`, optional
party_id: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The party ID of the message activity."""
@marshaller.marshallable()
@@ -210,37 +189,30 @@ class MessageActivity(bases.HikariEntity, marshaller.Deserializable):
class MessageCrosspost(bases.HikariEntity, marshaller.Deserializable):
"""Represents information about a cross-posted message and the origin of the original message."""
- #: The ID of the original message.
- #:
- #: Warning
- #: -------
- #: This may be :obj:`~None` in some cases according to the Discord API
- #: documentation, but the situations that cause this to occur are not
- #: currently documented.
- #:
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
message_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the original message.
+
+ !!! warning
+ This may be `None` in some cases according to the Discord API
+ documentation, but the situations that cause this to occur are not
+ currently documented.
+ """
- #: The ID of the channel that the message originated from.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel that the message originated from."""
- #: The ID of the guild that the message originated from.
- #:
- #: Warning
- #: -------
- #: This may be :obj:`~None` in some cases according to the Discord API
- #: documentation, but the situations that cause this to occur are not
- #: currently documented.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild that the message originated from.
+
+ !!! warning
+ This may be `None` in some cases according to the Discord API
+ documentation, but the situations that cause this to occur are not
+ currently documented.
+ """
@marshaller.marshallable()
@@ -248,150 +220,105 @@ class MessageCrosspost(bases.HikariEntity, marshaller.Deserializable):
class Message(bases.UniqueEntity, marshaller.Deserializable):
"""Represents a message."""
- #: The ID of the channel that the message was sent in.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the channel that the message was sent in."""
- #: The ID of the guild that the message was sent in.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild that the message was sent in."""
- #: The author of this message.
- #:
- #: :type: :obj:`~hikari.users.User`
author: users.User = marshaller.attrib(deserializer=users.User.deserialize)
+ """The author of this message."""
- #: The member properties for the message's author.
- #:
- #: :type: :obj:`~hikari.guilds.GuildMember`, optional
member: typing.Optional[guilds.GuildMember] = marshaller.attrib(
deserializer=guilds.GuildMember.deserialize, if_undefined=None, default=None
)
+ """The member properties for the message's author."""
- #: The content of the message.
- #:
- #: :type: :obj:`~str`
content: str = marshaller.attrib(deserializer=str)
+ """The content of the message."""
- #: The timestamp that the message was sent at.
- #:
- #: :type: :obj:`~datetime.datetime`
timestamp: datetime.datetime = marshaller.attrib(deserializer=conversions.parse_iso_8601_ts)
+ """The timestamp that the message was sent at."""
- #: The timestamp that the message was last edited at, or :obj:`~None` if it
- #: wasn't ever edited.
- #:
- #: :type: :obj:`~datetime.datetime`, optional
edited_timestamp: typing.Optional[datetime.datetime] = marshaller.attrib(
deserializer=conversions.parse_iso_8601_ts, if_none=None
)
+ """The timestamp that the message was last edited at.
+
+ Will be `None` if it wasn't ever edited.
+ """
- #: Whether the message is a TTS message.
- #:
- #: :type: :obj:`~bool`
is_tts: bool = marshaller.attrib(raw_name="tts", deserializer=bool)
+ """Whether the message is a TTS message."""
- #: Whether the message mentions ``@everyone`` or ``@here``.
- #:
- #: :type: :obj:`~bool`
is_mentioning_everyone: bool = marshaller.attrib(raw_name="mention_everyone", deserializer=bool)
+ """Whether the message mentions `@everyone` or `@here`."""
- #: The users the message mentions.
- #:
- #: :type: :obj:`~typing.Set` [ :obj:`~hikari.bases.Snowflake` ]
user_mentions: typing.Set[bases.Snowflake] = marshaller.attrib(
raw_name="mentions",
deserializer=lambda user_mentions: {bases.Snowflake.deserialize(u["id"]) for u in user_mentions},
)
+ """The users the message mentions."""
- #: The roles the message mentions.
- #:
- #: :type: :obj:`~typing.Set` [ :obj:`~hikari.bases.Snowflake` ]
role_mentions: typing.Set[bases.Snowflake] = marshaller.attrib(
raw_name="mention_roles",
deserializer=lambda role_mentions: {bases.Snowflake.deserialize(mention) for mention in role_mentions},
)
+ """The roles the message mentions."""
- #: The channels the message mentions.
- #:
- #: :type: :obj:`~typing.Set` [ :obj:`~hikari.bases.Snowflake` ]
channel_mentions: typing.Set[bases.Snowflake] = marshaller.attrib(
raw_name="mention_channels",
deserializer=lambda channel_mentions: {bases.Snowflake.deserialize(c["id"]) for c in channel_mentions},
if_undefined=set,
factory=set,
)
+ """The channels the message mentions."""
- #: The message attachments.
- #:
- #: :type: :obj:`~typing.Sequence` [ :obj:`~Attachment` ]
attachments: typing.Sequence[Attachment] = marshaller.attrib(
deserializer=lambda attachments: [Attachment.deserialize(a) for a in attachments]
)
+ """The message attachments."""
- #: The message embeds.
- #:
- #: :type: :obj:`~typing.Sequence` [ :obj:`~hikari.embeds.Embed` ]
embeds: typing.Sequence[_embeds.Embed] = marshaller.attrib(
deserializer=lambda embeds: [_embeds.Embed.deserialize(e) for e in embeds]
)
+ """The message embeds."""
- #: The message reactions.
- #:
- #: :type: :obj:`~typing.Sequence` [ :obj:`~Reaction` ]
reactions: typing.Sequence[Reaction] = marshaller.attrib(
deserializer=lambda reactions: [Reaction.deserialize(r) for r in reactions], if_undefined=list, factory=list
)
+ """The message reactions."""
- #: Whether the message is pinned.
- #:
- #: :type: :obj:`~bool`
is_pinned: bool = marshaller.attrib(raw_name="pinned", deserializer=bool)
+ """Whether the message is pinned."""
- #: If the message was generated by a webhook, the webhook's id.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
webhook_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """If the message was generated by a webhook, the webhook's id."""
- #: The message type.
- #:
- #: :type: :obj:`~MessageType`
type: MessageType = marshaller.attrib(deserializer=MessageType)
+ """The message type."""
- #: The message activity.
- #:
- #: :type: :obj:`~MessageActivity`, optional
activity: typing.Optional[MessageActivity] = marshaller.attrib(
deserializer=MessageActivity.deserialize, if_undefined=None, default=None
)
+ """The message activity."""
- #: The message application.
- #:
- #: :type: :obj:`~hikari.oauth2.Application`, optional
application: typing.Optional[applications.Application] = marshaller.attrib(
deserializer=applications.Application.deserialize, if_undefined=None, default=None
)
+ """The message application."""
- #: The message crossposted reference data.
- #:
- #: :type: :obj:`~MessageCrosspost`, optional
message_reference: typing.Optional[MessageCrosspost] = marshaller.attrib(
deserializer=MessageCrosspost.deserialize, if_undefined=None, default=None
)
+ """The message crossposted reference data."""
- #: The message flags.
- #:
- #: :type: :obj:`~MessageFlag`, optional
flags: typing.Optional[MessageFlag] = marshaller.attrib(deserializer=MessageFlag, if_undefined=None, default=None)
+ """The message flags."""
- #: The message nonce. This is a string used for validating
- #: a message was sent.
- #:
- #: :type: :obj:`~str`, optional
nonce: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The message nonce. This is a string used for validating a message was sent."""
diff --git a/hikari/net/codes.py b/hikari/net/codes.py
index 655f760c22..35075eeebb 100644
--- a/hikari/net/codes.py
+++ b/hikari/net/codes.py
@@ -30,77 +30,77 @@
class HTTPStatusCode(more_enums.EnumMixin, enum.IntEnum):
"""HTTP response codes expected from RESTful components."""
- #: Continue
CONTINUE = 100
+ """Continue"""
- #: OK
OK = 200
+ """OK"""
- #: Created
CREATED = 201
+ """Created"""
- #: Accepted
ACCEPTED = 202
+ """Accepted"""
- #: No content
NO_CONTENT = 204
+ """No content"""
- #: Moved permanently
MOVED_PERMANENTLY = 301
+ """Moved permanently"""
- #: Bad request
BAD_REQUEST = 400
+ """Bad request"""
- #: Unauthorized
UNAUTHORIZED = 401
+ """Unauthorized"""
- #: Forbidden
FORBIDDEN = 403
+ """Forbidden"""
- #: Not found
NOT_FOUND = 404
+ """Not found"""
- #: Method not allowed
METHOD_NOT_ALLOWED = 405
+ """Method not allowed"""
- #: Not acceptable
NOT_ACCEPTABLE = 406
+ """Not acceptable"""
- #: Proxy authentication required
PROXY_AUTHENTICATION_REQUIRED = 407
+ """Proxy authentication required"""
- #: Request entitiy too large
REQUEST_ENTITY_TOO_LARGE = 413
+ """Request entity too large"""
- #: Request URI too long
REQUEST_URI_TOO_LONG = 414
+ """Request URI too long"""
- #: Unsupported media type
UNSUPPORTED_MEDIA_TYPE = 415
+ """Unsupported media type"""
- #: Im a teapot
IM_A_TEAPOT = 418
+ """The server refused the attempt to brew coffee with a teapot."""
- #: Too many requests
TOO_MANY_REQUESTS = 429
+ """Too many requests"""
- #: Internal server error
INTERNAL_SERVER_ERROR = 500
+ """Internal server error"""
- #: Not implemented
NOT_IMPLEMENTED = 501
+ """Not implemented"""
- #: Bad gateway
BAD_GATEWAY = 502
+ """Bad gateway"""
- #: Service unavailable
SERVICE_UNAVAILABLE = 503
+ """Service unavailable"""
- #: Gateway timeout
GATEWAY_TIMEOUT = 504
+ """Gateway timeout"""
- #: HTTP Version not supported
HTTP_VERSION_NOT_SUPPORTED = 505
+ """HTTP Version not supported"""
def __str__(self) -> str:
name = self.name.replace("_", " ").title() if self is not HTTPStatusCode.IM_A_TEAPOT else "I'm a teapot"
@@ -111,61 +111,71 @@ def __str__(self) -> str:
class GatewayCloseCode(more_enums.EnumMixin, enum.IntEnum):
"""Reasons for closing a gateway connection.
- Note
- ----
- Any codes greater than or equal to ``4000`` are server-side codes. Any codes
- between ``1000`` and ``1999`` inclusive are generally client-side codes.
+ !!! note
+ Any codes greater than or equal to `4000` are server-side codes. Any
+ codes between `1000` and `1999` inclusive are generally client-side codes.
"""
- #: The application running closed.
NORMAL_CLOSURE = 1000
+ """The application running closed."""
- #: Discord is not sure what went wrong. Try reconnecting?
UNKNOWN_ERROR = 4000
+ """Discord is not sure what went wrong. Try reconnecting?"""
- #: You sent an invalid Gateway opcode or an invalid payload for an opcode.
- #: Don't do that!
UNKNOWN_OPCODE = 4001
+ """You sent an invalid Gateway opcode or an invalid payload for an opcode.
+
+ Don't do that!
+ """
- #: You sent an invalid payload to Discord. Don't do that!
DECODE_ERROR = 4002
+ """You sent an invalid payload to Discord. Don't do that!"""
- #: You sent Discord a payload prior to IDENTIFYing.
NOT_AUTHENTICATED = 4003
+ """You sent Discord a payload prior to IDENTIFYing."""
- #: The account token sent with your identify payload is incorrect.
AUTHENTICATION_FAILED = 4004
+ """The account token sent with your identify payload is incorrect."""
- #: You sent more than one identify payload. Don't do that!
ALREADY_AUTHENTICATED = 4005
+ """You sent more than one identify payload. Don't do that!"""
- #: The sequence sent when resuming the session was invalid. Reconnect and
- #: start a new session.
INVALID_SEQ = 4007
+ """The sequence sent when resuming the session was invalid.
+
+ Reconnect and start a new session.
+ """
- #: Woah nelly! You're sending payloads to Discord too quickly. Slow it down!
RATE_LIMITED = 4008
+ """Woah nelly! You're sending payloads to Discord too quickly. Slow it down!"""
- #: Your session timed out. Reconnect and start a new one.
SESSION_TIMEOUT = 4009
+ """Your session timed out. Reconnect and start a new one."""
- #: You sent Discord an invalid shard when IDENTIFYing.
INVALID_SHARD = 4010
+ """You sent Discord an invalid shard when IDENTIFYing."""
- #: The session would have handled too many guilds - you are required to
- #: shard your connection in order to connect.
SHARDING_REQUIRED = 4011
+ """The session would have handled too many guilds.
+
+ You are required to shard your connection in order to connect.
+ """
- #: You sent an invalid version for the gateway.
INVALID_VERSION = 4012
+ """You sent an invalid version for the gateway."""
- #: You sent an invalid intent for a Gateway Intent. You may have incorrectly
- #: calculated the bitwise value.
INVALID_INTENT = 4013
+ """You sent an invalid intent for a Gateway Intent.
+
+ You may have incorrectly calculated the bitwise value.
+ """
- #: You sent a disallowed intent for a Gateway Intent. You may have tried to
- #: specify an intent that you have not enabled or are not whitelisted for.
DISALLOWED_INTENT = 4014
+ """You sent a disallowed intent for a Gateway Intent.
+
+ You may have tried to specify an intent that you have not enabled or are not
+ whitelisted for.
+ """
def __str__(self) -> str:
name = self.name.replace("_", " ").title()
@@ -176,42 +186,44 @@ def __str__(self) -> str:
class GatewayOpcode(more_enums.EnumMixin, enum.IntEnum):
"""Opcodes that the gateway uses internally."""
- #: An event was dispatched.
DISPATCH = 0
+ """An event was dispatched."""
- #: Used for ping checking.
HEARTBEAT = 1
+ """Used for ping checking."""
- #: Used for client handshake.
IDENTIFY = 2
+ """Used for client handshake."""
- #: Used to update the client status.
PRESENCE_UPDATE = 3
+ """Used to update the client status."""
- #: Used to join/move/leave voice channels.
VOICE_STATE_UPDATE = 4
+ """Used to join/move/leave voice channels."""
- #: Used to resume a closed connection.
RESUME = 6
+ """Used to resume a closed connection."""
- #: Used to tell clients to reconnect to the gateway.
RECONNECT = 7
+ """Used to tell clients to reconnect to the gateway."""
- #: Used to request guild members.
REQUEST_GUILD_MEMBERS = 8
+ """Used to request guild members."""
- #: Used to notify client they have an invalid session id.
INVALID_SESSION = 9
+ """Used to notify client they have an invalid session id."""
- #: Sent immediately after connecting, contains heartbeat and server debug
- #: information.
HELLO = 10
+ """Sent immediately after connecting.
+
+ Contains heartbeat and server debug information.
+ """
- #: Sent immediately following a client heartbeat that was received.
HEARTBEAT_ACK = 11
+ """Sent immediately following a client heartbeat that was received."""
- #: Not yet documented, so do not use.
GUILD_SYNC = 12
+ """Not yet documented, so do not use."""
def __str__(self) -> str:
name = self.name.replace("_", " ").title()
@@ -222,205 +234,207 @@ def __str__(self) -> str:
class JSONErrorCode(more_enums.EnumMixin, enum.IntEnum):
"""Error codes that can be returned by the REST API."""
- #: This is sent if the payload is screwed up, etc.
GENERAL_ERROR = 0
+ """This is sent if the payload is screwed up, etc."""
- #: Unknown account
UNKNOWN_ACCOUNT = 10_001
+ """Unknown account"""
- #: Unknown application
UNKNOWN_APPLICATION = 10_002
+ """Unknown application"""
- #: Unknown channel
UNKNOWN_CHANNEL = 10_003
+ """Unknown channel"""
- #: Unknown guild
UNKNOWN_GUILD = 10_004
+ """Unknown guild"""
- #: Unknown integration
UNKNOWN_INTEGRATION = 10_005
+ """Unknown integration"""
- #: Unknown invite
UNKNOWN_INVITE = 10_006
+ """Unknown invite"""
- #: Unknown member
UNKNOWN_MEMBER = 10_007
+ """Unknown member"""
- #: Unknown message
UNKNOWN_MESSAGE = 10_008
+ """Unknown message"""
- #: Unknown overwrite
UNKNOWN_OVERWRITE = 10_009
+ """Unknown overwrite"""
- #: Unknown provider
UNKNOWN_PROVIDER = 10_010
+ """Unknown provider"""
- #: Unknown role
UNKNOWN_ROLE = 10_011
+ """Unknown role"""
- #: Unknown token
UNKNOWN_TOKEN = 10_012
+ """Unknown token"""
- #: Unknown user
UNKNOWN_USER = 10_013
+ """Unknown user"""
- #: Unknown emoji
UNKNOWN_EMOJI = 10_014
+ """Unknown emoji"""
- #: Unknown webhook
UNKNOWN_WEBHOOK = 10_015
+ """Unknown Webhook"""
- #: Unknown ban
UNKNOWN_BAN = 10_026
+ """Unknown ban"""
- #: Bots cannot use this endpoint
- #:
- #: Note
- #: ----
- #: You should never expect to receive this in normal API usage.
USERS_ONLY = 20_001
+ """Bots cannot use this endpoint
+
+ !!! note
+ You should never expect to receive this in normal API usage.
+ """
- #: Only bots can use this endpoint.
- #:
- #: Note
- #: ----
- #: You should never expect to receive this in normal API usage.
BOTS_ONLY = 20_002
+ """Only bots can use this endpoint.
+
+ !!! note
+ You should never expect to receive this in normal API usage.
+ """
- #: Maximum number of guilds reached (100)
- #:
- #: Note
- #: ----
- #: You should never expect to receive this in normal API usage as this only
- #: applies to user accounts.
- #:
- #: This is unlimited for bot accounts.
MAX_GUILDS_REACHED = 30_001
+ """Maximum number of guilds reached (100)
+
+ !!! note
+ You should never expect to receive this in normal API usage as this only
+ applies to user accounts.
+
+ This is unlimited for bot accounts.
+ """
- #: Maximum number of friends reached (1000)
- #:
- #: Note
- #: ----
- #: You should never expect to receive this in normal API usage as this only
- #: applies to user accounts.
- #:
- #: Bots cannot have friends :( .
MAX_FRIENDS_REACHED = 30_002
+ """Maximum number of friends reached (1000)
+
+ !!! note
+ You should never expect to receive this in normal API usage as this only
+ applies to user accounts.
+
+ Bots cannot have friends :( .
+ """
- #: Maximum number of pins reached (50)
MAX_PINS_REACHED = 30_003
+ """Maximum number of pins reached (50)"""
- #: Maximum number of guild roles reached (250)
MAX_GUILD_ROLES_REACHED = 30_005
+ """Maximum number of guild roles reached (250)"""
- #: Maximum number of webhooks reached (10)
MAX_WEBHOOKS_REACHED = 30_007
+ """Maximum number of webhooks reached (10)"""
- #: Maximum number of reactions reached (20)
MAX_REACTIONS_REACHED = 30_010
+ """Maximum number of reactions reached (20)"""
- #: Maximum number of guild channels reached (500)
MAX_GUILD_CHANNELS_REACHED = 30_013
+ """Maximum number of guild channels reached (500)"""
- #: Maximum number of attachments in a message reached (10)
MAX_MESSAGE_ATTACHMENTS_REACHED = 30_015
+ """Maximum number of attachments in a message reached (10)"""
- #: Maximum number of invites reached (10000)
MAX_INVITES_REACHED = 30_016
+ """Maximum number of invites reached (10000)"""
- #: Unauthorized
- UNAUTHORIZED = 40_001
-
- #: You need to verify your account to perform this action.
NEEDS_VERIFICATION = 40_002
+ """You need to verify your account to perform this action."""
+
+ UNAUTHORIZED = 40_001
+ """Unauthorized"""
- #: Request entity too large. Try sending something smaller in size
TOO_LARGE = 40_005
+ """Request entity too large. Try sending something smaller in size"""
- #: This feature has been temporarily disabled server-side
DISABLED_TEMPORARILY = 40_006
+ """This feature has been temporarily disabled server-side"""
- #: The user is banned from this guild
USER_BANNED = 40_007
+ """The user is banned from this guild"""
- #: Missing access
MISSING_ACCESS = 50_001
+ """Missing access"""
- #: Invalid account type
INVALID_ACCOUNT_TYPE = 50_002
+ """Invalid account type"""
- #: Cannot execute action on a DM channel
CANNOT_EXECUTE_ACTION_ON_DM_CHANNEL = 50_003
+ """Cannot execute action on a DM channel"""
- #: Widget Disabled
WIDGET_DISABLED = 50_004
+ """Widget Disabled"""
- #: Cannot edit a message authored by another user
CANNOT_EDIT_A_MESSAGE_AUTHORED_BY_ANOTHER_USER = 50_005
+ """Cannot edit a message authored by another user"""
- #: Cannot send an empty message
CANNOT_SEND_AN_EMPTY_MESSAGE = 50_006
+ """Cannot send an empty message"""
- #: Cannot send messages to this user
CANNOT_SEND_MESSAGES_TO_THIS_USER = 50_007
+ """Cannot send messages to this user"""
- #: Cannot send messages in a voice channel
CANNOT_SEND_MESSAGES_IN_VOICE_CHANNEL = 50_008
+ """Cannot send messages in a voice channel"""
- #: Channel verification level is too high
CHANNEL_VERIFICATION_TOO_HIGH = 50_009
+ """Channel verification level is too high"""
- #: OAuth2 application does not have a bot
OAUTH2_APPLICATION_DOES_NOT_HAVE_A_BOT = 50_010
+ """OAuth2 application does not have a bot"""
- #: OAuth2 application limit reached
OAUTH2_APPLICATION_LIMIT_REACHED = 50_011
+ """OAuth2 application limit reached"""
- #: Invalid OAuth state
INVALID_OAUTH2_STATE = 50_012
+ """Invalid OAuth state"""
- #: Missing permissions
MISSING_PERMISSIONS = 50_013
+ """Missing permissions"""
- #: Invalid authentication token
INVALID_AUTHENTICATION_TOKEN = 50_014
+ """Invalid authentication token"""
- #: Note is too long
NOTE_IS_TOO_LONG = 50_015
+ """Note is too long"""
- #: Provided too few or too many messages to delete. Must provide at least 2
- #: and fewer than 100 messages to delete.
INVALID_NUMBER_OF_MESSAGES_TO_DELETE = 50_016
+ """Provided too few or too many messages to delete.
+
+ Must provide at least 2 and fewer than 100 messages to delete.
+ """
- #: A message can only be pinned to the channel it was sent in
CANNOT_PIN_A_MESSAGE_IN_A_DIFFERENT_CHANNEL = 50_019
+ """A message can only be pinned to the channel it was sent in"""
- #: Invite code is either invalid or taken.
INVALID_INVITE = 50_020
+ """Invite code is either invalid or taken."""
- #: Cannot execute action on a system message
CANNOT_EXECUTE_ACTION_ON_SYSTEM_MESSAGE = 50_021
+ """Cannot execute action on a system message"""
- #: Invalid OAuth2 access token
INVALID_OAUTH2_TOKEN = 50_025
+ """Invalid OAuth2 access token"""
- #: A message provided was too old to bulk delete
MESSAGE_PROVIDED_WAS_TOO_OLD_TO_BULK_DELETE = 50_034
+ """A message provided was too old to bulk delete"""
- #: Invalid Form Body
INVALID_FORM_BODY = 50_035
+ """Invalid Form Body"""
- #: An invite was accepted to a guild the application's bot is not in
ACCEPTED_INVITE_TO_GUILD_BOT_IS_NOT_IN = 50_036
+ """An invite was accepted to a guild the application's bot is not in"""
- #: Invalid API version
INVALID_API_VERSION = 50_041
+ """Invalid API version"""
- #: Reaction blocked
REACTION_BLOCKED = 90_001
+ """Reaction blocked"""
- #: The resource is overloaded.
RESOURCE_OVERLOADED = 130_000
+ """The resource is overloaded."""
def __str__(self) -> str:
name = self.name.replace("_", " ").title()
diff --git a/hikari/net/ratelimits.py b/hikari/net/ratelimits.py
index b761c0cde1..706c0a864f 100644
--- a/hikari/net/ratelimits.py
+++ b/hikari/net/ratelimits.py
@@ -25,49 +25,46 @@
What is the theory behind this implementation?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In this module, we refer to a :obj:`~hikari.net.routes.CompiledRoute` as a
-definition of a route with specific major parameter values included (e.g.
-``POST /channels/123/messages``), and a :obj:`~hikari.net.routes.RouteTemplate`
-as a definition of a route without specific parameter values included (e.g.
-``POST /channels/{channel_id}/messages``). We can compile a
-:obj:`~hikari.net.routes.CompiledRoute` from a
-:obj:`~hikari.net.routes.RouteTemplate` by providing the corresponding
-parameters as kwargs, as you may already know.
+In this module, we refer to a `hikari.net.routes.CompiledRoute` as a definition
+of a route with specific major parameter values included (e.g.
+`POST /channels/123/messages`), and a `hikari.net.routes.RouteTemplate` as a
+definition of a route without specific parameter values included (e.g.
+`POST /channels/{channel_id}/messages`). We can compile a
+`hikari.net.routes.CompiledRoute` from a `hikari.net.routes.RouteTemplate`
+by providing the corresponding parameters as kwargs, as you may already know.
In this module, a "bucket" is an internal data structure that tracks and
-enforces the rate limit state for a specific
-:obj:`~hikari.net.routes.CompiledRoute`, and can manage delaying tasks in the
-event that we begin to get rate limited. It also supports providing in-order
-execution of queued tasks.
+enforces the rate limit state for a specific `hikari.net.routes.CompiledRoute`,
+and can manage delaying tasks in the event that we begin to get rate limited.
+It also supports providing in-order execution of queued tasks.
Discord allocates types of buckets to routes. If you are making a request and
there is a valid rate limit on the route you hit, you should receive an
-``X-RateLimit-Bucket`` header from the server in your response. This is a hash
+`X-RateLimit-Bucket` header from the server in your response. This is a hash
that identifies a route based on internal criteria that does not include major
-parameters. This ``X-RateLimitBucket`` is known in this module as an
-"bucket hash".
+parameters. This `X-RateLimitBucket` is known in this module as an "bucket hash".
This means that generally, the route `POST /channels/123/messages` and
-``POST /channels/456/messages`` will usually sit in the same bucket, but
-``GET /channels/123/messages/789`` and ``PATCH /channels/123/messages/789`` will
+`POST /channels/456/messages` will usually sit in the same bucket, but
+`GET /channels/123/messages/789` and `PATCH /channels/123/messages/789` will
usually not share the same bucket. Discord may or may not change this at any
time, so hard coding this logic is not a useful thing to be doing.
Rate limits, on the other hand, apply to a bucket and are specific to the major
-parameters of the compiled route. This means that ``POST /channels/123/messages``
-and ``POST /channels/456/messages`` do not share the same real bucket, despite
-Discord providing the same bucket hash. A real bucket hash is the :obj:`~str`
-hash of the bucket that Discord sends us in a response concatenated to the
-corresponding major parameters. This is used for quick bucket indexing
-internally in this module.
+parameters of the compiled route. This means that `POST /channels/123/messages`
+and `POST /channels/456/messages` do not share the same real bucket, despite
+Discord providing the same bucket hash. A real bucket hash is the `str` hash of
+the bucket that Discord sends us in a response concatenated to the corresponding
+major parameters. This is used for quick bucket indexing internally in this
+module.
One issue that occurs from this is that we cannot effectively hash a
-:obj:`~hikari.net.routes.CompiledRoute` that has not yet been hit, meaning that
+`hikari.net.routes.CompiledRoute` that has not yet been hit, meaning that
until we receive a response from this endpoint, we have no idea what our rate
limits could be, nor the bucket that they sit in. This is usually not
problematic, as the first request to an endpoint should never be rate limited
unless you are hitting it from elsewhere in the same time window outside your
-Hikari application. To manage this situation, unknown endpoints are allocated to
+hikari.applications. To manage this situation, unknown endpoints are allocated to
a special unlimited bucket until they have an initial bucket hash code allocated
from a response. Once this happens, the route is reallocated a dedicated bucket.
Unknown buckets have a hardcoded initial hash code internally.
@@ -75,19 +72,18 @@
Initially acquiring time on a bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Each time you ``BaseRateLimiter.acquire()`` a request
-timeslice for a given :obj:`~hikari.net.routes.CompiledRoute`, several
-things happen. The first is that we attempt to find the existing bucket for
-that route, if there is one, or get an unknown bucket otherwise. This is done
-by creating a real bucket hash` from the compiled route. The initial hash
-is calculated using a lookup table that maps :obj:`~hikari.net.routes.CompiledRoute`
-objects to their corresponding initial hash codes, or to the unknown bucket
-hash code if not yet known. This initial hash is processed by the
-:obj:`~hikari.net.routes.CompiledRoute` to provide the real bucket hash we
-need to get the route's bucket object internally.
-
-The ``acquire`` method will take the bucket and acquire a new timeslice on
-it. This takes the form of a :obj:`~asyncio.Future` which should be awaited by
+Each time you `BaseRateLimiter.acquire()` a request timeslice for a given
+`hikari.net.routes.CompiledRoute`, several things happen. The first is that we
+attempt to find the existing bucket for that route, if there is one, or get an
+unknown bucket otherwise. This is done by creating a real bucket hash` from the
+compiled route. The initial hash is calculated using a lookup table that maps
+`hikari.net.routes.CompiledRoute` objects to their corresponding initial hash
+codes, or to the unknown bucket hash code if not yet known. This initial hash is
+processed by the `hikari.net.routes.CompiledRoute` to provide the real bucket
+hash we need to get the route's bucket object internally.
+
+The `acquire` method will take the bucket and acquire a new timeslice on
+it. This takes the form of a `asyncio.Future` which should be awaited by
the caller and will complete once the caller is allowed to make a request. Most
of the time, this is done instantly, but if the bucket has an active rate limit
preventing requests being sent, then the future will be paused until the rate
@@ -101,15 +97,15 @@
tidies itself up and disposes of itself. This task will complete once the queue
becomes empty.
-The result of ``RateLimiter.acquire()`` is a tuple of a
-:obj:`~asyncio.Future` to await on which completes when you are allowed to
-proceed with making a request, and a real bucket hash which should be
-stored temporarily. This will be explained in the next section.
+The result of `RateLimiter.acquire()` is a tuple of a `asyncio.Future` to await
+on which completes when you are allowed to proceed with making a request, and a
+real bucket hash which should be stored temporarily. This will be explained in
+the next section.
When you make your response, you should be sure to set the
-``X-RateLimit-Precision`` header to ``millisecond`` to ensure a much greater
+`X-RateLimit-Precision` header to `millisecond` to ensure a much greater
accuracy against rounding errors for rate limits (reduces the error margin from
-``1`` second to ``1`` millisecond).
+`1` second to `1` millisecond).
Handling the rate limit headers of a response
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -118,28 +114,28 @@
the vital rate limit headers manually and parse them to the correct data types.
These headers are:
-* ``Date``:
+* `Date`:
the response date on the server. This should be parsed to a
- :obj:`~datetime.datetime` using :func:`email.utils.parsedate_to_datetime`.
-* ``X-RateLimit-Limit``:
- an :obj:`~int` describing the max requests in the bucket
- from empty to being rate limited.
-* ``X-RateLimit-Remaining``:
- an :obj:`~int` describing the remaining number of
- requests before rate limiting occurs in the current window.
-* ``X-RateLimit-Bucket``:
- a :obj:`~str` containing the initial bucket hash.
-* ``X-RateLimit-Reset``:
- a :obj:`~float` containing the number of seconds since
+ `datetime.datetime` using `email.utils.parsedate_to_datetime`.
+* `X-RateLimit-Limit`:
+ an `int` describing the max requests in the bucket from empty to being rate
+ limited.
+* `X-RateLimit-Remaining`:
+ an `int` describing the remaining number of requests before rate limiting
+ occurs in the current window.
+* `X-RateLimit-Bucket`:
+ a `str` containing the initial bucket hash.
+* `X-RateLimit-Reset`:
+ a `float` containing the number of seconds since
1st January 1970 at 0:00:00 UTC at which the current ratelimit window
- resets. This should be parsed to a :obj:`~datetime.datetime` using
- :meth:`datetime.datetime.fromtimestamp`, passing :obj:`~datetime.timezone.utc`
- as ``tz``.
+ resets. This should be parsed to a `datetime.datetime` using
+ `datetime.datetime.fromtimestamp`, passing `datetime.timezone.utc`
+ as `tz`.
-Each of the above values should be passed to the
-``update_rate_limits`` method to ensure that the bucket you acquired time
-from is correctly updated should Discord decide to alter their ratelimits on the
-fly without warning (including timings and the bucket).
+Each of the above values should be passed to the `update_rate_limits` method to
+ensure that the bucket you acquired time from is correctly updated should
+Discord decide to alter their ratelimits on the fly without warning (including
+timings and the bucket).
This method will manage creating new buckets as needed and resetting vital
information in each bucket you use.
@@ -147,17 +143,17 @@
Tidying up
~~~~~~~~~~
-To prevent unused buckets cluttering up memory, each :obj:`~BaseRateLimiter`
-instance spins up a :obj:`~asyncio.Task` that periodically locks the bucket
-list (not threadsafe, only using the concept of asyncio not yielding in regular
+To prevent unused buckets cluttering up memory, each `BaseRateLimiter`
+instance spins up a `asyncio.Task` that periodically locks the bucket list
+(not threadsafe, only using the concept of asyncio not yielding in regular
functions) and disposes of any clearly stale buckets that are no longer needed.
These will be recreated again in the future if they are needed.
-When shutting down an application, one must remember to ``close()`` the
-:obj:`~BaseRateLimiter` that has been used. This will ensure the garbage collection
+When shutting down an application, one must remember to `close()` the
+`BaseRateLimiter` that has been used. This will ensure the garbage collection
task is stopped, and will also ensure any remaining futures in any bucket queues
-have an :obj:`~asyncio.CancelledError` set on them to prevent deadlocking
-ratelimited calls that may be waiting to be unlocked.
+have an `asyncio.CancelledError` set on them to prevent deadlocking ratelimited
+calls that may be waiting to be unlocked.
"""
__all__ = [
"BaseRateLimiter",
@@ -183,10 +179,8 @@
from hikari.internal import more_typing
from hikari.net import routes
-#: The hash used for an unknown bucket that has not yet been resolved.
-#:
-#: :type: :obj:`~str`
UNKNOWN_HASH: typing.Final[str] = "UNKNOWN"
+"""The hash used for an unknown bucket that has not yet been resolved."""
class BaseRateLimiter(abc.ABC):
@@ -194,9 +188,8 @@ class BaseRateLimiter(abc.ABC):
Supports being used as a synchronous context manager.
- Warnings
- --------
- Async context manager support is not supported and will not be supported.
+ !!! warning
+ Async context manager support is not supported and will not be supported.
"""
__slots__ = ()
@@ -207,7 +200,7 @@ def acquire(self) -> more_typing.Future[None]:
Returns
-------
- :obj:`~asyncio.Future`
+ asyncio.Future
A future that should be awaited. Once the future is complete, you
can proceed to execute your rate-limited task.
"""
@@ -232,25 +225,17 @@ class BurstRateLimiter(BaseRateLimiter, abc.ABC):
__slots__ = ("name", "throttle_task", "queue", "logger")
- #: The name of the rate limiter.
- #:
- #: :type: :obj:`~str`
name: typing.Final[str]
+ """The name of the rate limiter."""
- #: The throttling task, or :obj:`~None` if it isn't running.
- #:
- #: :type: :obj:`~asyncio.Task`, optional
throttle_task: typing.Optional[more_typing.Task[None]]
+ """The throttling task, or `None` if it isn't running."""
- #: The queue of any futures under a rate limit.
- #:
- #: :type: :obj:`~asyncio.Queue` [`asyncio.Future`]
queue: typing.Final[typing.List[more_typing.Future[None]]]
+ """The queue of any futures under a rate limit."""
- #: The logger used by this rate limiter.
- #:
- #: :type: :obj:`~logging.Logger`
logger: typing.Final[logging.Logger]
+ """The logger used by this rate limiter."""
def __init__(self, name: str) -> None:
self.name = name
@@ -266,7 +251,7 @@ def acquire(self) -> more_typing.Future[None]:
Returns
-------
- :obj:`~asyncio.Future`
+ asyncio.Future
A future that should be immediately awaited. Once the await
completes, you are able to proceed with the operation that is
under this rate limit.
@@ -294,7 +279,7 @@ def close(self) -> None:
@property
def is_empty(self) -> bool:
- """Return :obj:`~True` if no futures are on the queue being rate limited."""
+ """Return `True` if no futures are on the queue being rate limited."""
return len(self.queue) == 0
@@ -302,12 +287,12 @@ class ManualRateLimiter(BurstRateLimiter):
"""Rate limit handler for the global REST rate limit.
This is a non-preemptive rate limiting algorithm that will always return
- completed futures until :meth:`throttle` is invoked. Once this is invoked,
- any subsequent calls to :meth:`acquire` will return incomplete futures
- that will be enqueued to an internal queue. A task will be spun up to wait
- for a period of time given to the :meth:`throttle`. Once that has passed,
- the lock will begin to re-consume incomplete futures on the queue,
- completing them.
+ completed futures until `ManualRateLimiter.throttle` is invoked. Once this
+ is invoked, any subsequent calls to `ManualRateLimiter.acquire` will return
+ incomplete futures that will be enqueued to an internal queue. A task will
+ be spun up to wait for a period of time given to the
+ `ManualRateLimiter.throttle`. Once that has passed, the lock will begin to
+ re-consume incomplete futures on the queue, completing them.
Triggering a throttle when it is already set will cancel the current
throttle task that is sleeping and replace it.
@@ -328,7 +313,7 @@ def acquire(self) -> more_typing.Future[None]:
Returns
-------
- :obj:`~asyncio.Future`
+ asyncio.Future
A future that should be immediately awaited. Once the await
completes, you are able to proceed with the operation that is
under this rate limit.
@@ -347,23 +332,22 @@ def throttle(self, retry_after: float) -> None:
Iterates repeatedly while the queue is not empty, adhering to any
rate limits that occur in the mean time.
- retry_after : :obj:`~float`
+ retry_after : float
How long to sleep for before unlocking and releasing any futures
in the queue.
- Note
- ----
- This will invoke :meth:`unlock_later` as a scheduled task in the future
- (it will not await it to finish)
+ !!! note
+ This will invoke `ManualRateLimiter.unlock_later` as a scheduled task
+ in the future (it will not await it to finish).
- When the :meth:`unlock_later` coroutine function completes, it should be
- expected to set the `throttle_task`` to :obj:`~None`. This means you can
- check if throttling is occurring by checking if ``throttle_task``
- is not :obj:`~None`.
+ When the `ManualRateLimiter.unlock_later` coroutine function
+ completes, it should be expected to set the `throttle_task` to
+ `None`. This means you can check if throttling is occurring by
+ checking if `throttle_task` is not `None`.
- If this is invoked while another throttle is in progress, that one is
- cancelled and a new one is started. This enables new rate limits to
- override existing ones.
+ If this is invoked while another throttle is in progress, that one
+ is cancelled and a new one is started. This enables new rate limits
+ to override existing ones.
"""
if self.throttle_task is not None:
self.throttle_task.cancel()
@@ -376,19 +360,18 @@ async def unlock_later(self, retry_after: float) -> None:
Parameters
----------
- retry_after : :obj:`~float`
+ retry_after : float
How long to sleep for before unlocking and releasing any futures
in the queue.
- Note
- ----
- You shouldn't need to invoke this directly. Call :meth:`throttle`
- instead.
+ !!! note
+ You shouldn't need to invoke this directly. Call
+ `ManualRateLimiter.throttle` instead.
- When the :meth:`unlock_later` coroutine function completes, it should be
- expected to set the ``throttle_task`` to :obj:`~None`. This means you can
- check if throttling is occurring by checking if ``throttle_task``
- is not :obj:`~None`.
+ When the `ManualRateLimiter.unlock_later` coroutine function
+ completes, it should be expected to set the `throttle_task` to
+ `None`. This means you can check if throttling is occurring by
+ checking if `throttle_task` is not `None`.
"""
self.logger.warning("you are being globally rate limited for %ss", retry_after)
await asyncio.sleep(retry_after)
@@ -404,8 +387,8 @@ class WindowedBurstRateLimiter(BurstRateLimiter):
Rate limiter for rate limits that last fixed periods of time with a
fixed number of times it can be used in that time frame.
- To use this, you should call :meth:`acquire` and await the result
- immediately before performing your rate-limited task.
+ To use this, you should call WindowedBurstRateLimiter.aquire` and await the
+ result immediately before performing your rate-limited task.
If the rate limit has been hit, acquiring time will return an incomplete
future that is placed on the internal queue. A throttle task is then spun up
@@ -429,26 +412,21 @@ class WindowedBurstRateLimiter(BurstRateLimiter):
__slots__ = ("reset_at", "remaining", "limit", "period")
- #: The :func:`time.perf_counter` that the limit window ends at.
- #:
- #: :type: :obj:`~float`
reset_at: float
+ """The `time.perf_counter` that the limit window ends at."""
- #: The number of :meth:`acquire`'s left in this window before you will get
- #: rate limited.
- #:
- #: :type: :obj:`~int`
remaining: int
+ """The number of `WindowedBurstRateLimiter.acquire`'s left in this window
+ before you will get rate limited.
+ """
- #: How long the window lasts for from the start in seconds.
- #:
- #: :type: :obj:`~float`
period: float
+ """How long the window lasts for from the start in seconds."""
- #: The maximum number of :meth:`acquire`'s allowed in this time window.
- #:
- #: :type: :obj:`~int`
limit: int
+ """The maximum number of `WindowedBurstRateLimiter.acquire`'s allowed in
+ this time window.
+ """
def __init__(self, name: str, period: float, limit: int) -> None:
super().__init__(name)
@@ -462,7 +440,7 @@ def acquire(self) -> more_typing.Future[None]:
Returns
-------
- :obj:`~asyncio.Future`
+ asyncio.Future
A future that should be immediately awaited. Once the await
completes, you are able to proceed with the operation that is
under this rate limit.
@@ -489,22 +467,21 @@ def get_time_until_reset(self, now: float) -> float:
Parameters
----------
- now : :obj:`~float`
- The monotonic :func:`time.perf_counter` timestamp.
+ now : float
+ The monotonic `time.perf_counter` timestamp.
Returns
-------
- :obj:`~float`
+ float
The time left to sleep before the rate limit is reset. If no rate limit
- is in effect, then this will return ``0.0`` instead.
-
- Warning
- -------
- Invoking this method will update the internal state if we were
- previously rate limited, but at the given time are no longer under that
- limit. This makes it imperative that you only pass the current timestamp
- to this function, and not past or future timestamps. The effects of
- doing the latter are undefined behaviour.
+ is in effect, then this will return `0.0` instead.
+
+ !!! warning
+ Invoking this method will update the internal state if we were
+ previously rate limited, but at the given time are no longer under
+ that limit. This makes it imperative that you only pass the current
+ timestamp to this function, and not past or future timestamps. The
+ effects of doing the latter are undefined behaviour.
"""
if not self.is_rate_limited(now):
return 0.0
@@ -515,21 +492,20 @@ def is_rate_limited(self, now: float) -> bool:
Parameters
----------
- now : :obj:`~float`
- The monotonic :func:`time.perf_counter` timestamp.
+ now : float
+ The monotonic `time.perf_counter` timestamp.
Returns
-------
- :obj:`~bool`
- :obj:`~True` if we are being rate limited. :obj:`~False` if we are not.
-
- Warning
- -------
- Invoking this method will update the internal state if we were
- previously rate limited, but at the given time are no longer under that
- limit. This makes it imperative that you only pass the current timestamp
- to this function, and not past or future timestamps. The effects of
- doing the latter are undefined behaviour.
+ bool
+ `True` if we are being rate limited. `False` if we are not.
+
+ !!! warning
+ Invoking this method will update the internal state if we were
+ previously rate limited, but at the given time are no longer under
+ that limit. This makes it imperative that you only pass the current
+ timestamp to this function, and not past or future timestamps. The
+ effects of doing the latter are undefined behaviour.
"""
if self.reset_at <= now:
self.remaining = self.limit
@@ -548,15 +524,14 @@ async def throttle(self) -> None:
Iterates repeatedly while the queue is not empty, adhering to any
rate limits that occur in the mean time.
- Note
- ----
- You should usually not need to invoke this directly, but if you do,
- ensure to call it using :func:`asyncio.create_task`, and store the
- task immediately in ``throttle_task``.
+ !!! note
+ You should usually not need to invoke this directly, but if you do,
+ ensure to call it using `asyncio.create_task`, and store the
+ task immediately in `throttle_task`.
- When this coroutine function completes, it will set the
- ``throttle_task`` to :obj:`~None`. This means you can check if throttling
- is occurring by checking if ``throttle_task`` is not :obj:`~None`.
+ When this coroutine function completes, it will set the
+ `throttle_task` to `None`. This means you can check if throttling
+ is occurring by checking if `throttle_task` is not `None`.
"""
self.logger.debug(
"you are being rate limited on bucket %s, backing off for %ss",
@@ -581,7 +556,7 @@ class RESTBucket(WindowedBurstRateLimiter):
Component to represent an active rate limit bucket on a specific REST route
with a specific major parameter combo.
- This is somewhat similar to the :obj:`~WindowedBurstRateLimiter` in how it
+ This is somewhat similar to the `WindowedBurstRateLimiter` in how it
works.
This algorithm will use fixed-period time windows that have a given limit
@@ -593,16 +568,14 @@ class RESTBucket(WindowedBurstRateLimiter):
capacity to zero, and tasks that are queued will start being able to drip
again.
- Additional logic is provided by the :meth:`update_rate_limit` call which
- allows dynamically changing the enforced rate limits at any time.
+ Additional logic is provided by the `RESTBucket.update_rate_limit` call
+ which allows dynamically changing the enforced rate limits at any time.
"""
__slots__ = ("compiled_route",)
- #: The compiled route that this rate limit is covering.
- #:
- #: :type: :obj:`~hikari.net.routes.CompiledRoute`
compiled_route: typing.Final[routes.CompiledRoute]
+ """The compiled route that this rate limit is covering."""
def __init__(self, name: str, compiled_route: routes.CompiledRoute) -> None:
super().__init__(name, 1, 1)
@@ -612,7 +585,7 @@ def __init__(self, name: str, compiled_route: routes.CompiledRoute) -> None:
@property
def is_unknown(self) -> bool:
- """Return :obj:`~True` if the bucket represents an ``UNKNOWN`` bucket."""
+ """Return `True` if the bucket represents an `UNKNOWN` bucket."""
return self.name.startswith(UNKNOWN_HASH)
def acquire(self) -> more_typing.Future[None]:
@@ -620,14 +593,13 @@ def acquire(self) -> more_typing.Future[None]:
Returns
-------
- :obj:`~asyncio.Future`
+ asyncio.Future
A future that should be awaited immediately. Once the future completes,
you are allowed to proceed with your operation.
- Note
- ----
- You should afterwards invoke :meth:`update_rate_limit` to update any
- rate limit information you are made aware of.
+ !!! note
+ You should afterwards invoke `RESTBucket.update_rate_limit` to
+ update any rate limit information you are made aware of.
"""
return more_asyncio.completed_future(None) if self.is_unknown else super().acquire()
@@ -636,17 +608,16 @@ def update_rate_limit(self, remaining: int, limit: int, reset_at: float) -> None
Parameters
----------
- remaining : :obj:`~int`
+ remaining : int
The calls remaining in this time window.
- limit : :obj:`~int`
+ limit : int
The total calls allowed in this time window.
- reset_at : :obj:`~float`
+ reset_at : float
The epoch at which to reset the limit.
- Note
- ----
- The ``reset_at`` epoch is expected to be a :func:`time.perf_counter`
- monotonic epoch, rather than a :func:`time.time` date-based epoch.
+ !!! note
+ The `reset_at` epoch is expected to be a `time.perf_counter`
+ monotonic epoch, rather than a `time.time` date-based epoch.
"""
self.remaining = remaining
self.limit = limit
@@ -656,10 +627,9 @@ def update_rate_limit(self, remaining: int, limit: int, reset_at: float) -> None
def drip(self) -> None:
"""Decrement the remaining count for this bucket.
- Note
- ----
- If the bucket is marked as :attr:`is_unknown`, then this will not do
- anything. ``Unknown`` buckets have infinite rate limits.
+ !!! note
+ If the bucket is marked as `RESTBucket.is_unknown`, then this will
+ not do anything. `Unknown` buckets have infinite rate limits.
"""
# We don't drip unknown buckets: we can't rate limit them as we don't know their real bucket hash or
# the current rate limit values Discord put on them...
@@ -671,7 +641,7 @@ class RESTBucketManager:
"""The main rate limiter implementation for REST clients.
This is designed to provide bucketed rate limiting for Discord REST
- endpoints that respects the ``X-RateLimit-Bucket`` rate limit header. To do
+ endpoints that respects the `X-RateLimit-Bucket` rate limit header. To do
this, it makes the assumption that any limit can change at any time.
"""
@@ -683,32 +653,23 @@ class RESTBucketManager:
"logger",
)
- #: Maps compiled routes to their ``X-RateLimit-Bucket`` header being used.
- #:
- #: :type: :obj:`~typing.MutableMapping` [ :obj:`~hikari.net.routes.CompiledRoute`, :obj:`~str` ]
routes_to_hashes: typing.Final[typing.MutableMapping[routes.CompiledRoute, str]]
+ """Maps compiled routes to their `X-RateLimit-Bucket` header being used."""
- #: Maps full bucket hashes (``X-RateLimit-Bucket`` appended with a hash of
- #: major parameters used in that compiled route) to their corresponding rate
- #: limiters.
- #:
- #: :type: :obj:`~typing.MutableMapping` [ :obj:`~str`, :obj:`~RESTBucket` ]
real_hashes_to_buckets: typing.Final[typing.MutableMapping[str, RESTBucket]]
+ """Maps full bucket hashes (`X-RateLimit-Bucket` appended with a hash of
+ major parameters used in that compiled route) to their corresponding rate
+ limiters.
+ """
- #: An internal event that is set when the object is shut down.
- #:
- #: :type: :obj:`~asyncio.Event`
closed_event: typing.Final[asyncio.Event]
+ """An internal event that is set when the object is shut down."""
- #: The internal garbage collector task.
- #:
- #: :type: :obj:`~asyncio.Task`, optional
gc_task: typing.Optional[more_typing.Task[None]]
+ """The internal garbage collector task."""
- #: The logger to use for this object.
- #:
- #: :type: :obj:`~logging.Logger`
logger: typing.Final[logging.Logger]
+ """The logger to use for this object."""
def __init__(self) -> None:
self.routes_to_hashes = weakref.WeakKeyDictionary()
@@ -735,9 +696,9 @@ def start(self, poll_period: float = 20) -> None:
Parameters
----------
- poll_period : :obj:`~float`
+ poll_period : float
Period to poll the garbage collector at in seconds. Defaults
- to ``20`` seconds.
+ to `20` seconds.
"""
if not self.gc_task:
self.gc_task = asyncio.get_running_loop().create_task(self.gc(poll_period))
@@ -761,18 +722,18 @@ async def gc(self, poll_period: float = 20) -> None: # noqa: D401
This is designed to run in the background and manage removing unused
route references from the rate-limiter collection to save memory.
- This will run forever until :attr:`closed_event` is set. This will
- invoke :meth:`do_gc_pass` periodically.
+ This will run forever until `RESTBucketManager. closed_event` is set.
+ This will invoke `RESTBucketManager.do_gc_pass` periodically.
Parameters
----------
- poll_period : :obj:`~float`
- The period to poll at. This defaults to once every ``20`` seconds.
+ poll_period : float
+ The period to poll at. This defaults to once every `20` seconds.
- Warnings
- --------
- You generally have no need to invoke this directly. Use
- :meth:`start` and :meth:`close` to control this instead.
+ !!! warning
+ You generally have no need to invoke this directly. Use
+ `RESTBucketManager.start` and `RESTBucketManager.close` to control
+ this instead.
"""
# Prevent filling memory increasingly until we run out by removing dead buckets every 20s
# Allocations are somewhat cheap if we only do them every so-many seconds, after all.
@@ -795,10 +756,10 @@ def do_gc_pass(self) -> None:
If the removed routes are used again in the future, they will be
re-cached automatically.
- Warning
- -------
- You generally have no need to invoke this directly. Use
- :meth:`start` and :meth:`close` to control this instead.
+ !!! warning
+ You generally have no need to invoke this directly. Use
+ `RESTBucketManager.start` and `RESTBucketManager.close` to control
+ this instead.
"""
buckets_to_purge = []
@@ -820,21 +781,20 @@ def acquire(self, compiled_route: routes.CompiledRoute) -> more_typing.Future:
Parameters
----------
- compiled_route : :obj:`~hikari.net.routes.CompiledRoute`
+ compiled_route : hikari.net.routes.CompiledRoute
The route to get the bucket for.
Returns
-------
- :obj:`~asyncio.Future`
+ asyncio.Future
A future to await that completes when you are allowed to run
your request logic.
- Note
- ----
- The returned future MUST be awaited, and will complete when your turn to
- make a call comes along. You are expected to await this and then
- immediately make your REST call. The returned future may already be
- completed if you can make the call immediately.
+ !!! note
+ The returned future MUST be awaited, and will complete when your
+ turn to make a call comes along. You are expected to await this and
+ then immediately make your REST call. The returned future may
+ already be completed if you can make the call immediately.
"""
# Returns a future to await on to wait to be allowed to send the request, and a
# bucket hash to use to update rate limits later.
@@ -868,20 +828,19 @@ def update_rate_limits(
Parameters
----------
- compiled_route : :obj:`~hikari.net.routes.CompiledRoute`
+ compiled_route : hikari.net.routes.CompiledRoute
The compiled route to get the bucket for.
- bucket_header : :obj:`~str`, optional
- The ``X-RateLimit-Bucket`` header that was provided in the response,
- or :obj:`~None` if not present.
- remaining_header : :obj:`~int`
- The ``X-RateLimit-Remaining`` header cast to an :obj:`~int`.
- limit_header : :obj:`~int`
- The ``X-RateLimit-Limit`` header cast to an :obj:`~int`.
- date_header : :obj:`~datetime.datetime`
- The ``Date`` header value as a :obj:`~datetime.datetime`.
- reset_at_header : :obj:`~datetime.datetime`
- The ``X-RateLimit-Reset`` header value as a
- :obj:`~datetime.datetime`.
+ bucket_header : str, optional
+ The `X-RateLimit-Bucket` header that was provided in the response,
+ or `None` if not present.
+ remaining_header : int
+ The `X-RateLimit-Remaining` header cast to an `int`.
+ limit_header : int
+ The `X-RateLimit-Limit`header cast to an `int`.
+ date_header : datetime.datetime
+ The `Date` header value as a `datetime.datetime`.
+ reset_at_header : datetime.datetime
+ The `X-RateLimit-Reset` header value as a `datetime.datetime`.
"""
self.routes_to_hashes[compiled_route] = bucket_header
@@ -903,51 +862,46 @@ class ExponentialBackOff:
.. math::
- t_{backoff} = b^{i} + m \\cdot rand()
+ t_{backoff} = b^{i} + m \cdot \mathrm{rand}()
- Such that :math:`t_{backoff}` is the backoff time, :math:`b` is the base,
- :math:`i` is the increment that increases by 1 for each invocation, and
- :math:`m` is the jitter multiplier. :math:`rand()` returns a value in the
- range :math:`[0,1)`.
+ Such that \(t_{backoff}\) is the backoff time, \(b\) is the base,
+ \(i\) is the increment that increases by 1 for each invocation, and
+ \(m\) is the jitter multiplier. \(\mathrm{rand}()\) returns a value in
+ the range \([0,1]\).
Parameters
----------
- base : :obj:`~float`
- The base to use. Defaults to ``2``.
- maximum : :obj:`~float`, optional
- If not :obj:`~None`, then this is the max value the backoff can be in a
- single iteration before an :obj:`~asyncio.TimeoutError` is raised.
- Defaults to ``64`` seconds.
- jitter_multiplier : :obj:`~float`
- The multiplier for the random jitter. Defaults to ``1``.
- Set to ``0`` to disable jitter.
- initial_increment : :obj:`~int`
- The initial increment to start at. Defaults to ``0``.
+ base : float
+ The base to use. Defaults to `2`.
+ maximum : float, optional
+ If not `None`, then this is the max value the backoff can be in a
+ single iteration before an `asyncio.TimeoutError` is raised.
+ Defaults to `64` seconds.
+ jitter_multiplier : float
+ The multiplier for the random jitter. Defaults to `1`.
+ Set to `0` to disable jitter.
+ initial_increment : int
+ The initial increment to start at. Defaults to `0`.
"""
__slots__ = ("base", "increment", "maximum", "jitter_multiplier")
- #: The base to use. Defaults to 2.
- #:
- #: :type: :obj:`~float`
base: typing.Final[float]
+ """The base to use. Defaults to 2."""
- #: The current increment.
- #:
- #: :type: :obj:`~int`
increment: int
+ """The current increment."""
- #: If not :obj:`~None`, then this is the max value the backoff can be in a
- #: single iteration before an :obj:`~asyncio.TimeoutError` is raised.
- #:
- #: :type: :obj:`~float`, optional
maximum: typing.Optional[float]
+ """If not `None`, then this is the max value the backoff can be in a
+ single iteration before an `asyncio.TimeoutError` is raised.
+ """
- #: The multiplier for the random jitter. Defaults to ``1``.
- #: Set to ``0`` to disable jitter.
- #:
- #: :type: :obj:`~float`
jitter_multiplier: typing.Final[float]
+ """The multiplier for the random jitter.
+
+ This defaults to `1`. Set to `0` to disable jitter.
+ """
def __init__(
self,
diff --git a/hikari/net/rest.py b/hikari/net/rest.py
index 934df23a70..35313a2e21 100644
--- a/hikari/net/rest.py
+++ b/hikari/net/rest.py
@@ -51,40 +51,38 @@ class REST:
Parameters
----------
- base_url: :obj:`~str`
+ base_url: str
The base URL and route for the discord API
- allow_redirects: :obj:`~bool`
+ allow_redirects: bool
Whether to allow redirects or not.
- connector: :obj:`~aiohttp.BaseConnector`, optional
+ connector: aiohttp.BaseConnector, optional
Optional aiohttp connector info for making an HTTP connection
- proxy_headers: :obj:`~typing.Mapping` [ :obj:`~str`, :obj:`~str` ], optional
+ proxy_headers: typing.Mapping [ str, str ], optional
Optional proxy headers to pass to HTTP requests.
- proxy_auth: :obj:`~aiohttp.BasicAuth`, optional
+ proxy_auth: aiohttp.BasicAuth, optional
Optional authorization to be used if using a proxy.
- proxy_url: :obj:`~str`, optional
+ proxy_url: str, optional
Optional proxy URL to use for HTTP requests.
- ssl_context: :obj:`~ssl.SSLContext`, optional
+ ssl_context: ssl.SSLContext, optional
The optional SSL context to be used.
- verify_ssl: :obj:`~bool`
+ verify_ssl: bool
Whether or not the client should enforce SSL signed certificate
- verification. If :obj:`~False` it will ignore potentially malicious
+ verification. If 1 it will ignore potentially malicious
SSL certificates.
- timeout: :obj:`~float`, optional
+ timeout: float, optional
The optional timeout for all HTTP requests.
- json_deserialize: ``deserialization function``
- A custom JSON deserializer function to use. Defaults to
- :func:`json.loads`.
- json_serialize: ``serialization function``
- A custom JSON serializer function to use. Defaults to
- :func:`json.dumps`.
- token: :obj:`~string`, optional
+ json_deserialize: `deserialization function`
+ A custom JSON deserializer function to use. Defaults to `json.loads`.
+ json_serialize: `serialization function`
+ A custom JSON serializer function to use. Defaults to `json.dumps`.
+ token: string, optional
The bot token for the client to use. You may start this with
- a prefix of either ``Bot`` or ``Bearer`` to force the token type, or
+ a prefix of either `Bot` or `Bearer` to force the token type, or
not provide this information if you want to have it auto-detected.
- If this is passed as :obj:`~None`, then no token is used.
- This will be passed as the ``Authorization`` header if not :obj:`~None`
+ If this is passed as `None`, then no token is used.
+ This will be passed as the `Authorization` header if not `None`
for each request.
- version: :obj:`~int`
+ version: int
The version of the API to use. Defaults to the most recent stable
version (v6).
"""
@@ -99,129 +97,112 @@ class REST:
_AUTHENTICATION_SCHEMES: typing.Final[typing.Tuple[str, ...]] = ("Bearer", "Bot")
- #: :obj:`~True` if HTTP redirects are enabled, or :obj:`~False` otherwise.
- #:
- #: :type: :obj:`~bool`
allow_redirects: bool
+ """`True` if HTTP redirects are enabled, or `False` otherwise."""
- #: The base URL to send requests to.
- #:
- #: :type: :obj:`~str`
base_url: str
+ """The base URL to send requests to."""
- #: The :mod:`aiohttp` client session to make requests with.
- #:
- #: This will be :obj:`~None` until the first request, due to limitations
- #: with how :obj:`aiohttp.ClientSession` is able to be initialized outside
- #: of a running event loop.
- #:
- #: :type: :obj:`~aiohttp.ClientSession`
client_session: typing.Optional[aiohttp.ClientSession]
+ """The `aiohttp` client session to make requests with.
+
+ This will be `None` until the first request, due to limitations with how
+ `aiohttp.ClientSession` is able to be initialized outside of a running
+ event loop.
+ """
- #: The base connector for the :obj:`~aiohttp.ClientSession`, if provided.
- #:
- #: :type: :obj:`~aiohttp.BaseConnector`, optional
connector: typing.Optional[aiohttp.BaseConnector]
+ """The base connector for the `aiohttp.ClientSession`, if provided."""
- #: The internal correlation ID for the number of requests sent. This will
- #: increase each time a REST request is sent.
- #:
- #: :type: :obj:`~int`
in_count: int
+ """The internal correlation ID for the number of requests sent.
+
+ This will increase each time a REST request is sent.
+ """
- #: The global ratelimiter. This is used if Discord declares a ratelimit
- #: across the entire API, regardless of the endpoint. If this is set, then
- #: any HTTP operation using this session will be paused.
- #:
- #: :type: :obj:`~hikari.net.ratelimits.ManualRateLimiter`
global_ratelimiter: ratelimits.ManualRateLimiter
+ """The global ratelimiter.
+
+ This is used if Discord declares a ratelimit across the entire API,
+ regardless of the endpoint. If this is set, then any HTTP operation using
+ this session will be paused.
+ """
- #: The logger to use for this object.
- #:
- #: :type: :obj:`~logging.Logger`
logger: logging.Logger
+ """The logger to use for this object."""
- #: The JSON deserialization function. This consumes a JSON string and
- #: produces some object.
json_deserialize: typing.Callable[[typing.AnyStr], typing.Any]
+ """The JSON deserialization function.
+
+ This consumes a JSON string and produces some object.
+ """
- #: The JSON deserialization function. This consumes an object and
- #: produces some JSON string.
json_serialize: typing.Callable[[typing.Any], typing.AnyStr]
+ """The JSON deserialization function.
+
+ This consumes an object and produces some JSON string.
+ """
- #: Proxy authorization to use.
- #:
- #: :type: :obj:`~aiohttp.BasicAuth`, optional
proxy_auth: typing.Optional[aiohttp.BasicAuth]
+ """Proxy authorization to use."""
- #: A set of headers to provide to a proxy server.
- #:
- #: :type: :obj:`~typing.Mapping` [ :obj:`~str`, :obj:`~str` ], optional
proxy_headers: typing.Optional[typing.Mapping[str, str]]
+ """A set of headers to provide to a proxy server."""
- #: An optional proxy URL to send requests to.
- #:
- #: :type: :obj:`~str`, optional
proxy_url: typing.Optional[str]
+ """An optional proxy URL to send requests to."""
- #: The per-route ratelimit manager. This handles tracking any ratelimits
- #: for routes that have recently been used or are in active use, as well
- #: as keeping memory usage to a minimum where possible for large numbers
- #: of varying requests. This encapsulates a lot of complex rate limiting
- #: rules to reduce the number of active ``429`` responses this client gets,
- #: and thus reducing your chances of an API ban by Discord.
- #:
- #: You should not ever need to touch this implementation.
- #:
- #: :type: :obj:`~hikari.net.ratelimits.RESTBucketManager`
bucket_ratelimiters: ratelimits.RESTBucketManager
+ """The per-route ratelimit manager.
+
+ This handles tracking any ratelimits for routes that have recently been used
+ or are in active use, as well as keeping memory usage to a minimum where
+ possible for large numbers of varying requests. This encapsulates a lot of
+ complex rate limiting rules to reduce the number of active `429` responses
+ this client gets, and thus reducing your chances of an API ban by Discord.
+
+ You should not ever need to touch this implementation.
+ """
- #: The custom SSL context to use.
- #:
- #: :type: :obj:`~ssl.SSLContext`
ssl_context: typing.Optional[ssl.SSLContext]
+ """The custom SSL context to use."""
- #: The HTTP request timeout to abort requests after.
- #:
- #: :type: :obj:`~float`
timeout: typing.Optional[float]
+ """The HTTP request timeout to abort requests after."""
- #: The bot token. This will be prefixed with either ``"Bearer "`` or
- #: ``"Bot"`` depending on the format of the token passed to the constructor.
- #:
- #: This value will be used for the ``Authorization`` HTTP header on each
- #: API request.
- #:
- #: If no token is set, then the value will be :obj:`~None`. In this case,
- #: no ``Authorization`` header will be sent.
- #:
- #: :type: :obj:`~str`, optional
token: typing.Optional[str]
+ """The bot token.
+
+ This will be prefixed with either `"Bearer"` or `"Bot"` depending on the
+ format of the token passed to the constructor.
+
+ This value will be used for the `Authorization` HTTP header on each
+ API request.
+
+ If no token is set, then the value will be `None`. In this case,
+ no `Authorization` header will be sent.
+ """
- #: The ``User-Agent`` header to send to Discord.
- #:
- #: Warning
- #: -------
- #: Changing this value may lead to undesirable results, as Discord document
- #: that they can actively IP ban any client that does not have a valid
- #: ``User-Agent`` header that conforms to specific requirements.
- #: Your mileage may vary (YMMV).
- #:
- #: :type: :obj:`~str`
user_agent: str
+ """The `User-Agent` header to send to Discord.
+
+ !!! warning
+ Changing this value may lead to undesirable results, as Discord document
+ that they can actively IP ban any client that does not have a valid
+ `User-Agent` header that conforms to specific requirements.
+ Your mileage may vary (YMMV).
+ """
- #: If :obj:`~True`, SSL certificates are verified for each request, and
- #: invalid SSL certificates are rejected, causing an exception. If
- #: :obj:`~False`, then unrecognised certificates that may be illegitimate
- #: are accepted and ignored.
- #:
- #: :type: :obj:`~bool`
verify_ssl: bool
+ """Whether SSL certificates should be verified for each request.
+
+ When this is `True` then an exception will be raised whenever invalid SSL
+ certificates are received. When this is `False` unrecognised certificates
+ that may be illegitimate are accepted and ignored.
+ """
- #: The API version number that is being used.
- #:
- #: :type: :obj:`~int`
version: int
+ """The API version number that is being used."""
def __init__(
self,
@@ -472,12 +453,11 @@ async def get_gateway(self) -> str:
Returns
-------
- :obj:`~str`
+ str
A static URL to use to connect to the gateway with.
- Note
- ----
- Users are expected to attempt to cache this result.
+ !!! note
+ Users are expected to attempt to cache this result.
"""
result = await self._request(routes.GATEWAY.compile(self.GET))
return result["url"]
@@ -487,13 +467,14 @@ async def get_gateway_bot(self) -> typing.Dict[str, typing.Any]:
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
- An object containing a ``url`` to connect to, an :obj:`~int` number of shards recommended to use
- for connecting, and a ``session_start_limit`` object.
+ typing.Dict [ str, typing.Any ]
+ An object containing a `url` to connect to, an `int` number of
+ shards recommended to use for connecting, and a
+ `session_start_limit` object.
- Note
- ----
- Unlike :meth:`get_gateway`, this requires a valid token to work.
+ !!! note
+ Unlike `LowLevelRestfulClient.get_gateway`, this requires a valid
+ token to work.
"""
return await self._request(routes.GATEWAY_BOT.compile(self.GET))
@@ -504,29 +485,29 @@ async def get_guild_audit_log(
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The guild ID to look up.
- user_id : :obj:`~str`
+ user_id : str
If specified, the user ID to filter by.
- action_type : :obj:`~int`
+ action_type : int
If specified, the action type to look up.
- limit : :obj:`~int`
+ limit : int
If specified, the limit to apply to the number of records.
- Defaults to ``50``. Must be between ``1`` and ``100`` inclusive.
- before : :obj:`~str`
+ Defaults to `50`. Must be between `1` and `100` inclusive.
+ before : str
If specified, the ID of the entry that all retrieved entries will
have occurred before.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
An audit log object.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack the given permissions to view an audit log.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild does not exist.
"""
query = {}
@@ -542,19 +523,19 @@ async def get_channel(self, channel_id: str) -> typing.Dict[str, typing.Any]:
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The channel ID to look up.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The channel object that has been found.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you don't have access to the channel.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel does not exist.
"""
route = routes.CHANNEL.compile(self.GET, channel_id=channel_id)
@@ -579,58 +560,58 @@ async def modify_channel( # lgtm [py/similar-function]
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The channel ID to update.
- name : :obj:`~str`
+ name : str
If specified, the new name for the channel. This must be
- between ``2`` and ``100`` characters in length.
- position : :obj:`~int`
+ between `2` and `100` characters in length.
+ position : int
If specified, the position to change the channel to.
- topic : :obj:`~str`
+ topic : str
If specified, the topic to set. This is only applicable to
- text channels. This must be between ``0`` and ``1024``
+ text channels. This must be between `0` and `1024`
characters in length.
- nsfw : :obj:`~bool`
+ nsfw : bool
If specified, whether the channel will be marked as NSFW.
Only applicable to text channels.
- rate_limit_per_user : :obj:`~int`
+ rate_limit_per_user : int
If specified, the number of seconds the user has to wait before sending
another message. This will not apply to bots, or to members with
- ``MANAGE_MESSAGES`` or ``MANAGE_CHANNEL`` permissions. This must
- be between ``0`` and ``21600`` seconds.
- bitrate : :obj:`~int`
+ `MANAGE_MESSAGES` or `MANAGE_CHANNEL` permissions. This must
+ be between `0` and `21600` seconds.
+ bitrate : int
If specified, the bitrate in bits per second allowable for the channel.
- This only applies to voice channels and must be between ``8000``
- and ``96000`` for normal servers or ``8000`` and ``128000`` for
+ This only applies to voice channels and must be between `8000`
+ and `96000` for normal servers or `8000` and `128000` for
VIP servers.
- user_limit : :obj:`~int`
+ user_limit : int
If specified, the new max number of users to allow in a voice channel.
- This must be between ``0`` and ``99`` inclusive, where
- ``0`` implies no limit.
- permission_overwrites : :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ This must be between `0` and `99` inclusive, where
+ `0` implies no limit.
+ permission_overwrites : typing.Sequence [ typing.Dict [ str, typing.Any ] ]
If specified, the new list of permission overwrites that are category
specific to replace the existing overwrites with.
- parent_id : :obj:`~str`, optional
+ parent_id : str, optional
If specified, the new parent category ID to set for the channel.,
- pass :obj:`~None` to unset.
- reason : :obj:`~str`
+ pass `None` to unset.
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The channel object that has been modified.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel does not exist.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack the permission to make the change.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If you provide incorrect options for the corresponding channel type
- (e.g. a ``bitrate`` for a text channel).
+ (e.g. a `bitrate` for a text channel).
"""
payload = {}
conversions.put_if_specified(payload, "name", name)
@@ -650,25 +631,25 @@ async def delete_close_channel(self, channel_id: str) -> None:
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The channel ID to delete, or direct message channel to close.
Returns
-------
- :obj:`~None`
+ None
Nothing, unlike what the API specifies. This is done to maintain
consistency with other calls of a similar nature in this API wrapper.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel does not exist.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you do not have permission to delete the channel.
- Warning
- -------
- Deleted channels cannot be un-deleted. Deletion of DMs is able to be undone by reopening the DM.
+ !!! warning
+ Deleted channels cannot be un-deleted. Deletion of DMs is able to be
+ undone by reopening the DM.
"""
route = routes.CHANNEL.compile(self.DELETE, channel_id=channel_id)
await self._request(route)
@@ -680,47 +661,46 @@ async def get_channel_messages(
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to retrieve the messages from.
- limit : :obj:`~int`
+ limit : int
If specified, the number of messages to return. Must be
- between ``1`` and ``100`` inclusive.Defaults to ``50``
+ between `1` and `100` inclusive.Defaults to `50`
if unspecified.
- after : :obj:`~str`
+ after : str
A message ID. If specified, only return messages sent AFTER this message.
- before : :obj:`~str`
+ before : str
A message ID. If specified, only return messages sent BEFORE this message.
- around : :obj:`~str`
+ around : str
A message ID. If specified, only return messages sent AROUND and
including (if it still exists) this message.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of message objects.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permission to read the channel.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If your query is malformed, has an invalid value for ``limit``,
- or contains more than one of ``after``, ``before`` and ``around``.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.BadRequestHTTPError
+ If your query is malformed, has an invalid value for `limit`,
+ or contains more than one of `after`, `before` and `around`.
+ hikari.errors.NotFoundHTTPError
If the channel is not found, or the message
provided for one of the filter arguments is not found.
- Note
- ----
- If you are missing the ``VIEW_CHANNEL`` permission, you will receive a
- :obj:`~hikari.errors.ForbiddenHTTPError`. If you are instead missing
- the ``READ_MESSAGE_HISTORY`` permission, you will always receive
- zero results, and thus an empty list will be returned instead.
+ !!! note
+ If you are missing the `VIEW_CHANNEL` permission, you will receive a
+ `hikari.errors.ForbiddenHTTPError`. If you are instead missing
+ the `READ_MESSAGE_HISTORY` permission, you will always receive
+ zero results, and thus an empty list will be returned instead.
- Warning
- -------
- You can only specify a maximum of one from ``before``, ``after``, and ``around``.
- Specifying more than one will cause a :obj:`~hikari.errors.BadRequestHTTPError` to be raised.
+ !!! warning
+ You can only specify a maximum of one from `before`, `after`, and
+ `around`; specifying more than one will cause a
+ `hikari.errors.BadRequestHTTPError` to be raised.
"""
query = {}
conversions.put_if_specified(query, "limit", limit)
@@ -735,25 +715,24 @@ async def get_channel_message(self, channel_id: str, message_id: str) -> typing.
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to get the message from.
- message_id : :obj:`~str`
+ message_id : str
The ID of the message to retrieve.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
A message object.
- Note
- ----
- This requires the ``READ_MESSAGE_HISTORY`` permission.
+ !!! note
+ This requires the `READ_MESSAGE_HISTORY` permission.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permission to see the message.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found.
"""
route = routes.CHANNEL_MESSAGE.compile(self.GET, channel_id=channel_id, message_id=message_id)
@@ -774,45 +753,45 @@ async def create_message(
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to send to.
- content : :obj:`~str`
+ content : str
If specified, the message content to send with the message.
- nonce : :obj:`~str`
+ nonce : str
If specified, an optional ID to send for opportunistic message
creation. This doesn't serve any real purpose for general use,
and can usually be ignored.
- tts : :obj:`~bool`
+ tts : bool
If specified, whether the message will be sent as a TTS message.
- files : :obj:`~typing.Sequence` [ :obj:`~typing.Tuple` [ :obj:`~str`, :obj:`~io.IOBase` ] ]
- If specified, this should be a list of between ``1`` and ``5`` tuples.
+ files : typing.Sequence [ typing.Tuple [ str, io.IOBase ] ]
+ If specified, this should be a list of between `1` and `5` tuples.
Each tuple should consist of the file name, and either
- raw :obj:`~bytes` or an :obj:`~io.IOBase` derived object with
+ raw `bytes` or an `io.IOBase` derived object with
a seek that points to a buffer containing said file.
- embed : :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ embed : typing.Dict [ str, typing.Any ]
If specified, the embed to send with the message.
- allowed_mentions : :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
- If specified, the mentions to parse from the ``content``.
- If not specified, will parse all mentions from the ``content``.
+ allowed_mentions : typing.Dict [ str, typing.Any ]
+ If specified, the mentions to parse from the `content`.
+ If not specified, will parse all mentions from the `content`.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The created message object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
This can be raised if the file is too large; if the embed exceeds
the defined limits; if the message content is specified only and
- empty or greater than ``2000`` characters; if neither content, file
+ empty or greater than `2000` characters; if neither content, file
or embed are specified; if there is a duplicate id in only of the
- fields in ``allowed_mentions``; if you specify to parse all
+ fields in `allowed_mentions`; if you specify to parse all
users/roles mentions but also specify which users/roles to
parse only.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permissions to send to this channel.
"""
form = aiohttp.FormData()
@@ -841,24 +820,24 @@ async def create_reaction(self, channel_id: str, message_id: str, emoji: str) ->
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to add this reaction in.
- message_id : :obj:`~str`
+ message_id : str
The ID of the message to add the reaction in.
- emoji : :obj:`~str`
+ emoji : str
The emoji to add. This can either be a series of unicode
characters making up a valid Discord emoji, or it can be a the url
- representation of a custom emoji ``<{emoji.name}:{emoji.id}>``.
+ representation of a custom emoji `<{emoji.name}:{emoji.id}>`.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If this is the first reaction using this specific emoji on this
- message and you lack the ``ADD_REACTIONS`` permission. If you lack
- ``READ_MESSAGE_HISTORY``, this may also raise this error.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ message and you lack the `ADD_REACTIONS` permission. If you lack
+ `READ_MESSAGE_HISTORY`, this may also raise this error.
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found, or if the emoji is not found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If the emoji is not valid, unknown, or formatted incorrectly.
"""
route = routes.OWN_REACTION.compile(self.PUT, channel_id=channel_id, message_id=message_id, emoji=emoji)
@@ -869,20 +848,20 @@ async def delete_own_reaction(self, channel_id: str, message_id: str, emoji: str
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to get the message from.
- message_id : :obj:`~str`
+ message_id : str
The ID of the message to delete the reaction from.
- emoji : :obj:`~str`
+ emoji : str
The emoji to delete. This can either be a series of unicode
characters making up a valid Discord emoji, or it can be a
snowflake ID for a custom emoji.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permission to do this.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message or emoji is not found.
"""
route = routes.OWN_REACTION.compile(self.DELETE, channel_id=channel_id, message_id=message_id, emoji=emoji)
@@ -893,21 +872,21 @@ async def delete_all_reactions_for_emoji(self, channel_id: str, message_id: str,
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to get the message from.
- message_id : :obj:`~str`
+ message_id : str
The ID of the message to delete the reactions from.
- emoji : :obj:`~str`
+ emoji : str
The emoji to delete. This can either be a series of unicode
characters making up a valid Discord emoji, or it can be a
snowflake ID for a custom emoji.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message or emoji or user is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_MESSAGES`` permission, or are in DMs.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_MESSAGES` permission, or are in DMs.
"""
route = routes.REACTION_EMOJI.compile(self.DELETE, channel_id=channel_id, message_id=message_id, emoji=emoji)
await self._request(route)
@@ -917,23 +896,23 @@ async def delete_user_reaction(self, channel_id: str, message_id: str, emoji: st
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to get the message from.
- message_id : :obj:`~str`
+ message_id : str
The ID of the message to remove the reaction from.
- emoji : :obj:`~str`
+ emoji : str
The emoji to delete. This can either be a series of unicode
characters making up a valid Discord emoji, or it can be a
snowflake ID for a custom emoji.
- user_id : :obj:`~str`
+ user_id : str
The ID of the user who made the reaction that you wish to remove.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message or emoji or user is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_MESSAGES`` permission, or are in DMs.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_MESSAGES` permission, or are in DMs.
"""
route = routes.REACTION_EMOJI_USER.compile(
self.DELETE, channel_id=channel_id, message_id=message_id, emoji=emoji, user_id=user_id,
@@ -947,32 +926,32 @@ async def get_reactions(
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to get the message from.
- message_id : :obj:`~str`
+ message_id : str
The ID of the message to get the reactions from.
- emoji : :obj:`~str`
+ emoji : str
The emoji to get. This can either be a series of unicode
characters making up a valid Discord emoji, or it can be a
snowflake ID for a custom emoji.
- after : :obj:`~str`
+ after : str
If specified, the user ID. If specified, only users with a snowflake
that is lexicographically greater than the value will be returned.
- limit : :obj:`~str`
+ limit : str
If specified, the limit of the number of values to return. Must be
- between ``1`` and ``100`` inclusive. If unspecified,
- defaults to ``25``.
+ between `1` and `100` inclusive. If unspecified,
+ defaults to `25`.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of user objects.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack access to the message.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found.
"""
query = {}
@@ -986,17 +965,17 @@ async def delete_all_reactions(self, channel_id: str, message_id: str) -> None:
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to get the message from.
- message_id : :obj:`~str`
+ message_id : str
The ID of the message to remove all reactions from.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_MESSAGES`` permission.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_MESSAGES` permission.
"""
route = routes.ALL_REACTIONS.compile(self.DELETE, channel_id=channel_id, message_id=message_id)
await self._request(route)
@@ -1015,41 +994,41 @@ async def edit_message(
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to get the message from.
- message_id : :obj:`~str`
+ message_id : str
The ID of the message to edit.
- content : :obj:`~str`, optional
+ content : str, optional
If specified, the string content to replace with in the message.
- If :obj:`~None`, the content will be removed from the message.
- embed : :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ], optional
+ If `None`, the content will be removed from the message.
+ embed : typing.Dict [ str, typing.Any ], optional
If specified, the embed to replace with in the message.
- If :obj:`~None`, the embed will be removed from the message.
- flags : :obj:`~int`
+ If `None`, the embed will be removed from the message.
+ flags : int
If specified, the integer to replace the message's current flags.
- allowed_mentions : :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
- If specified, the mentions to parse from the ``content``.
- If not specified, will parse all mentions from the ``content``.
+ allowed_mentions : typing.Dict [ str, typing.Any ]
+ If specified, the mentions to parse from the `content`.
+ If not specified, will parse all mentions from the `content`.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The edited message object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
This can be raised if the embed exceeds the defined limits;
if the message content is specified only and empty or greater
- than ``2000`` characters; if neither content, file or embed
+ than `2000` characters; if neither content, file or embed
are specified.
parse only.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you try to edit ``content`` or ``embed`` or ``allowed_mentions`
+ hikari.errors.ForbiddenHTTPError
+ If you try to edit `content` or `embed` or `allowed_mentions`
on a message you did not author or try to edit the flags on a
- message you did not author without the ``MANAGE_MESSAGES``
+ message you did not author without the `MANAGE_MESSAGES`
permission.
"""
payload = {}
@@ -1065,17 +1044,17 @@ async def delete_message(self, channel_id: str, message_id: str) -> None:
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to get the message from.
- message_id : :obj:`~str`
+ message_id : str
The ID of the message to delete.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you did not author the message and are in a DM, or if you did not author the message and lack the
- ``MANAGE_MESSAGES`` permission in a guild channel.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ `MANAGE_MESSAGES` permission in a guild channel.
+ hikari.errors.NotFoundHTTPError
If the channel or message is not found.
"""
route = routes.CHANNEL_MESSAGE.compile(self.DELETE, channel_id=channel_id, message_id=message_id)
@@ -1086,28 +1065,27 @@ async def bulk_delete_messages(self, channel_id: str, messages: typing.Sequence[
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to get the message from.
- messages : :obj:`~typing.Sequence` [ :obj:`~str` ]
- A list of ``2-100`` message IDs to remove in the channel.
+ messages : typing.Sequence [ str ]
+ A list of `2-100` message IDs to remove in the channel.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_MESSAGES`` permission in the channel.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If any of the messages passed are older than ``2`` weeks in age or
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_MESSAGES` permission in the channel.
+ hikari.errors.BadRequestHTTPError
+ If any of the messages passed are older than `2` weeks in age or
any duplicate message IDs are passed.
- Note
- ----
- This can only be used on guild text channels.
- Any message IDs that do not exist or are invalid still add towards the
- total ``100`` max messages to remove. This can only delete messages that
- are newer than ``2`` weeks in age. If any of the messages are older than
- ``2`` weeks then this call will fail.
+ !!! note
+ This can only be used on guild text channels. Any message IDs that
+ do not exist or are invalid still add towards the total `100` max
+ messages to remove. This can only delete messages that are newer
+ than `2` weeks in age. If any of the messages are older than
+ `2` weeks then this call will fail.
"""
payload = {"messages": messages}
route = routes.CHANNEL_MESSAGES_BULK_DELETE.compile(self.POST, channel_id=channel_id)
@@ -1120,26 +1098,26 @@ async def edit_channel_permissions(
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to edit permissions for.
- overwrite_id : :obj:`~str`
+ overwrite_id : str
The overwrite ID to edit.
- type_ : :obj:`~str`
- The type of overwrite. ``"member"`` if it is for a member,
- or ``"role"`` if it is for a role.
- allow : :obj:`~int`
+ type_ : str
+ The type of overwrite. `"member"` if it is for a member,
+ or `"role"` if it is for a role.
+ allow : int
If specified, the bitwise value of all permissions to set to be allowed.
- deny : :obj:`~int`
+ deny : int
If specified, the bitwise value of all permissions to set to be denied.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the target channel or overwrite doesn't exist.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permission to do this.
"""
payload = {"type": type_}
@@ -1153,19 +1131,19 @@ async def get_channel_invites(self, channel_id: str) -> typing.Sequence[typing.D
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to get invites for.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of invite objects.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_CHANNELS`` permission.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_CHANNELS` permission.
+ hikari.errors.NotFoundHTTPError
If the channel does not exist.
"""
route = routes.CHANNEL_INVITES.compile(self.GET, channel_id=channel_id)
@@ -1187,40 +1165,40 @@ async def create_channel_invite(
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to create the invite for.
- max_age : :obj:`~int`
+ max_age : int
If specified, the max age of the invite in seconds, defaults to
- ``86400`` (``24`` hours).
- Set to ``0`` to never expire.
- max_uses : :obj:`~int`
- If specified, the max number of uses this invite can have, or ``0``
+ `86400` (`24` hours).
+ Set to `0` to never expire.
+ max_uses : int
+ If specified, the max number of uses this invite can have, or `0`
for unlimited (as per the default).
- temporary : :obj:`~bool`
+ temporary : bool
If specified, whether to grant temporary membership, meaning the
user is kicked when their session ends unless they are given a role.
- unique : :obj:`~bool`
+ unique : bool
If specified, whether to try to reuse a similar invite.
- target_user : :obj:`~str`
+ target_user : str
If specified, the ID of the user this invite should target.
- target_user_type : :obj:`~int`
+ target_user_type : int
If specified, the type of target for this invite.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
An invite object.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``CREATE_INSTANT_MESSAGES`` permission.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `CREATE_INSTANT_MESSAGES` permission.
+ hikari.errors.NotFoundHTTPError
If the channel does not exist.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If the arguments provided are not valid (e.g. negative age, etc).
"""
payload = {}
@@ -1238,34 +1216,34 @@ async def delete_channel_permission(self, channel_id: str, overwrite_id: str) ->
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to delete the overwrite from.
- overwrite_id : :obj:`~str`
+ overwrite_id : str
The ID of the overwrite to remove.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the overwrite or channel do not exist.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission for that channel.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission for that channel.
"""
route = routes.CHANNEL_PERMISSIONS.compile(self.DELETE, channel_id=channel_id, overwrite_id=overwrite_id)
await self._request(route)
async def trigger_typing_indicator(self, channel_id: str) -> None:
- """Trigger the account to appear to be typing for the next ``10`` seconds in the given channel.
+ """Trigger the account to appear to be typing for the next `10` seconds in the given channel.
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to appear to be typing in.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you are not able to type in the channel.
"""
route = routes.CHANNEL_TYPING.compile(self.POST, channel_id=channel_id)
@@ -1276,25 +1254,25 @@ async def get_pinned_messages(self, channel_id: str) -> typing.Sequence[typing.D
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The channel ID to get messages from.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of messages.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you are not able to see the channel.
- Note
- ----
- If you are not able to see the pinned message (eg. you are missing ``READ_MESSAGE_HISTORY``
- and the pinned message is an old message), it will not be returned.
+ !!! note
+ If you are not able to see the pinned message (eg. you are missing
+ `READ_MESSAGE_HISTORY` and the pinned message is an old message), it
+ will not be returned.
"""
route = routes.CHANNEL_PINS.compile(self.GET, channel_id=channel_id)
return await self._request(route)
@@ -1304,16 +1282,16 @@ async def add_pinned_channel_message(self, channel_id: str, message_id: str) ->
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to pin a message to.
- message_id : :obj:`~str`
+ message_id : str
The ID of the message to pin.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_MESSAGES`` permission.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_MESSAGES` permission.
+ hikari.errors.NotFoundHTTPError
If the message or channel do not exist.
"""
route = routes.CHANNEL_PINS.compile(self.PUT, channel_id=channel_id, message_id=message_id)
@@ -1326,16 +1304,16 @@ async def delete_pinned_channel_message(self, channel_id: str, message_id: str)
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to remove a pin from.
- message_id : :obj:`~str`
+ message_id : str
The ID of the message to unpin.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_MESSAGES`` permission.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_MESSAGES` permission.
+ hikari.errors.NotFoundHTTPError
If the message or channel do not exist.
"""
route = routes.CHANNEL_PIN.compile(self.DELETE, channel_id=channel_id, message_id=message_id)
@@ -1346,19 +1324,19 @@ async def list_guild_emojis(self, guild_id: str) -> typing.Sequence[typing.Dict[
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to get the emojis for.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of emoji objects.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you aren't a member of the guild.
"""
route = routes.GUILD_EMOJIS.compile(self.GET, guild_id=guild_id)
@@ -1369,21 +1347,21 @@ async def get_guild_emoji(self, guild_id: str, emoji_id: str) -> typing.Dict[str
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to get the emoji from.
- emoji_id : :obj:`~str`
+ emoji_id : str
The ID of the emoji to get.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
An emoji object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the emoji aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you aren't a member of said guild.
"""
route = routes.GUILD_EMOJI.compile(self.GET, guild_id=guild_id, emoji_id=emoji_id)
@@ -1396,34 +1374,34 @@ async def create_guild_emoji(
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to create the emoji in.
- name : :obj:`~str`
+ name : str
The new emoji's name.
- image : :obj:`~bytes`
- The ``128x128`` image in bytes form.
- roles : :obj:`~typing.Sequence` [ :obj:`~str` ]
+ image : bytes
+ The `128x128` image in bytes form.
+ roles : typing.Sequence [ str ]
If specified, a list of roles for which the emoji will be whitelisted.
If empty, all roles are whitelisted.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The newly created emoji object.
Raises
------
- :obj:`~ValueError`
- If ``image`` is :obj:`~None`.
- :obj:`~hikari.errors.NotFoundHTTPError`
+ ValueError
+ If `image` is `None`.
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_EMOJIS`` permission or aren't a member of said guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you attempt to upload an image larger than ``256kb``, an empty image or an invalid image format.
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_EMOJIS` permission or aren't a member of said guild.
+ hikari.errors.BadRequestHTTPError
+ If you attempt to upload an image larger than `256kb`, an empty image or an invalid image format.
"""
assertions.assert_not_none(image, "image must be a valid image")
payload = {
@@ -1441,31 +1419,31 @@ async def modify_guild_emoji(
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to which the emoji to update belongs to.
- emoji_id : :obj:`~str`
+ emoji_id : str
The ID of the emoji to update.
- name : :obj:`~str`
+ name : str
If specified, a new emoji name string. Keep unspecified to keep the name the same.
- roles : :obj:`~typing.Sequence` [ :obj:`~str` ]
+ roles : typing.Sequence [ str ]
If specified, a list of IDs for the new whitelisted roles.
Set to an empty list to whitelist all roles.
Keep unspecified to leave the same roles already set.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The updated emoji object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the emoji aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_EMOJIS`` permission or are not a member of the given guild.
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_EMOJIS` permission or are not a member of the given guild.
"""
payload = {}
conversions.put_if_specified(payload, "name", name)
@@ -1478,17 +1456,17 @@ async def delete_guild_emoji(self, guild_id: str, emoji_id: str) -> None:
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to delete the emoji from.
- emoji_id : :obj:`~str`
+ emoji_id : str
The ID of the emoji to be deleted.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the emoji aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_EMOJIS`` permission or aren't a member of said guild.
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_EMOJIS` permission or aren't a member of said guild.
"""
route = routes.GUILD_EMOJI.compile(self.DELETE, guild_id=guild_id, emoji_id=emoji_id)
await self._request(route)
@@ -1507,42 +1485,42 @@ async def create_guild(
) -> typing.Dict[str, typing.Any]:
"""Create a new guild.
- Warning
- -------
- Can only be used by bots in less than ``10`` guilds.
+ !!! warning
+ Can only be used by bots in less than `10` guilds.
Parameters
----------
- name : :obj:`~str`
- The name string for the new guild (``2-100`` characters).
- region : :obj:`~str`
+ name : str
+ The name string for the new guild (`2-100` characters).
+ region : str
If specified, the voice region ID for new guild. You can use
- :meth:`list_voice_regions` to see which region IDs are available.
- icon : :obj:`~bytes`
+ `LowLevelRestfulClient.list_voice_regions` to see which region IDs
+ are available.
+ icon : bytes
If specified, the guild icon image in bytes form.
- verification_level : :obj:`~int`
- If specified, the verification level integer (``0-5``).
- default_message_notifications : :obj:`~int`
- If specified, the default notification level integer (``0-1``).
- explicit_content_filter : :obj:`~int`
- If specified, the explicit content filter integer (``0-2``).
- roles : :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ verification_level : int
+ If specified, the verification level integer (`0-5`).
+ default_message_notifications : int
+ If specified, the default notification level integer (`0-1`).
+ explicit_content_filter : int
+ If specified, the explicit content filter integer (`0-2`).
+ roles : typing.Sequence [ typing.Dict [ str, typing.Any ] ]
If specified, an array of role objects to be created alongside the
- guild. First element changes the ``@everyone`` role.
- channels : :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ guild. First element changes the `@everyone` role.
+ channels : typing.Sequence [ typing.Dict [ str, typing.Any ] ]
If specified, an array of channel objects to be created alongside the guild.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The newly created guild object.
Raises
------
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you are on ``10`` or more guilds.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you provide unsupported fields like ``parent_id`` in channel objects.
+ hikari.errors.ForbiddenHTTPError
+ If you are on `10` or more guilds.
+ hikari.errors.BadRequestHTTPError
+ If you provide unsupported fields like `parent_id` in channel objects.
"""
payload = {"name": name}
conversions.put_if_specified(payload, "region", region)
@@ -1560,19 +1538,19 @@ async def get_guild(self, guild_id: str) -> typing.Dict[str, typing.Any]:
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to get.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The requested guild object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you don't have access to the guild.
"""
route = routes.GUILD.compile(self.GET, guild_id=guild_id)
@@ -1583,23 +1561,22 @@ async def get_guild_preview(self, guild_id: str) -> typing.Dict[str, typing.Any]
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to get the preview object of.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The requested guild preview object.
- Note
- ----
- Unlike other guild endpoints, the bot doesn't have to be in the target
- guild to get it's preview.
+ !!! note
+ Unlike other guild endpoints, the bot doesn't have to be in the
+ target guild to get it's preview.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
- If the guild is not found or it isn't ``PUBLIC``.
+ hikari.errors.NotFoundHTTPError
+ If the guild is not found or it isn't `PUBLIC`.
"""
route = routes.GUILD_PREVIEW.compile(self.GET, guild_id=guild_id)
return await self._request(route)
@@ -1626,46 +1603,47 @@ async def modify_guild( # lgtm [py/similar-function]
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to be edited.
- name : :obj:`~str`
- If specified, the new name string for the guild (``2-100`` characters).
- region : :obj:`~str`
+ name : str
+ If specified, the new name string for the guild (`2-100` characters).
+ region : str
If specified, the new voice region ID for guild. You can use
- :meth:`list_voice_regions` to see which region IDs are available.
- verification_level : :obj:`~int`
- If specified, the new verification level integer (``0-5``).
- default_message_notifications : :obj:`~int`
- If specified, the new default notification level integer (``0-1``).
- explicit_content_filter : :obj:`~int`
- If specified, the new explicit content filter integer (``0-2``).
- afk_channel_id : :obj:`~str`
+ `LowLevelRestfulClient.list_voice_regions` to see which region IDs
+ are available.
+ verification_level : int
+ If specified, the new verification level integer (`0-5`).
+ default_message_notifications : int
+ If specified, the new default notification level integer (`0-1`).
+ explicit_content_filter : int
+ If specified, the new explicit content filter integer (`0-2`).
+ afk_channel_id : str
If specified, the new ID for the AFK voice channel.
- afk_timeout : :obj:`~int`
+ afk_timeout : int
If specified, the new AFK timeout period in seconds
- icon : :obj:`~bytes`
+ icon : bytes
If specified, the new guild icon image in bytes form.
- owner_id : :obj:`~str`
+ owner_id : str
If specified, the new ID of the new guild owner.
- splash : :obj:`~bytes`
+ splash : bytes
If specified, the new new splash image in bytes form.
- system_channel_id : :obj:`~str`
+ system_channel_id : str
If specified, the new ID of the new system channel.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The edited guild object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_GUILD` permission or are not in the guild.
"""
payload = {}
conversions.put_if_specified(payload, "name", name)
@@ -1691,14 +1669,14 @@ async def delete_guild(self, guild_id: str) -> None:
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to be deleted.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you are not the guild owner.
"""
route = routes.GUILD.compile(self.DELETE, guild_id=guild_id)
@@ -1709,19 +1687,19 @@ async def list_guild_channels(self, guild_id: str) -> typing.Sequence[typing.Dic
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to get the channels from.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of channel objects.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you are not in the guild.
"""
route = routes.GUILD_CHANNELS.compile(self.GET, guild_id=guild_id)
@@ -1747,59 +1725,59 @@ async def create_guild_channel(
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to create the channel in.
- name : :obj:`~str`
+ name : str
If specified, the name for the channel.This must be
- between ``2`` and ``100`` characters in length.
- type_: :obj:`~int`
- If specified, the channel type integer (``0-6``).
- position : :obj:`~int`
+ between `2` and `100` characters in length.
+ type_: int
+ If specified, the channel type integer (`0-6`).
+ position : int
If specified, the position to change the channel to.
- topic : :obj:`~str`
+ topic : str
If specified, the topic to set. This is only applicable to
- text channels. This must be between ``0`` and ``1024``
+ text channels. This must be between `0` and `1024`
characters in length.
- nsfw : :obj:`~bool`
+ nsfw : bool
If specified, whether the channel will be marked as NSFW.
Only applicable to text channels.
- rate_limit_per_user : :obj:`~int`
+ rate_limit_per_user : int
If specified, the number of seconds the user has to wait before sending
another message. This will not apply to bots, or to members with
- ``MANAGE_MESSAGES`` or ``MANAGE_CHANNEL`` permissions. This must
- be between ``0`` and ``21600`` seconds.
- bitrate : :obj:`~int`
+ `MANAGE_MESSAGES` or `MANAGE_CHANNEL` permissions. This must
+ be between `0` and `21600` seconds.
+ bitrate : int
If specified, the bitrate in bits per second allowable for the channel.
- This only applies to voice channels and must be between ``8000``
- and ``96000`` for normal servers or ``8000`` and ``128000`` for
+ This only applies to voice channels and must be between `8000`
+ and `96000` for normal servers or `8000` and `128000` for
VIP servers.
- user_limit : :obj:`~int`
+ user_limit : int
If specified, the max number of users to allow in a voice channel.
- This must be between ``0`` and ``99`` inclusive, where
- ``0`` implies no limit.
- permission_overwrites : :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ This must be between `0` and `99` inclusive, where
+ `0` implies no limit.
+ permission_overwrites : typing.Sequence [ typing.Dict [ str, typing.Any ] ]
If specified, the list of permission overwrites that are category
specific to replace the existing overwrites with.
- parent_id : :obj:`~str`
+ parent_id : str
If specified, the parent category ID to set for the channel.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The newly created channel object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_CHANNEL`` permission or are not in the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_CHANNEL` permission or are not in the guild.
+ hikari.errors.BadRequestHTTPError
If you provide incorrect options for the corresponding channel type
- (e.g. a ``bitrate`` for a text channel).
+ (e.g. a `bitrate` for a text channel).
"""
payload = {}
conversions.put_if_specified(payload, "name", name)
@@ -1822,23 +1800,23 @@ async def modify_guild_channel_positions(
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild in which to edit the channels.
- channel : :obj:`~typing.Tuple` [ :obj:`~str`, :obj:`~int` ]
+ channel : typing.Tuple [ str, int ]
The first channel to change the position of. This is a tuple of the channel ID and the integer position.
- *channels : :obj:`~typing.Tuple` [ :obj:`~str`, :obj:`~int` ]
+ *channels : typing.Tuple [ str, int ]
Optional additional channels to change the position of. These must be tuples of the channel ID and the
integer positions to change to.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or any of the channels aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_CHANNELS`` permission or are not a member of said guild or are not in
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_CHANNELS` permission or are not a member of said guild or are not in
the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you provide anything other than the ``id`` and ``position`` fields for the channels.
+ hikari.errors.BadRequestHTTPError
+ If you provide anything other than the `id` and `position` fields for the channels.
"""
payload = [{"id": ch[0], "position": ch[1]} for ch in (channel, *channels)]
route = routes.GUILD_CHANNELS.compile(self.PATCH, guild_id=guild_id)
@@ -1849,21 +1827,21 @@ async def get_guild_member(self, guild_id: str, user_id: str) -> typing.Dict[str
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to get the member from.
- user_id : :obj:`~str`
+ user_id : str
The ID of the member to get.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The requested member object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the member aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you don't have access to the target guild.
"""
route = routes.GUILD_MEMBER.compile(self.GET, guild_id=guild_id, user_id=user_id)
@@ -1876,19 +1854,17 @@ async def list_guild_members(
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to get the members from.
- limit : :obj:`~int`
+ limit : int
If specified, the maximum number of members to return. This has to be between
- ``1`` and ``1000`` inclusive.
- after : :obj:`~str`
+ `1` and `1000` inclusive.
+ after : str
If specified, the highest ID in the previous page. This is used for retrieving more
- than ``1000`` members in a server using consecutive requests.
-
- Example
- -------
- .. code-block:: python
+ than `1000` members in a server using consecutive requests.
+ Examples
+ --------
members = []
last_id = 0
@@ -1903,17 +1879,17 @@ async def list_guild_members(
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
A list of member objects.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you are not in the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you provide invalid values for the ``limit`` or `after`` fields.
+ hikari.errors.BadRequestHTTPError
+ If you provide invalid values for the `limit` or `after` fields.
"""
query = {}
conversions.put_if_specified(query, "limit", limit)
@@ -1937,39 +1913,40 @@ async def modify_guild_member( # lgtm [py/similar-function]
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to edit the member from.
- user_id : :obj:`~str`
+ user_id : str
The ID of the member to edit.
- nick : :obj:`~str`, optional
- If specified, the new nickname string. Setting it to :obj:`~None`
+ nick : str, optional
+ If specified, the new nickname string. Setting it to None
explicitly will clear the nickname.
- roles : :obj:`~typing.Sequence` [ :obj:`~str` ]
+ roles : typing.Sequence [ str ]
If specified, a list of role IDs the member should have.
- mute : :obj:`~bool`
+ mute : bool
If specified, whether the user should be muted in the voice channel
or not.
- deaf : :obj:`~bool`
+ deaf : bool
If specified, whether the user should be deafen in the voice channel
or not.
- channel_id : :obj:`~str`
+ channel_id : str
If specified, the ID of the channel to move the member to. Setting
- it to :obj:`~None` explicitly will disconnect the user.
- reason : :obj:`~str`
+ it to None explicitly will disconnect the user.
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild, user, channel or any of the roles aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack any of the applicable permissions
- (``MANAGE_NICKNAMES``, ``MANAGE_ROLES``, ``MUTE_MEMBERS``, ``DEAFEN_MEMBERS`` or ``MOVE_MEMBERS``).
- Note that to move a member you must also have permission to connect to the end channel.
- This will also be raised if you're not in the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you pass ```mute``, ``deaf`` or ``channel_id`` while the member is not connected to a voice channel.
+ hikari.errors.ForbiddenHTTPError
+ If you lack any of the applicable permissions (`MANAGE_NICKNAMES`,
+ `MANAGE_ROLES`, `MUTE_MEMBERS`,`DEAFEN_MEMBERS` or `MOVE_MEMBERS`).
+ Note that to move a member you must also have permission to connect
+ to the end channel. This will also be raised if you're not in the
+ guild.
+ hikari.errors.BadRequestHTTPError
+ If you pass `mute`, `deaf` or `channel_id` while the member is not connected to a voice channel.
"""
payload = {}
conversions.put_if_specified(payload, "nick", nick)
@@ -1985,21 +1962,21 @@ async def modify_current_user_nick(self, guild_id: str, nick: typing.Optional[st
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild you want to change the nick on.
- nick : :obj:`~str`, optional
+ nick : str, optional
The new nick string. Setting this to `None` clears the nickname.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``CHANGE_NICKNAME`` permission or are not in the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `CHANGE_NICKNAME` permission or are not in the guild.
+ hikari.errors.BadRequestHTTPError
If you provide a disallowed nickname, one that is too long, or one that is empty.
"""
payload = {"nick": nick}
@@ -2011,22 +1988,22 @@ async def add_guild_member_role(self, guild_id: str, user_id: str, role_id: str,
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild the member belongs to.
- user_id : :obj:`~str`
+ user_id : str
The ID of the member you want to add the role to.
- role_id : :obj:`~str`
+ role_id : str
The ID of the role you want to add.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild, member or role aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission or are not in the guild.
"""
route = routes.GUILD_MEMBER_ROLE.compile(self.PUT, guild_id=guild_id, user_id=user_id, role_id=role_id)
await self._request(route, reason=reason)
@@ -2036,22 +2013,22 @@ async def remove_guild_member_role(self, guild_id: str, user_id: str, role_id: s
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild the member belongs to.
- user_id : :obj:`~str`
+ user_id : str
The ID of the member you want to remove the role from.
- role_id : :obj:`~str`
+ role_id : str
The ID of the role you want to remove.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild, member or role aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission or are not in the guild.
"""
route = routes.GUILD_MEMBER_ROLE.compile(self.DELETE, guild_id=guild_id, user_id=user_id, role_id=role_id)
await self._request(route, reason=reason)
@@ -2061,20 +2038,20 @@ async def remove_guild_member(self, guild_id: str, user_id: str, *, reason: str
Parameters
----------
- guild_id: :obj:`~str`
+ guild_id: str
The ID of the guild the member belongs to.
- user_id: :obj:`~str`
+ user_id: str
The ID of the member you want to kick.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or member aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``KICK_MEMBERS`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `KICK_MEMBERS` permission or are not in the guild.
"""
route = routes.GUILD_MEMBER.compile(self.DELETE, guild_id=guild_id, user_id=user_id)
await self._request(route, reason=reason)
@@ -2084,20 +2061,20 @@ async def get_guild_bans(self, guild_id: str) -> typing.Sequence[typing.Dict[str
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild you want to get the bans from.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of ban objects.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``BAN_MEMBERS`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `BAN_MEMBERS` permission or are not in the guild.
"""
route = routes.GUILD_BANS.compile(self.GET, guild_id=guild_id)
return await self._request(route)
@@ -2107,22 +2084,22 @@ async def get_guild_ban(self, guild_id: str, user_id: str) -> typing.Dict[str, t
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild you want to get the ban from.
- user_id : :obj:`~str`
+ user_id : str
The ID of the user to get the ban information for.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
A ban object for the requested user.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the user aren't found, or if the user is not banned.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``BAN_MEMBERS`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `BAN_MEMBERS` permission or are not in the guild.
"""
route = routes.GUILD_BAN.compile(self.GET, guild_id=guild_id, user_id=user_id)
return await self._request(route)
@@ -2134,23 +2111,23 @@ async def create_guild_ban(
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild the member belongs to.
- user_id : :obj:`~str`
+ user_id : str
The ID of the member you want to ban.
- delete_message_days : :obj:`~str`
+ delete_message_days : str
If specified, how many days of messages from the user should
be removed.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or member aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``BAN_MEMBERS`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `BAN_MEMBERS` permission or are not in the guild.
"""
query = {}
conversions.put_if_specified(query, "delete-message-days", delete_message_days)
@@ -2163,20 +2140,20 @@ async def remove_guild_ban(self, guild_id: str, user_id: str, *, reason: str = .
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to un-ban the user from.
- user_id : :obj:`~str`
+ user_id : str
The ID of the user you want to un-ban.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or member aren't found, or the member is not banned.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``BAN_MEMBERS`` permission or are not a in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `BAN_MEMBERS` permission or are not a in the guild.
"""
route = routes.GUILD_BAN.compile(self.DELETE, guild_id=guild_id, user_id=user_id)
await self._request(route, reason=reason)
@@ -2186,19 +2163,19 @@ async def get_guild_roles(self, guild_id: str) -> typing.Sequence[typing.Dict[st
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild you want to get the roles from.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of role objects.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you're not in the guild.
"""
route = routes.GUILD_ROLES.compile(self.GET, guild_id=guild_id)
@@ -2219,34 +2196,34 @@ async def create_guild_role(
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild you want to create the role on.
- name : :obj:`~str`
+ name : str
If specified, the new role name string.
- permissions : :obj:`~int`
+ permissions : int
If specified, the permissions integer for the role.
- color : :obj:`~int`
+ color : int
If specified, the color for the role.
- hoist : :obj:`~bool`
+ hoist : bool
If specified, whether the role will be hoisted.
- mentionable : :obj:`~bool`
+ mentionable : bool
If specified, whether the role will be able to be mentioned by any user.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The newly created role object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission or you're not in the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission or you're not in the guild.
+ hikari.errors.BadRequestHTTPError
If you provide invalid values for the role attributes.
"""
payload = {}
@@ -2267,25 +2244,25 @@ async def modify_guild_role_positions(
----------
guild_id : str
The ID of the guild the roles belong to.
- role : :obj:`~typing.Tuple` [ :obj:`~str`, :obj:`~int` ]
+ role : typing.Tuple [ str, int ]
The first role to move. This is a tuple of the role ID and the
integer position.
- *roles : :obj:`~typing.Tuple` [ :obj:`~str`, :obj:`~int` ]
+ *roles : typing.Tuple [ str, int ]
Optional extra roles to move. These must be tuples of the role ID
and the integer position.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of all the guild roles.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or any of the roles aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission or you're not in the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission or you're not in the guild.
+ hikari.errors.BadRequestHTTPError
If you provide invalid values for the `position` fields.
"""
payload = [{"id": r[0], "position": r[1]} for r in (role, *roles)]
@@ -2308,36 +2285,36 @@ async def modify_guild_role( # lgtm [py/similar-function]
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild the role belong to.
- role_id : :obj:`~str`
+ role_id : str
The ID of the role you want to edit.
- name : :obj:`~str`
+ name : str
If specified, the new role's name string.
- permissions : :obj:`~int`
+ permissions : int
If specified, the new permissions integer for the role.
- color : :obj:`~int`
+ color : int
If specified, the new color for the new role.
- hoist : :obj:`~bool`
+ hoist : bool
If specified, whether the role should hoist or not.
- mentionable : :obj:`~bool`
+ mentionable : bool
If specified, whether the role should be mentionable or not.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The edited role object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or role aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission or you're not in the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission or you're not in the guild.
+ hikari.errors.BadRequestHTTPError
If you provide invalid values for the role attributes.
"""
payload = {}
@@ -2354,17 +2331,17 @@ async def delete_guild_role(self, guild_id: str, role_id: str) -> None:
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild you want to remove the role from.
- role_id : :obj:`~str`
+ role_id : str
The ID of the role you want to delete.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the role aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_ROLES`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_ROLES` permission or are not in the guild.
"""
route = routes.GUILD_ROLE.compile(self.DELETE, guild_id=guild_id, role_id=role_id)
await self._request(route)
@@ -2374,23 +2351,23 @@ async def get_guild_prune_count(self, guild_id: str, days: int) -> int:
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild you want to get the count for.
- days : :obj:`~int`
- The number of days to count prune for (at least ``1``).
+ days : int
+ The number of days to count prune for (at least `1`).
Returns
-------
- :obj:`~int`
+ int
The number of members estimated to be pruned.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``KICK_MEMBERS`` or you are not in the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `KICK_MEMBERS` or you are not in the guild.
+ hikari.errors.BadRequestHTTPError
If you pass an invalid amount of days.
"""
payload = {"days": days}
@@ -2405,31 +2382,31 @@ async def begin_guild_prune(
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild you want to prune member of.
- days : :obj:`~int`
+ days : int
The number of inactivity days you want to use as filter.
- compute_prune_count : :obj:`~bool`
+ compute_prune_count : bool
Whether a count of pruned members is returned or not.
Discouraged for large guilds out of politeness.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~int`, optional
- The number of members who were kicked if ``compute_prune_count``
- is :obj:`~True`, else :obj:`~None`.
+ int, optional
+ The number of members who were kicked if `compute_prune_count`
+ is True, else None.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found:
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``KICK_MEMBER`` permission or are not in the guild.
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you provide invalid values for the ``days`` or ``compute_prune_count`` fields.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `KICK_MEMBER` permission or are not in the guild.
+ hikari.errors.BadRequestHTTPError
+ If you provide invalid values for the `days` or `compute_prune_count` fields.
"""
query = {"days": days}
conversions.put_if_specified(query, "compute_prune_count", compute_prune_count, str)
@@ -2446,19 +2423,19 @@ async def get_guild_voice_regions(self, guild_id: str) -> typing.Sequence[typing
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to get the voice regions for.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of voice region objects.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you are not in the guild.
"""
route = routes.GUILD_VOICE_REGIONS.compile(self.GET, guild_id=guild_id)
@@ -2469,20 +2446,20 @@ async def get_guild_invites(self, guild_id: str) -> typing.Sequence[typing.Dict[
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to get the invites for.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of invite objects (with metadata).
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_GUILD` permission or are not in the guild.
"""
route = routes.GUILD_INVITES.compile(self.GET, guild_id=guild_id)
return await self._request(route)
@@ -2492,20 +2469,20 @@ async def get_guild_integrations(self, guild_id: str) -> typing.Sequence[typing.
Parameters
----------
- guild_id : :obj:`~int`
+ guild_id : int
The ID of the guild to get the integrations for.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of integration objects.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_GUILD` permission or are not in the guild.
"""
route = routes.GUILD_INTEGRATIONS.compile(self.GET, guild_id=guild_id)
return await self._request(route)
@@ -2524,28 +2501,28 @@ async def modify_guild_integration(
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to which the integration belongs to.
- integration_id : :obj:`~str`
+ integration_id : str
The ID of the integration.
- expire_behaviour : :obj:`~int`
+ expire_behaviour : int
If specified, the behaviour for when an integration subscription
lapses.
- expire_grace_period : :obj:`~int`
+ expire_grace_period : int
If specified, time interval in seconds in which the integration
will ignore lapsed subscriptions.
- enable_emojis : :obj:`~bool`
+ enable_emojis : bool
If specified, whether emojis should be synced for this integration.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the integration aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_GUILD` permission or are not in the guild.
"""
payload = {}
conversions.put_if_specified(payload, "expire_behaviour", expire_behaviour)
@@ -2560,19 +2537,19 @@ async def delete_guild_integration(self, guild_id: str, integration_id: str, *,
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to which the integration belongs to.
- integration_id : :obj:`~str`
+ integration_id : str
The ID of the integration to delete.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the integration aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack the `MANAGE_GUILD` permission or are not in the guild.
"""
route = routes.GUILD_INTEGRATION.compile(self.DELETE, guild_id=guild_id, integration_id=integration_id)
@@ -2583,17 +2560,17 @@ async def sync_guild_integration(self, guild_id: str, integration_id: str) -> No
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to which the integration belongs to.
- integration_id : :obj:`~str`
+ integration_id : str
The ID of the integration to sync.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the guild or the integration aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you lack the `MANAGE_GUILD` permission or are not in the guild.
"""
route = routes.GUILD_INTEGRATION_SYNC.compile(self.POST, guild_id=guild_id, integration_id=integration_id)
await self._request(route)
@@ -2603,20 +2580,20 @@ async def get_guild_embed(self, guild_id: str) -> typing.Dict[str, typing.Any]:
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to get the embed for.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
A guild embed object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_GUILD` permission or are not in the guild.
"""
route = routes.GUILD_EMBED.compile(self.GET, guild_id=guild_id)
return await self._request(route)
@@ -2628,28 +2605,28 @@ async def modify_guild_embed(
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to edit the embed for.
- channel_id : :obj:`~str`, optional
+ channel_id : str, optional
If specified, the channel that this embed's invite should target.
- Set to :obj:`~None` to disable invites for this embed.
- enabled : :obj:`~bool`
+ Set to None to disable invites for this embed.
+ enabled : bool
If specified, whether this embed should be enabled.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The updated embed object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_GUILD` permission or are not in the guild.
"""
payload = {}
conversions.put_if_specified(payload, "channel_id", channel_id)
@@ -2662,20 +2639,20 @@ async def get_guild_vanity_url(self, guild_id: str) -> typing.Dict[str, typing.A
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to get the vanity URL for.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
- A partial invite object containing the vanity URL in the ``code`` field.
+ typing.Dict [ str, typing.Any ]
+ A partial invite object containing the vanity URL in the `code` field.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_GUILD`` permission or are not in the guild.
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_GUILD` permission or are not in the guild.
"""
route = routes.GUILD_VANITY_URL.compile(self.GET, guild_id=guild_id)
return await self._request(route)
@@ -2685,24 +2662,23 @@ def get_guild_widget_image_url(self, guild_id: str, *, style: str = ...,) -> str
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The guild ID to use for the widget.
- style : :obj:`~str`
- If specified, the syle of the widget.
+ style : str
+ If specified, the style of the widget.
Returns
-------
- :obj:`~str`
+ str
A URL to retrieve a PNG widget for your guild.
- Note
- ----
- This does not actually make any form of request, and shouldn't be awaited.
- Thus, it doesn't have rate limits either.
+ !!! note
+ This does not actually make any form of request, and shouldn't be
+ awaited. Thus, it doesn't have rate limits either.
- Warning
- -------
- The guild must have the widget enabled in the guild settings for this to be valid.
+ !!! warning
+ The guild must have the widget enabled in the guild settings for
+ this to be valid.
"""
query = "" if style is ... else f"?style={style}"
return f"{self.base_url}/guilds/{guild_id}/widget.png" + query
@@ -2712,20 +2688,20 @@ async def get_invite(self, invite_code: str, *, with_counts: bool = ...) -> typi
Parameters
----------
- invite_code : :obj:`~str`
+ invite_code : str
The ID for wanted invite.
- with_counts : :obj:`~bool`
+ with_counts : bool
If specified, whether to attempt to count the number of
times the invite has been used.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The requested invite object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the invite is not found.
"""
query = {}
@@ -2738,22 +2714,22 @@ async def delete_invite(self, invite_code: str) -> None:
Parameters
----------
- invite_code : :obj:`~str`
+ invite_code : str
The ID for the invite to be deleted.
Returns
-------
- :obj:`~None` # Marker
+ None # Marker
Nothing, unlike what the API specifies. This is done to maintain
consistency with other calls of a similar nature in this API wrapper.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the invite is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you lack either ``MANAGE_CHANNELS`` on the channel the invite
- belongs to or ``MANAGE_GUILD`` for guild-global delete.
+ hikari.errors.ForbiddenHTTPError
+ If you lack either `MANAGE_CHANNELS` on the channel the invite
+ belongs to or `MANAGE_GUILD` for guild-global delete.
"""
route = routes.INVITE.compile(self.DELETE, invite_code=invite_code)
return await self._request(route)
@@ -2763,7 +2739,7 @@ async def get_current_user(self) -> typing.Dict[str, typing.Any]:
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The current user object.
"""
route = routes.OWN_USER.compile(self.GET)
@@ -2774,17 +2750,17 @@ async def get_user(self, user_id: str) -> typing.Dict[str, typing.Any]:
Parameters
----------
- user_id : :obj:`~str`
+ user_id : str
The ID of the user to get.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The requested user object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the user is not found.
"""
route = routes.USER.compile(self.GET, user_id=user_id)
@@ -2797,21 +2773,21 @@ async def modify_current_user(
Parameters
----------
- username : :obj:`~str`
+ username : str
If specified, the new username string.
- avatar : :obj:`~bytes`, optional
+ avatar : bytes, optional
If specified, the new avatar image in bytes form.
- If it is :obj:`~None`, the avatar is removed.
+ If it is None, the avatar is removed.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The updated user object.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you pass username longer than the limit (``2-32``) or an invalid image.
+ hikari.errors.BadRequestHTTPError
+ If you pass username longer than the limit (`2-32`) or an invalid image.
"""
payload = {}
conversions.put_if_specified(payload, "username", username)
@@ -2822,13 +2798,13 @@ async def modify_current_user(
async def get_current_user_connections(self) -> typing.Sequence[typing.Dict[str, typing.Any]]:
"""Get the current user's connections.
- This endpoint can be used with both ``Bearer`` and ``Bot`` tokens but
+ This endpoint can be used with both `Bearer` and `Bot` tokens but
will usually return an empty list for bots (with there being some exceptions
to this, like user accounts that have been converted to bots).
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of connection objects.
"""
route = routes.OWN_CONNECTIONS.compile(self.GET)
@@ -2841,26 +2817,26 @@ async def get_current_user_guilds(
Parameters
----------
- before : :obj:`~str`
+ before : str
If specified, the guild ID to get guilds before it.
- after : :obj:`~str`
+ after : str
If specified, the guild ID to get guilds after it.
- limit : :obj:`~int`
+ limit : int
If specified, the limit of guilds to get. Has to be between
- ``1`` and ``100``.
+ `1` and `100`.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of partial guild objects.
Raises
------
- :obj:`~hikari.errors.BadRequestHTTPError`
- If you pass both ``before`` and ``after`` or an
- invalid value for ``limit``.
+ hikari.errors.BadRequestHTTPError
+ If you pass both `before` and `after` or an
+ invalid value for `limit`.
"""
query = {}
conversions.put_if_specified(query, "before", before)
@@ -2874,12 +2850,12 @@ async def leave_guild(self, guild_id: str) -> None:
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID of the guild to leave.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
"""
route = routes.LEAVE_GUILD.compile(self.DELETE, guild_id=guild_id)
@@ -2890,17 +2866,17 @@ async def create_dm(self, recipient_id: str) -> typing.Dict[str, typing.Any]:
Parameters
----------
- recipient_id : :obj:`~str`
+ recipient_id : str
The ID of the user to create the new DM channel with.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The newly created DM channel object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the recipient is not found.
"""
payload = {"recipient_id": recipient_id}
@@ -2912,12 +2888,11 @@ async def list_voice_regions(self) -> typing.Sequence[typing.Dict[str, typing.An
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of voice regions available
- Note
- ----
- This does not include VIP servers.
+ !!! note
+ This does not include VIP servers.
"""
route = routes.VOICE_REGIONS.compile(self.GET)
return await self._request(route)
@@ -2929,29 +2904,29 @@ async def create_webhook(
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel for webhook to be created in.
- name : :obj:`~str`
+ name : str
The webhook's name string.
- avatar : :obj:`~bytes`
+ avatar : bytes
If specified, the avatar image in bytes form.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The newly created webhook object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_WEBHOOKS`` permission or
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_WEBHOOKS` permission or
can not see the given channel.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
If the avatar image is too big or the format is invalid.
"""
payload = {"name": name}
@@ -2964,20 +2939,20 @@ async def get_channel_webhooks(self, channel_id: str) -> typing.Sequence[typing.
Parameters
----------
- channel_id : :obj:`~str`
+ channel_id : str
The ID of the channel to get the webhooks from.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of webhook objects for the give channel.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_WEBHOOKS`` permission or
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_WEBHOOKS` permission or
can not see the given channel.
"""
route = routes.CHANNEL_WEBHOOKS.compile(self.GET, channel_id=channel_id)
@@ -2988,20 +2963,20 @@ async def get_guild_webhooks(self, guild_id: str) -> typing.Sequence[typing.Dict
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The ID for the guild to get the webhooks from.
Returns
-------
- :obj:`~typing.Sequence` [ :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ] ]
+ typing.Sequence [ typing.Dict [ str, typing.Any ] ]
A list of webhook objects for the given guild.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the guild is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_WEBHOOKS`` permission or
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_WEBHOOKS` permission or
aren't a member of the given guild.
"""
route = routes.GUILD_WEBHOOKS.compile(self.GET, guild_id=guild_id)
@@ -3012,24 +2987,24 @@ async def get_webhook(self, webhook_id: str, *, webhook_token: str = ...) -> typ
Parameters
----------
- webhook_id : :obj:`~str`
+ webhook_id : str
The ID of the webhook to get.
- webhook_token : :obj:`~str`
+ webhook_token : str
If specified, the webhook token to use to get it (bypassing bot authorization).
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The requested webhook object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the webhook is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you're not in the guild that owns this webhook or
- lack the ``MANAGE_WEBHOOKS`` permission.
- :obj:`~hikari.errors.UnauthorizedHTTPError`
+ lack the `MANAGE_WEBHOOKS` permission.
+ hikari.errors.UnauthorizedHTTPError
If you pass a token that's invalid for the target webhook.
"""
if webhook_token is ...:
@@ -3052,35 +3027,35 @@ async def modify_webhook(
Parameters
----------
- webhook_id : :obj:`~str`
+ webhook_id : str
The ID of the webhook to edit.
- webhook_token : :obj:`~str`
+ webhook_token : str
If specified, the webhook token to use to modify it (bypassing bot authorization).
- name : :obj:`~str`
+ name : str
If specified, the new name string.
- avatar : :obj:`~bytes`
+ avatar : bytes
If specified, the new avatar image in bytes form. If None, then
it is removed.
- channel_id : :obj:`~str`
+ channel_id : str
If specified, the ID of the new channel the given
webhook should be moved to.
- reason : :obj:`~str`
+ reason : str
If specified, the audit log reason explaining why the operation
was performed.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
The updated webhook object.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If either the webhook or the channel aren't found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_WEBHOOKS`` permission or
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_WEBHOOKS` permission or
aren't a member of the guild this webhook belongs to.
- :obj:`~hikari.errors.UnauthorizedHTTPError`
+ hikari.errors.UnauthorizedHTTPError
If you pass a token that's invalid for the target webhook.
"""
payload = {}
@@ -3100,20 +3075,20 @@ async def delete_webhook(self, webhook_id: str, *, webhook_token: str = ...) ->
Parameters
----------
- webhook_id : :obj:`~str`
+ webhook_id : str
The ID of the webhook to delete
- webhook_token : :obj:`~str`
+ webhook_token : str
If specified, the webhook token to use to
delete it (bypassing bot authorization).
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the webhook is not found.
- :obj:`~hikari.errors.ForbiddenHTTPError`
- If you either lack the ``MANAGE_WEBHOOKS`` permission or
+ hikari.errors.ForbiddenHTTPError
+ If you either lack the `MANAGE_WEBHOOKS` permission or
aren't a member of the guild this webhook belongs to.
- :obj:`~hikari.errors.UnauthorizedHTTPError`
+ hikari.errors.UnauthorizedHTTPError
If you pass a token that's invalid for the target webhook.
"""
if webhook_token is ...:
@@ -3140,55 +3115,55 @@ async def execute_webhook(
Parameters
----------
- webhook_id : :obj:`~str`
+ webhook_id : str
The ID of the webhook to execute.
- webhook_token : :obj:`~str`
+ webhook_token : str
The token of the webhook to execute.
- content : :obj:`~str`
+ content : str
If specified, the webhook message content to send.
- username : :obj:`~str`
+ username : str
If specified, the username to override the webhook's username
for this request.
- avatar_url : :obj:`~str`
+ avatar_url : str
If specified, the url of an image to override the webhook's
avatar with for this request.
- tts : :obj:`~bool`
+ tts : bool
If specified, whether this webhook should create a TTS message.
- wait : :obj:`~bool`
+ wait : bool
If specified, whether this request should wait for the webhook
to be executed and return the resultant message object.
- file : :obj:`~typing.Tuple` [ :obj:`~str`, :obj:`~io.IOBase` ]
- If specified, a tuple of the file name and either raw :obj:`~bytes`
- or a :obj:`~io.IOBase` derived object that points to a buffer
+ file : typing.Tuple [ str, io.IOBase ]
+ If specified, a tuple of the file name and either raw `bytes`
+ or a `io.IOBase` derived object that points to a buffer
containing said file.
- embeds : :obj:`~typing.Sequence` [:obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]]
+ embeds : typing.Sequence [typing.Dict [ str, typing.Any ]]
If specified, the sequence of embed objects that will be sent
with this message.
- allowed_mentions : :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
- If specified, the mentions to parse from the ``content``.
- If not specified, will parse all mentions from the ``content``.
+ allowed_mentions : typing.Dict [ str, typing.Any ]
+ If specified, the mentions to parse from the `content`.
+ If not specified, will parse all mentions from the `content`.
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ], optional
- The created message object if ``wait`` is :obj:`~True`, else
- :obj:`~None`.
+ typing.Dict [ str, typing.Any ], optional
+ The created message object if `wait` is `True`, else
+ `None`.
Raises
------
- :obj:`~hikari.errors.NotFoundHTTPError`
+ hikari.errors.NotFoundHTTPError
If the channel ID or webhook ID is not found.
- :obj:`~hikari.errors.BadRequestHTTPError`
+ hikari.errors.BadRequestHTTPError
This can be raised if the file is too large; if the embed exceeds
the defined limits; if the message content is specified only and
- empty or greater than ``2000`` characters; if neither content, file
+ empty or greater than `2000` characters; if neither content, file
or embed are specified; if there is a duplicate id in only of the
- fields in ``allowed_mentions``; if you specify to parse all
+ fields in `allowed_mentions`; if you specify to parse all
users/roles mentions but also specify which users/roles to parse
only.
- :obj:`~hikari.errors.ForbiddenHTTPError`
+ hikari.errors.ForbiddenHTTPError
If you lack permissions to send to this channel.
- :obj:`~hikari.errors.UnauthorizedHTTPError`
+ hikari.errors.UnauthorizedHTTPError
If you pass a token that's invalid for the target webhook.
"""
form = aiohttp.FormData()
@@ -3232,7 +3207,7 @@ async def get_current_application_info(self) -> typing.Dict[str, typing.Any]:
Returns
-------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~typing.Any` ]
+ typing.Dict [ str, typing.Any ]
An application info object.
"""
route = routes.OAUTH2_APPLICATIONS_ME.compile(self.GET)
diff --git a/hikari/net/routes.py b/hikari/net/routes.py
index 32908cb611..c2a1af8133 100644
--- a/hikari/net/routes.py
+++ b/hikari/net/routes.py
@@ -29,35 +29,27 @@ class CompiledRoute:
Parameters
----------
- method : :obj:`~str`
+ method : str
The HTTP method to use.
- path : :obj:`~str`
+ path : str
The path with any major parameters interpolated in.
- major_params_hash : :obj:`~str`
+ major_params_hash : str
The part of the hash identifier to use for the compiled set of major parameters.
"""
__slots__ = ("method", "major_params_hash", "compiled_path", "hash_code", "__weakref__")
- #: The method to use on the route.
- #:
- #: :type: :obj:`~str`
method: typing.Final[str]
+ """The method to use on the route."""
- #: The major parameters in a bucket hash-compatible representation.
- #:
- #: :type: :obj:`~str`
major_params_hash: typing.Final[str]
+ """The major parameters in a bucket hash-compatible representation."""
- #: The compiled route path to use
- #:
- #: :type: :obj:`~str`
compiled_path: typing.Final[str]
+ """The compiled route path to use."""
- #: The hash code
- #:
- #: :type: :obj:`~int`
hash_code: typing.Final[int]
+ """The hash code."""
def __init__(self, method: str, path_template: str, path: str, major_params_hash: str) -> None:
self.method = method
@@ -70,12 +62,12 @@ def create_url(self, base_url: str) -> str:
Parameters
----------
- base_url : :obj:`~str`
+ base_url : str
The base of the URL to prepend to the compiled path.
Returns
-------
- :obj:`~str`
+ str
The full URL for the route.
"""
return base_url + self.compiled_path
@@ -88,13 +80,13 @@ def create_real_bucket_hash(self, initial_bucket_hash: str) -> str:
Parameters
----------
- initial_bucket_hash: :obj:`~str`
+ initial_bucket_hash : str
The initial bucket hash provided by Discord in the HTTP headers
for a given response.
Returns
-------
- :obj:`~str`
+ str
The input hash amalgamated with a hash code produced by the
major parameters in this compiled route instance.
"""
@@ -128,9 +120,9 @@ class RouteTemplate:
Parameters
----------
- path_template : :obj:`~str`
+ path_template : str
The template string for the path to use.
- major_params : :obj:`~str`
+ major_params : str
A collection of major parameter names that appear in the template path.
If not specified, the default major parameter names are extracted and
used in-place.
@@ -138,15 +130,11 @@ class RouteTemplate:
__slots__ = ("path_template", "major_params")
- #: The template string used for the path.
- #:
- #: :type: :obj:`~str`
path_template: typing.Final[str]
+ """The template string used for the path."""
- #: Major parameter names that appear in the template path.
- #:
- #: :type: :obj:`~typing.FrozenSet` [ :obj:`~str` ]
major_params: typing.Final[typing.FrozenSet[str]]
+ """Major parameter names that appear in the template path."""
def __init__(self, path_template: str, major_params: typing.Collection[str] = None) -> None:
self.path_template = path_template
@@ -156,21 +144,22 @@ def __init__(self, path_template: str, major_params: typing.Collection[str] = No
self.major_params = frozenset(major_params)
def compile(self, method: str, /, **kwargs: typing.Any) -> CompiledRoute:
- """Generate a formatted :obj:`~CompiledRoute` for this route template.
+ """Generate a formatted `CompiledRoute` for this route template.
- This takes into account any URL parameters that have been passed, and extracting
- the :attr:major_params" for bucket hash operations accordingly.
+ This takes into account any URL parameters that have been passed, and
+ extracting the `RouteTemplate.major_params` for bucket hash operations
+ accordingly.
Parameters
----------
- method : :obj:`~str`
+ method : str
The method to use.
- **kwargs : :obj:`~typing.Any`
+ **kwargs : typing.Any
Any parameters to interpolate into the route path.
Returns
-------
- :obj:`~CompiledRoute`
+ CompiledRoute
The compiled route.
"""
major_hash_part = "-".join((str(kwargs[p]) for p in self.major_params))
diff --git a/hikari/net/shards.py b/hikari/net/shards.py
index 7554747749..b055d7e02d 100644
--- a/hikari/net/shards.py
+++ b/hikari/net/shards.py
@@ -26,9 +26,9 @@
See Also
--------
-* IANA WS closure code standards: https://www.iana.org/assignments/websocket/websocket.xhtml
-* Gateway documentation: https://discordapp.com/developers/docs/topics/gateway
-* Opcode documentation: https://discordapp.com/developers/docs/topics/opcodes-and-status-codes
+* [IANA WS closure code standards](https://www.iana.org/assignments/websocket/websocket.xhtml)
+* [Gateway documentation](https://discordapp.com/developers/docs/topics/gateway)
+* [Opcode documentation](https://discordapp.com/developers/docs/topics/opcodes-and-status-codes)
"""
__all__ = ["Shard"]
@@ -53,8 +53,8 @@
from hikari.net import ratelimits
from hikari.net import user_agents
-#: The signature for an event dispatch callback.
DispatchT = typing.Callable[["Shard", str, typing.Dict], None]
+"""The signature for an event dispatch callback."""
VERSION_6: typing.Final[int] = 6
@@ -68,92 +68,88 @@ class Shard:
application of events that occur, and to allow you to change your presence,
amongst other real-time applications.
- Each :obj:`~Shard` represents a single shard.
+ Each `Shard` represents a single shard.
Expected events that may be passed to the event dispatcher are documented in the
- `gateway event reference `_.
+ [gateway event reference](https://discordapp.com/developers/docs/topics/gateway#commands-and-events) .
No normalization of the gateway event names occurs. In addition to this,
some internal events can also be triggered to notify you of changes to
the connection state.
- * ``CONNECTED`` - fired on initial connection to Discord.
- * ``DISCONNECTED`` - fired when the connection is closed for any reason.
+ * `CONNECTED` - fired on initial connection to Discord.
+ * `DISCONNECTED` - fired when the connection is closed for any reason.
Parameters
----------
- compression: :obj:`~bool`
- If True, then payload compression is enabled on the connection.
- If False, no payloads are compressed. You usually want to keep this
+ compression : bool
+ If `True`, then payload compression is enabled on the connection.
+ If `False`, no payloads are compressed. You usually want to keep this
enabled.
- connector: :obj:`~aiohttp.BaseConnector`, optional
- The :obj:`~aiohttp.BaseConnector` to use for the HTTP session that
+ connector : aiohttp.BaseConnector, optional
+ The `aiohttp.BaseConnector` to use for the HTTP session that
gets upgraded to a websocket connection. You can use this to customise
connection pooling, etc.
- debug: :obj:`~bool`
- If True, the client is configured to provide extra contextual
+ debug : bool
+ If `True`, the client is configured to provide extra contextual
information to use when debugging this library or extending it. This
includes logging every payload that is sent or received to the logger
as debug entries. Generally it is best to keep this disabled.
- dispatch: ``dispatch function``
+ dispatch : `dispatch function`
The function to invoke with any dispatched events. This must not be a
coroutine function, and must take three arguments only. The first is
- the reference to this :obj:`~Shard` The second is the
+ the reference to this `Shard` The second is the
event name.
- initial_presence: :obj:`~typing.Dict`, optional
- A raw JSON object as a :obj:`~typing.Dict` that should be set as the
- initial presence of the bot user once online. If :obj:`~None`, then it
+ initial_presence : typing.Dict, optional
+ A raw JSON object as a `typing.Dict` that should be set as the
+ initial presence of the bot user once online. If `None`, then it
will be set to the default, which is showing up as online without a
custom status message.
- intents: :obj:`~hikari.intents.Intent`, optional
+ intents : hikari.intents.Intent, optional
Bitfield of intents to use. If you use the V7 API, this is mandatory.
This field will determine what events you will receive.
- json_deserialize: ``deserialization function``
- A custom JSON deserializer function to use. Defaults to
- :func:`json.loads`.
- json_serialize: ``serialization function``
- A custom JSON serializer function to use. Defaults to
- :func:`json.dumps`.
- large_threshold: :obj:`~int`
+ json_deserialize : `deserialization function`
+ A custom JSON deserializer function to use. Defaults to `json.loads`.
+ json_serialize : `serialization function`
+ A custom JSON serializer function to use. Defaults to `json.dumps`.
+ large_threshold : int
The number of members that have to be in a guild for it to be
considered to be "large". Large guilds will not have member information
sent automatically, and must manually request that member chunks be
- sent using :meth:`request_guild_members`.
- proxy_auth: :obj:`~aiohttp.BasicAuth`, optional
- Optional :obj:`~aiohttp.BasicAuth` object that can be provided to
- allow authenticating with a proxy if you use one. Leave :obj:`~None` to
- ignore.
- proxy_headers: :obj:`~typing.Mapping` [ :obj:`~str`, :obj:`~str` ], optional
- Optional :obj:`~typing.Mapping` to provide as headers to allow the
- connection through a proxy if you use one. Leave :obj:`~None` to ignore.
- proxy_url: :obj:`~str`, optional
- Optional :obj:`~str` to use for a proxy server. If :obj:`~None`, then it
- is ignored.
- session_id: :obj:`~str`, optional
- The session ID to use. If specified along with ``seq``, then the
- gateway client will attempt to ``RESUME`` an existing session rather than
- re-``IDENTIFY``. Otherwise, it will be ignored.
- seq: :obj:`~int`, optional
- The sequence number to use. If specified along with ``session_id``, then
- the gateway client will attempt to ``RESUME`` an existing session rather
- than re-``IDENTIFY``. Otherwise, it will be ignored.
- shard_id: :obj:`~int`
- The shard ID of this gateway client. Defaults to ``0``.
- shard_count: :obj:`~int`
- The number of shards on this gateway. Defaults to ``1``, which implies no
+ sent using `ShardConnection.request_guild_members`.
+ proxy_auth : aiohttp.BasicAuth, optional
+ Optional `aiohttp.BasicAuth` object that can be provided to
+ allow authenticating with a proxy if you use one. Leave `None` to ignore.
+ proxy_headers : typing.Mapping [ str, str ], optional
+ Optional `typing.Mapping` to provide as headers to allow the
+ connection through a proxy if you use one. Leave `None` to ignore.
+ proxy_url : str, optional
+ Optional `str` to use for a proxy server. If `None`, then it is ignored.
+ session_id : str, optional
+ The session ID to use. If specified along with `seq`, then the
+ gateway client will attempt to `RESUME` an existing session rather than
+ re-`IDENTIFY`. Otherwise, it will be ignored.
+ seq : int, optional
+ The sequence number to use. If specified along with `session_id`, then
+ the gateway client will attempt to `RESUME` an existing session rather
+ than re-`IDENTIFY`. Otherwise, it will be ignored.
+ shard_id : int
+ The shard ID of this gateway client. Defaults to `0`.
+ shard_count : int
+ The number of shards on this gateway. Defaults to `1`, which implies no
sharding is taking place.
- ssl_context: :obj:`~ssl.SSLContext`, optional
- An optional custom :obj:`~ssl.SSLContext` to provide to customise how
+ ssl_context : ssl.SSLContext, optional
+ An optional custom `ssl.SSLContext` to provide to customise how
SSL works.
- token: :obj:`~str`
+ token : str
The mandatory bot token for the bot account to use, minus the "Bot"
authentication prefix used elsewhere.
- url: :obj:`~str`
+ url : str
The websocket URL to use.
- verify_ssl: :obj:`~bool`
- If :obj:`~True`, SSL verification is enabled, which is generally what you
+ verify_ssl : bool
+ If `True`, SSL verification is enabled, which is generally what you
want. If you get SSL issues, you can try turning this off at your own
risk.
- version: :obj:`~int`
+ version : int
The version of the API to use. Defaults to the most recent stable
version (v6).
"""
@@ -221,119 +217,103 @@ class Shard:
_ws: typing.Optional[aiohttp.ClientWebSocketResponse]
_zlib: typing.Optional[zlib.decompressobj]
- #: An event that is set when the connection closes.
- #:
- #: :type: :obj:`~asyncio.Event`
closed_event: typing.Final[asyncio.Event]
+ """An event that is set when the connection closes."""
- #: The number of times we have disconnected from the gateway on this
- #: client instance.
- #:
- #: :type: :obj:`~int`
disconnect_count: int
+ """The number of times we have disconnected from the gateway on this
+ client instance.
+ """
- #: The dispatch method to call when dispatching a new event. This is
- #: the method passed in the constructor.
dispatch: DispatchT
+ """The dispatch method to call when dispatching a new event.
+
+ This is the method passed in the constructor.
+ """
- #: The heartbeat interval Discord instructed the client to beat at.
- #: This is ``nan`` until this information is received.
- #:
- #: :type: :obj:`~float`
heartbeat_interval: float
+ """The heartbeat interval Discord instructed the client to beat at.
+
+ This is `nan` until this information is received.
+ """
- #: The most recent heartbeat latency measurement in seconds. This is
- #: ``nan`` until this information is available. The latency is calculated
- #: as the time between sending a ``HEARTBEAT`` payload and receiving a
- #: ``HEARTBEAT_ACK`` response.
- #:
- #: :type: :obj:`~float`
heartbeat_latency: float
+ """The most recent heartbeat latency measurement in seconds.
+
+ This is `nan` until this information is available. The latency is calculated
+ as the time between sending a `HEARTBEAT` payload and receiving a
+ `HEARTBEAT_ACK` response.
+ """
- #: An event that is set when Discord sends a ``HELLO`` payload. This
- #: indicates some sort of connection has successfully been made.
- #:
- #: :type: :obj:`~asyncio.Event`
hello_event: typing.Final[asyncio.Event]
+ """An event that is set when Discord sends a `HELLO` payload.
+
+ This indicates some sort of connection has successfully been made.
+ """
- #: An event that is set when the client has successfully ``IDENTIFY``ed
- #: or ``RESUMED`` with the gateway. This indicates regular communication
- #: can now take place on the connection and events can be expected to
- #: be received.
- #:
- #: :type: :obj:`~asyncio.Event`
handshake_event: typing.Final[asyncio.Event]
+ """An event that is set when the client has successfully `IDENTIFY`ed
+ or `RESUMED` with the gateway.
+
+ This indicates regular communication can now take place on the connection
+ and events can be expected to be received.
+ """
- #: The monotonic timestamp that the last ``HEARTBEAT`` was sent at, or
- #: ``nan`` if no ``HEARTBEAT`` has yet been sent.
- #:
- #: :type: :obj:`~float`
last_heartbeat_sent: float
+ """The monotonic timestamp that the last `HEARTBEAT` was sent at.
+
+ This will be `nan` if no `HEARTBEAT` has yet been sent.
+ """
- #: The monotonic timestamp at which the last payload was received from
- #: Discord. If this was more than the ``heartbeat_interval`` from
- #: the current time, then the connection is assumed to be zombied and
- #: is shut down. If no messages have been received yet, this is ``nan``.
- #:
- #: :type: :obj:`~float`
last_message_received: float
+ """The monotonic timestamp at which the last payload was received from Discord.
+
+ If this was more than the `heartbeat_interval` from the current time, then
+ the connection is assumed to be zombied and is shut down.
+ If no messages have been received yet, this is `nan`.
+ """
- #: The logger used for dumping information about what this client is doing.
- #:
- #: :type: :obj:`~logging.Logger`
logger: typing.Final[logging.Logger]
+ """The logger used for dumping information about what this client is doing."""
- #: An event that is triggered when a ``READY`` payload is received for the
- #: shard. This indicates that it successfully started up and had a correct
- #: sharding configuration. This is more appropriate to wait for than
- #: :attr:`identify_event` since the former will still fire if starting
- #: shards too closely together, for example. This would still lead to an
- #: immediate invalid session being fired afterwards.
- #
- #: It is worth noting that this event is only set for the first ``READY``
- #: event after connecting with a fresh connection. For all other purposes,
- #: you should wait for the event to be fired in the ``dispatch`` function
- #: you provide.
- #:
- #: :type: :obj:`~asyncio.Event`
ready_event: typing.Final[asyncio.Event]
+ """An event that is triggered when a `READY` payload is received for the shard.
+
+ This indicates that it successfully started up and had a correct sharding
+ configuration. This is more appropriate to wait for than
+ `Shard.handshake_event` since the former will still fire if starting
+ shards too closely together, for example. This would still lead to an
+ immediate invalid session being fired afterwards.
+
+ It is worth noting that this event is only set for the first `READY` event
+ after connecting with a fresh connection. For all other purposes, you should
+ wait for the event to be fired in the `dispatch` function you provide.
+ """
- #: An event that is triggered when a resume has succeeded on the gateway.
- #:
- #: :type: :obj:`~asyncio.Event`
resumed_event: typing.Final[asyncio.Event]
+ """An event that is triggered when a resume has succeeded on the gateway."""
- #: An event that is set when something requests that the connection
- #: should close somewhere.
- #:
- #: :type: :obj:`~asyncio.Event`
requesting_close_event: typing.Final[asyncio.Event]
+ """An event that is set when something requests that the connection should
+ close somewhere.
+ """
- #: The current session ID, if known.
- #:
- #: :type: :obj:`~str`, optional
session_id: typing.Optional[str]
+ """The current session ID, if known."""
- #: The current sequence number for state synchronization with the API,
- #: if known.
- #:
- #: :type: :obj:`~int`, optional.
seq: typing.Optional[int]
+ """The current sequence number for state synchronization with the API,
+ if known.
+ """
- #: The shard ID.
- #:
- #: :type: :obj:`~int`
shard_id: typing.Final[int]
+ """The shard ID."""
- #: The number of shards in use for the bot.
- #:
- #: :type: :obj:`~int`
shard_count: typing.Final[int]
+ """The number of shards in use for the bot."""
- #: The API version to use on Discord.
- #:
- #: :type: :obj:`~int`
version: typing.Final[int]
+ """The API version to use on Discord."""
def __init__(
self,
@@ -415,54 +395,33 @@ def __init__(
def uptime(self) -> datetime.timedelta:
"""Amount of time the connection has been running for.
- Returns
- -------
- :obj:`~datetime.timedelta`
- The amount of time the connection has been running for. If it isn't
- running, this will always return ``0`` seconds.
+ If this connection isn't running, this will always be `0` seconds.
"""
delta = time.perf_counter() - self._connected_at
return datetime.timedelta(seconds=0 if math.isnan(delta) else delta)
@property
def is_connected(self) -> bool:
- """Whether the gateway is connected or not.
-
- Returns
- -------
- :obj:`~bool`
- True if this gateway client is actively connected to something, or
- False if it is not running.
- """
+ """Whether the gateway is connected or not."""
return not math.isnan(self._connected_at)
@property
def intents(self) -> typing.Optional[_intents.Intent]:
"""Intents being used.
- If this is :obj:`~None`, no intent usage was being
- used on this shard. On V6 this would be regular usage as prior to
- the intents change in January 2020. If on V7, you just won't be
- able to connect at all to the gateway.
-
- Returns
- -------
- :obj:`~hikari.intents.Intent`, optional
- The intents being used.
+ If this is `None`, no intent usage was being used on this shard.
+ On V6 this would be regular usage as prior to the intents change in
+ January 2020. If on V7, you just won't be able to connect at all to the
+ gateway.
"""
return self._intents
@property
def reconnect_count(self) -> int:
- """Reconnection count for this shard connection instance.
+ """Amount of times the gateway has reconnected since initialization.
This can be used as a debugging context, but is also used internally
for exception management.
-
- Returns
- -------
- :obj:`~int`
- The amount of times the gateway has reconnected since initialization.
"""
# 0 disconnects + not is_connected => 0
# 0 disconnects + is_connected => 0
@@ -475,13 +434,7 @@ def reconnect_count(self) -> int:
# Ignore docstring not starting in an imperative mood
@property
def current_presence(self) -> typing.Dict: # noqa: D401
- """Current presence for the gateway.
-
- Returns
- -------
- :obj:`~typing.Dict`
- The current presence for the gateway.
- """
+ """Current presence for the gateway."""
# Make a shallow copy to prevent mutation.
return dict(self._presence or {})
@@ -497,35 +450,35 @@ async def request_guild_members(self, guild_id, *guild_ids, **kwargs):
"""Request the guild members for a guild or set of guilds.
These guilds must be being served by this shard, and the results will be
- provided to the dispatcher with ``GUILD_MEMBER_CHUNK`` events.
+ provided to the dispatcher with `GUILD_MEMBER_CHUNK` events.
Parameters
----------
- guild_id : :obj:`~str`
+ guild_id : str
The first guild to request members for.
- *guild_ids : :obj:`~str`
+ *guild_ids : str
Additional guilds to request members for.
**kwargs
Optional arguments.
Keyword Args
------------
- limit : :obj:`~int`
- Limit for the number of members to respond with. Set to ``0`` to be
+ limit : int
+ Limit for the number of members to respond with. Set to `0` to be
unlimited.
- query : :obj:`~str`
+ query : str
An optional string to filter members with. If specified, only
members who have a username starting with this string will be
returned.
- user_ids : :obj:`~typing.Sequence` [ :obj:`~str` ]
+ user_ids : typing.Sequence [ str ]
An optional list of user IDs to return member info about.
- Note
- ----
- You may not specify ``user_ids`` at the same time as ``limit`` and
- ``query``. Likewise, if you specify one of ``limit`` or ``query``,
- the other must also be included. The default, if no optional arguments
- are specified, is to use a ``limit = 0`` and a ``query = ""`` (empty-string).
+ !!! note
+ You may not specify `user_id` at the same time as `limit` and
+ `query`. Likewise, if you specify one of `limit` or `query`, the
+ other must also be included. The default, if no optional arguments
+ are specified, is to use a `limit = 0` and a `query = ""`
+ (empty-string).
"""
guilds = [guild_id, *guild_ids]
constraints = {}
@@ -550,7 +503,7 @@ async def update_presence(self, presence: typing.Dict) -> None:
Parameters
----------
- presence : :obj:`~typing.Dict`
+ presence : typing.Dict
The new presence payload to set.
"""
presence.setdefault("since", None)
@@ -567,9 +520,9 @@ async def connect(self, client_session_type=aiohttp.ClientSession) -> None:
Parameters
----------
- client_session_type
+ client_session_type : aiohttp.ClientSession
The client session implementation to use. You generally do not want
- to change this from the default, which is :obj:`~aiohttp.ClientSession`.
+ to change this from the default, which is `aiohttp.ClientSession`.
"""
if self.is_connected:
raise RuntimeError("Already connected")
@@ -666,8 +619,8 @@ async def close(self, close_code: int = 1000) -> None:
Parameters
----------
- close_code : :obj:`~int`
- The close code to use. Defaults to ``1000`` (normal closure).
+ close_code : int
+ The close code to use. Defaults to `1000` (normal closure).
"""
if not self.requesting_close_event.is_set():
self.logger.debug("closing websocket connection")
diff --git a/hikari/net/user_agents.py b/hikari/net/user_agents.py
index a36154ceea..fdbe395323 100644
--- a/hikari/net/user_agents.py
+++ b/hikari/net/user_agents.py
@@ -34,46 +34,41 @@
class UserAgent(metaclass=meta.SingletonMeta):
"""Platform version info.
- Notes
- -----
- This is a singleton.
+ !!! note
+ This is a singleton.
"""
- #: The version of the library.
- #:
- #: Example
- #: -------
- #: ``"hikari 1.0.1"``
- #:
- #: :type: :obj:`~typing.Final` [ :obj:`~str` ]
library_version: typing.Final[str]
+ """The version of the library.
+
+ Examples
+ --------
+ `"hikari 1.0.1"`
+ """
- #: The platform version.
- #:
- #: Example
- #: -------
- #: ``"CPython 3.8.2 GCC 9.2.0"``
- #:
- #: :type: :obj:`~typing.Final` [ :obj:`~str` ]
platform_version: typing.Final[str]
+ """The platform version.
+
+ Examples
+ --------
+ `"CPython 3.8.2 GCC 9.2.0"`
+ """
- #: The operating system type.
- #:
- #: Example
- #: -------
- #: ``"Linux-5.4.15-2-MANJARO-x86_64-with-glibc2.2.5"``
- #:
- #: :type: :obj:`~typing.Final` [ :obj:`~str` ]
system_type: typing.Final[str]
+ """The operating system type.
+
+ Examples
+ --------
+ `"Linux-5.4.15-2-MANJARO-x86_64-with-glibc2.2.5"`
+ """
- #: The Hikari-specific user-agent to use in HTTP connections to Discord.
- #:
- #: Example
- #: -------
- #: ``"DiscordBot (https://gitlab.com/nekokatt/hikari; 1.0.1; Nekokatt) CPython 3.8.2 GCC 9.2.0 Linux"``
- #:
- #: :type: :obj:`~typing.Final` [ :obj:`~str` ]
user_agent: typing.Final[str]
+ """The Hikari-specific user-agent to use in HTTP connections to Discord.
+
+ Examples
+ --------
+ `"DiscordBot (https://gitlab.com/nekokatt/hikari; 1.0.1; Nekokatt) CPython 3.8.2 GCC 9.2.0 Linux"`
+ """
def __init__(self):
from hikari._about import __author__, __url__, __version__
@@ -96,16 +91,13 @@ def __attr__(_):
def _join_strip(*args):
return " ".join((arg.strip() for arg in args if arg.strip()))
- # Ignore docstring not starting in an imperative mood
+ # Inore docstring not starting in an imperativge mood
@property
def websocket_triplet(self) -> typing.Dict[str, str]: # noqa: D401
"""A dict representing device and library info.
- Returns
- -------
- :obj:`~typing.Dict` [ :obj:`~str`, :obj:`~str` ]
- The object to send to Discord representing device info when
- IDENTIFYing with the gateway.
+ This is the object to send to Discord representing device info when
+ IDENTIFYing with the gateway in the format `typing.Dict` [ `str`, `str` ]
"""
return {
"$os": self.system_type,
diff --git a/hikari/permissions.py b/hikari/permissions.py
index 340b2ffab6..8d45245d3c 100644
--- a/hikari/permissions.py
+++ b/hikari/permissions.py
@@ -27,9 +27,7 @@ class Permission(enum.IntFlag):
"""Represents the permissions available in a given channel or guild.
This is an int-flag enum. This means that you can **combine multiple
- permissions together** into one value using the bitwise-OR operator (``|``).
-
- .. code-block:: python
+ permissions together** into one value using the bitwise-OR operator (`|`).
my_perms = Permission.MANAGE_CHANNELS | Permission.MANAGE_GUILD
@@ -41,10 +39,8 @@ class Permission(enum.IntFlag):
)
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.
-
- .. code-block:: python
+ 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 = Permission.MANAGE_CHANNELS | Permission.MANAGE_GUILD
@@ -66,10 +62,8 @@ class Permission(enum.IntFlag):
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``.
-
- .. code-block:: python
+ 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 = Permission.MANAGE_CHANNELS | Permission.MANAGE_GUILD
@@ -77,106 +71,106 @@ class Permission(enum.IntFlag):
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.
-
- .. code-block:: python
+ you can use the inversion operator (`~`) to do that.
# All permissions except ADMINISTRATOR.
my_perms = ~Permission.ADMINISTRATOR
"""
- #: Empty permission.
NONE = 0
+ """Empty permission."""
- #: Allows creation of instant invites.
CREATE_INSTANT_INVITE = 1 << 0
+ """Allows creation of instant invites."""
- #: Allows kicking members
KICK_MEMBERS = 1 << 1
+ """Allows kicking members"""
- #: Allows banning members.
BAN_MEMBERS = 1 << 2
+ """Allows banning members."""
- #: Allows all permissions and bypasses channel permission overwrites.
ADMINISTRATOR = 1 << 3
+ """Allows all permissions and bypasses channel permission overwrites."""
- #: Allows management and editing of channels.
MANAGE_CHANNELS = 1 << 4
+ """Allows management and editing of channels."""
- #: Allows management and editing of the guild.
MANAGE_GUILD = 1 << 5
+ """Allows management and editing of the guild."""
- #: Allows for the addition of reactions to messages.
ADD_REACTIONS = 1 << 6
+ """Allows for the addition of reactions to messages."""
- #: Allows for viewing of audit logs.
VIEW_AUDIT_LOG = 1 << 7
+ """Allows for viewing of audit logs."""
- #: Allows for using priority speaker in a voice channel.
PRIORITY_SPEAKER = 1 << 8
+ """Allows for using priority speaker in a voice channel."""
- #: Allows the user to go live.
STREAM = 1 << 9
+ """Allows the user to go live."""
- #: Allows guild members to view a channel, which includes reading messages in text channels.
VIEW_CHANNEL = 1 << 10
+ """Allows guild members to view a channel, which includes reading messages in text channels."""
- #: Allows for sending messages in a channel.
SEND_MESSAGES = 1 << 11
+ """Allows for sending messages in a channel."""
- #: Allows for sending of ``/tts`` messages.
SEND_TTS_MESSAGES = 1 << 12
+ """Allows for sending of `/tts` messages."""
- #: Allows for deletion of other users messages.
MANAGE_MESSAGES = 1 << 13
+ """Allows for deletion of other users messages."""
- #: Links sent by users with this permission will be auto-embedded.
EMBED_LINKS = 1 << 14
+ """Links sent by users with this permission will be auto-embedded."""
- #: Allows for uploading images and files
ATTACH_FILES = 1 << 15
+ """Allows for uploading images and files."""
- #: Allows for reading of message history.
READ_MESSAGE_HISTORY = 1 << 16
+ """Allows for reading of message history."""
- #: 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.
MENTION_EVERYONE = 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.
+ """
- #: Allows the usage of custom emojis from other servers.
USE_EXTERNAL_EMOJIS = 1 << 18
+ """Allows the usage of custom emojis from other servers."""
- #: Allows for joining of a voice channel.
CONNECT = 1 << 20
+ """Allows for joining of a voice channel."""
- #: Allows for speaking in a voice channel.
SPEAK = 1 << 21
+ """Allows for speaking in a voice channel."""
- #: Allows for muting members in a voice channel.
MUTE_MEMBERS = 1 << 22
+ """Allows for muting members in a voice channel."""
- #: Allows for deafening of members in a voice channel.
DEAFEN_MEMBERS = 1 << 23
+ """Allows for deafening of members in a voice channel."""
- #: Allows for moving of members between voice channels.
MOVE_MEMBERS = 1 << 24
+ """Allows for moving of members between voice channels."""
- #: Allows for using voice-activity-detection in a voice channel.
USE_VAD = 1 << 25
+ """Allows for using voice-activity-detection in a voice channel."""
- #: Allows for modification of own nickname.
CHANGE_NICKNAME = 1 << 26
+ """Allows for modification of own nickname."""
- #: Allows for modification of other users nicknames.
MANAGE_NICKNAMES = 1 << 27
+ """Allows for modification of other users nicknames."""
- #: Allows management and editing of roles.
MANAGE_ROLES = 1 << 28
+ """Allows management and editing of roles."""
- #: Allows management and editing of webhooks.
MANAGE_WEBHOOKS = 1 << 29
+ """Allows management and editing of webhooks."""
- #: Allows management and editing of emojis.
MANAGE_EMOJIS = 1 << 30
+ """Allows management and editing of emojis."""
diff --git a/hikari/snowflakes.py b/hikari/snowflakes.py
index b124e3160e..dd5ae4b5df 100644
--- a/hikari/snowflakes.py
+++ b/hikari/snowflakes.py
@@ -39,15 +39,13 @@
class Snowflake(bases.HikariEntity, typing.SupportsInt):
"""A concrete representation of a unique identifier for an object on Discord.
- This object can be treated as a regular :obj:`~int` for most purposes.
+ This object can be treated as a regular `int` for most purposes.
"""
__slots__ = ("_value",)
- #: The integer value of this ID.
- #:
- #: :type: :obj:`~int`
_value: int
+ """The integer value of this ID."""
# noinspection PyMissingConstructor
def __init__(self, value: typing.Union[int, str]) -> None: # pylint:disable=super-init-not-called
@@ -98,7 +96,7 @@ def serialize(self) -> str:
@classmethod
def deserialize(cls, value: str) -> "Snowflake":
- """Take a :obj:`~str` ID and convert it into a Snowflake object."""
+ """Take a `str` ID and convert it into a Snowflake object."""
return cls(value)
@classmethod
@@ -117,10 +115,8 @@ def from_timestamp(cls, timestamp: float) -> "Snowflake":
class UniqueEntity(bases.HikariEntity, typing.SupportsInt):
"""An entity that has an integer ID of some sort."""
- #: The ID of this entity.
- #:
- #: :type: :obj:`~Snowflake`
id: Snowflake = marshaller.attrib(hash=True, eq=True, repr=True, deserializer=Snowflake, serializer=str)
+ """The ID of this entity."""
def __int__(self):
return int(self.id)
diff --git a/hikari/state/__init__.py b/hikari/state/__init__.py
index 608c413269..937c2e7faa 100644
--- a/hikari/state/__init__.py
+++ b/hikari/state/__init__.py
@@ -23,13 +23,5 @@
several key components to be implemented separately, in case you have a
specific use case you want to provide (such as placing stuff on a message
queue if you distribute your bot).
-
-The overall structure is as follows:
-
-.. inheritance-diagram::
- hikari.state.event_dispatchers
- hikari.state.raw_event_consumers
- hikari.state.event_managers
- hikari.state.stateless_event_managers
"""
__all__ = []
diff --git a/hikari/state/consumers.py b/hikari/state/consumers.py
index 184f458643..7c5f0e7636 100644
--- a/hikari/state/consumers.py
+++ b/hikari/state/consumers.py
@@ -49,10 +49,10 @@ def process_raw_event(
Parameters
----------
- shard_client_obj : :obj:`~hikari.clients.shard_clients.ShardClient`
+ shard_client_obj : hikari.clients.shards.ShardClient
The client for the shard that received the event.
- name : :obj:`~str`
+ name : str
The raw event name.
- payload : :obj:`~typing.Any`
+ payload : typing.Any
The raw event payload. Will be a JSON-compatible type.
"""
diff --git a/hikari/state/dispatchers.py b/hikari/state/dispatchers.py
index e4984e8693..13cb9a494d 100644
--- a/hikari/state/dispatchers.py
+++ b/hikari/state/dispatchers.py
@@ -77,15 +77,15 @@ def add_listener(self, event_type: typing.Type[EventT], callback: EventCallbackT
Parameters
----------
- event_type : :obj:`~typing.Type` [ :obj:`~hikari.events.HikariEvent` ]
+ event_type : typing.Type [ hikari.events.HikariEvent ]
The event to register to.
- callback : ``async def callback(event: HikariEvent) -> ...``
+ callback : `async def callback(event: HikariEvent) -> ...`
The event callback to invoke when this event is fired.
Raises
------
- :obj:`~TypeError`
- If ``coroutine_function`` is not a coroutine.
+ TypeError
+ If `coroutine_function` is not a coroutine.
"""
@abc.abstractmethod
@@ -96,9 +96,9 @@ def remove_listener(self, event_type: typing.Type[EventT], callback: EventCallba
Parameters
----------
- event_type : :obj:`~typing.Type` [ :obj:`~hikari.events.HikariEvent` ]
+ event_type : typing.Type [ hikari.events.HikariEvent ]
The type of event to remove the callback from.
- callback : ``async def callback(event: HikariEvent) -> ...``
+ callback : `async def callback(event: HikariEvent) -> ...`
The event callback to invoke when this event is fired.
"""
@@ -110,16 +110,16 @@ def wait_for(
Parameters
----------
- event_type : :obj:`~typing.Type` [ :obj:`~hikari.events.HikariEvent` ]
+ event_type : typing.Type [ hikari.events.HikariEvent ]
The name of the event to wait for.
- timeout : :obj:`~float`, optional
+ timeout : float, optional
The timeout to wait for before cancelling and raising an
- :obj:`~asyncio.TimeoutError` instead. If this is :obj:`~None`, this
- will wait forever. Care must be taken if you use :obj:`~None` as this
+ `asyncio.TimeoutError` instead. If this is `None`, this
+ will wait forever. Care must be taken if you use `None` as this
may leak memory if you do this from an event listener that gets
repeatedly called. If you want to do this, you should consider
using an event listener instead of this function.
- predicate : ``def predicate(event) -> bool`` or ``async def predicate(event) -> bool``
+ predicate : `def predicate(event) -> bool` or `async def predicate(event) -> bool`
A function that takes the arguments for the event and returns True
if it is a match, or False if it should be ignored.
This can be a coroutine function that returns a boolean, or a
@@ -127,17 +127,16 @@ def wait_for(
Returns
-------
- :obj:`~asyncio.Future`:
+ asyncio.Future:
A future to await. When the given event is matched, this will be
completed with the corresponding event body.
If the predicate throws an exception, or the timeout is reached,
then this will be set as an exception on the returned future.
- Notes
- -----
- The event type is not expected to be considered in a polymorphic
- lookup, but can be implemented this way optionally if documented.
+ !!! note
+ The event type is not expected to be considered in a polymorphic
+ lookup, but can be implemented this way optionally if documented.
"""
@typing.overload
@@ -146,10 +145,8 @@ def on(self) -> typing.Callable[[EventCallbackT], EventCallbackT]:
This considers the type hint on the signature to get the event type.
- Example
- -------
- .. code-block:: python
-
+ Examples
+ --------
@bot.on()
async def on_message(event: hikari.MessageCreatedEvent):
print(event.content)
@@ -161,21 +158,19 @@ def on(self, event_type: typing.Type[EventCallbackT]) -> typing.Callable[[EventC
This considers the type given to the decorator.
- Example
- -------
- .. code-block:: python
-
+ Examples
+ --------
@bot.on(hikari.MessageCreatedEvent)
async def on_message(event):
print(event.content)
"""
def on(self, event_type=None):
- """Return a decorator equivalent to invoking :meth:`add_listener`.
+ """Return a decorator equivalent to invoking `EventDispatcher.add_listener`.
Parameters
----------
- event_type : :obj:`~typing.Type` [ :obj:`~hikari.events.HikariEvent` ], optional
+ event_type : typing.Type [ hikari.events.HikariEvent ], optional
The event type to register the produced decorator to. If this is not
specified, then the given function is used instead and the type hint
of the first argument is considered. If no type hint is present
@@ -183,8 +178,6 @@ def on(self, event_type=None):
Examples
--------
- .. code-block:: python
-
# Type-hinted format.
@bot.on()
async def on_message(event: hikari.MessageCreatedEvent):
@@ -197,7 +190,7 @@ async def on_message(event):
Returns
-------
- ``decorator(T) -> T``
+ decorator(T) -> T
A decorator for a coroutine function that registers the given event.
"""
@@ -242,12 +235,12 @@ def dispatch_event(self, event: events.HikariEvent) -> more_typing.Future[typing
Parameters
----------
- event : :obj:`~hikari.events.HikariEvent`
+ event : hikari.events.HikariEvent
The event to dispatch.
Returns
-------
- :obj:`~asyncio.Future`:
+ asyncio.Future:
a future that can be optionally awaited if you need to wait for all
listener callbacks and waiters to be processed. If this is not
awaited, the invocation is invoked soon on the current event loop.
@@ -273,15 +266,13 @@ class IntentAwareEventDispatcherImpl(EventDispatcher):
Parameters
----------
- enabled_intents : :obj:`~hikari.intents.Intent`, optional
- The intents that are enabled for the application. If ``None``, then no
+ enabled_intents : hikari.intents.Intent, optional
+ The intents that are enabled for the application. If `None`, then no
intent checks are performed when subscribing a new event.
"""
- #: The logger used to write log messages.
- #:
- #: :type: :obj:`~logging.Logger`
logger: logging.Logger
+ """The logger used to write log messages."""
def __init__(self, enabled_intents: typing.Optional[intents.Intent]) -> None:
self._enabled_intents = enabled_intents
@@ -304,15 +295,15 @@ def add_listener(self, event_type: typing.Type[events.HikariEvent], callback: Ev
Parameters
----------
- event_type : :obj:`~typing.Type` [ :obj:`~hikari.events.HikariEvent` ]
+ event_type : typing.Type [ hikari.events.HikariEvent ]
The event to register to.
- callback : ``async def callback(event: HikariEvent) -> ...``
+ callback : `async def callback(event: HikariEvent) -> ...`
The event callback to invoke when this event is fired.
Raises
------
- :obj:`~TypeError`
- If ``coroutine_function`` is not a coroutine.
+ TypeError
+ If `coroutine_function` is not a coroutine.
Note
----
@@ -356,9 +347,9 @@ def remove_listener(self, event_type: typing.Type[EventT], callback: EventCallba
Parameters
----------
- event_type : :obj:`~typing.Type` [ :obj:`~hikari.events.HikariEvent` ]
+ event_type : typing.Type [ hikari.events.HikariEvent ]
The type of event to remove the callback from.
- callback : ``async def callback(event: HikariEvent) -> ...``
+ callback : `async def callback(event: HikariEvent) -> ...`
The event callback to remove.
"""
if event_type in self._listeners and callback in self._listeners[event_type]:
@@ -374,12 +365,12 @@ def dispatch_event(self, event: events.HikariEvent):
Parameters
----------
- event : :obj:`~hikari.events.HikariEvent`
+ event : hikari.events.HikariEvent
The event to dispatch.
Returns
-------
- :obj:`~asyncio.Future`
+ asyncio.Future
This may be a gathering future of the callbacks to invoke, or it may
be a completed future object. Regardless, this result will be
scheduled on the event loop automatically, and does not need to be
@@ -452,17 +443,16 @@ def handle_exception(
This allows users to override this with a custom implementation if desired.
This implementation will check to see if the event that triggered the
- exception is an :obj:`~hikari.events.ExceptionEvent`. If this
- exception was caused by the :obj:`~hikari.events.ExceptionEvent`,
- then nothing is dispatched (thus preventing an exception handler recursively
- re-triggering itself). Otherwise, an :obj:`~hikari.events.ExceptionEvent`
- is dispatched.
+ exception is an `hikari.events.ExceptionEvent`. If this exception was
+ caused by the `hikari.events.ExceptionEvent`, then nothing is dispatched
+ (thus preventing an exception handler recursively re-triggering itself).
+ Otherwise, an `hikari.events.ExceptionEvent` is dispatched.
Parameters
----------
- exception: :obj:`~Exception`
+ exception : Exception
The exception that triggered this call.
- event: :obj:`~hikari.events.HikariEvent`
+ event : hikari.events.HikariEvent
The event that was being dispatched.
callback
The callback that threw the exception.
@@ -495,35 +485,34 @@ def wait_for(
Parameters
----------
- event_type : :obj:`~typing.Type` [ :obj:`~hikari.events.HikariEvent` ]
+ event_type : typing.Type [ hikari.events.HikariEvent ]
The name of the event to wait for.
- timeout : :obj:`~float`, optional
+ timeout : float, optional
The timeout to wait for before cancelling and raising an
- :obj:`~asyncio.TimeoutError` instead. If this is `None`, this will
- wait forever. Care must be taken if you use `None` as this may
- leak memory if you do this from an event listener that gets
- repeatedly called. If you want to do this, you should consider
- using an event listener instead of this function.
- predicate : ``def predicate(event) -> bool`` or ``async def predicate(event) -> bool``
- A function that takes the arguments for the event and returns True
- if it is a match, or False if it should be ignored.
+ `asyncio.TimeoutError` instead. If this is `None`, this will wait
+ forever. Care must be taken if you use `None` as this may leak
+ memory if you do this from an event listener that gets repeatedly
+ called. If you want to do this, you should consider using an event
+ listener instead of this function.
+ predicate : `def predicate(event) -> bool` or `async def predicate(event) -> bool`
+ A function that takes the arguments for the event and returns `True`
+ if it is a match, or `False` if it should be ignored.
This can be a coroutine function that returns a boolean, or a
regular function.
Returns
-------
- :obj:`~asyncio.Future`
+ asyncio.Future
A future that when awaited will provide a the arguments passed to
the first matching event. If no arguments are passed to the event,
then `None` is the result. If one argument is passed to the event,
then that argument is the result, otherwise a tuple of arguments is
the result instead.
- Notes
- -----
- Awaiting this result will raise an :obj:`~asyncio.TimeoutError` if the
- timeout is hit and no match is found. If the predicate throws any
- exception, this is raised immediately.
+ !!! note
+ Awaiting this result will raise an `asyncio.TimeoutError` if the
+ timeout is hit and no match is found. If the predicate throws any
+ exception, this is raised immediately.
"""
future = asyncio.get_event_loop().create_future()
if event_type not in self._waiters:
diff --git a/hikari/state/event_managers.py b/hikari/state/event_managers.py
index 8177510d59..7ae5c4166d 100644
--- a/hikari/state/event_managers.py
+++ b/hikari/state/event_managers.py
@@ -44,7 +44,7 @@ def raw_event_mapper(name: str) -> typing.Callable[[EventConsumerT], EventConsum
Returns
-------
- ``decorator(T) -> T``
+ decorator(T) -> T
A decorator for a method.
"""
@@ -74,8 +74,8 @@ class EventManager(typing.Generic[EventDispatcherT], consumers.RawEventConsumer)
"""Abstract definition of the components for an event system for a bot.
The class itself inherits from
- :obj:`~hikari.state.raw_event_consumers.RawEventConsumer` (which allows
- it to provide the ability to transform a raw payload into an event object).
+ `hikari.state.consumers.RawEventConsumer` (which allows it to provide the
+ ability to transform a raw payload into an event object).
This is designed as a basis to enable transformation of raw incoming events
from the websocket into more usable native Python objects, and to then
@@ -84,53 +84,54 @@ class EventManager(typing.Generic[EventDispatcherT], consumers.RawEventConsumer)
Parameters
----------
- event_dispatcher_impl: :obj:`~hikari.state.event_dispatchers.EventDispatcher`
+ event_dispatcher_impl: hikari.state.dispatchers.EventDispatcher
An implementation of event dispatcher that will store individual events
and manage dispatching them after this object creates them.
- Notes
- -----
- This object will detect internal event mapper functions by looking for
- coroutine functions wrapped with :obj:`~raw_event_mapper`.
+ !!! note
+ This object will detect internal event mapper functions by looking for
+ coroutine functions wrapped with `raw_event_mapper`.
- These methods are expected to have the following parameters:
+ These methods are expected to have the following parameters:
- shard_obj: :obj:`~hikari.clients.shard_clients.ShardClient`
- The shard client that emitted the event.
- payload: :obj:`~typing.Any`
- The received payload. This is expected to be a JSON-compatible type.
+ * shard_obj : `hikari.clients.shards.ShardClient`
- For example, if you want to provide an implementation that can consume
- and handle ``MESSAGE_CREATE`` events, you can do the following.
+ The shard client that emitted the event.
- .. code-block:: python
+ * payload : `typing.Any`
- class MyMappingEventConsumer(MappingEventConsumer):
- @event_mapper("MESSAGE_CREATE")
- def _process_message_create(self, shard, payload) -> MessageCreateEvent:
- return MessageCreateEvent.deserialize(payload)
+ The received payload. This is expected to be a JSON-compatible type.
- The decorator can be stacked if you wish to provide one mapper
+ For example, if you want to provide an implementation that can consume
+ and handle `MESSAGE_CREATE` events, you can do the following.
- ... it is pretty simple. This is exposed in this way to enable you to write
- code that may use a distributed system instead of a single-process bot.
+ class MyMappingEventConsumer(MappingEventConsumer):
+ @event_mapper("MESSAGE_CREATE")
+ def _process_message_create(self, shard, payload) -> MessageCreateEvent:
+ return MessageCreateEvent.deserialize(payload)
- Writing to a message queue is pretty simple using this mechanism, as you can
- choose when and how to place the event on a queue to be consumed by other
- application components.
+ The decorator can be stacked if you wish to provide one mapper
- For the sake of simplicity, Hikari only provides implementations for single
- process bots, since most of what you will need will be fairly bespoke if you
- want to implement anything more complicated; regardless, the tools are here
- for you to use as you see fit.
+ ... it is pretty simple. This is exposed in this way to enable you to
+ write code that may use a distributed system instead of a single-process
+ bot.
- Warnings
- --------
- This class provides the scaffold for making an event consumer, but does not
- physically implement the logic to deserialize and process specific events.
+ Writing to a message queue is pretty simple using this mechanism, as you
+ can choose when and how to place the event on a queue to be consumed by
+ other application components.
- To provide this, use one of the provided implementations of this class, or
- create your own as needed.
+ For the sake of simplicity, Hikari only provides implementations for
+ single process bots, since most of what you will need will be fairly
+ bespoke if you want to implement anything more complicated; regardless,
+ the tools are here for you to use as you see fit.
+
+ !!! warning
+ This class provides the scaffold for making an event consumer, but doe
+ not physically implement the logic to deserialize and process specific
+ events.
+
+ To provide this, use one of the provided implementations of this class,
+ or create your own as needed.
"""
def __init__(self, event_dispatcher_impl: EventDispatcherT) -> None:
@@ -154,11 +155,11 @@ def process_raw_event(
Parameters
----------
- shard_client_obj: :obj:`~hikari.clients.shard_clients.ShardClient`
+ shard_client_obj : hikari.clients.shards.ShardClient
The shard that triggered this event.
- name : :obj:`~str`
+ name : str
The raw event name.
- payload : :obj:`~dict`
+ payload : dict
The payload that was sent.
"""
try:
diff --git a/hikari/state/stateless.py b/hikari/state/stateless.py
index 0731114793..7bac8536d1 100644
--- a/hikari/state/stateless.py
+++ b/hikari/state/stateless.py
@@ -34,181 +34,181 @@ class StatelessEventManagerImpl(event_managers.EventManager[dispatchers.EventDis
"""
@event_managers.raw_event_mapper("CONNECTED")
- def on_connect(self, shard, _):
+ def on_connect(self, shard, _) -> None:
"""Handle CONNECTED events."""
event = events.ConnectedEvent(shard=shard)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("DISCONNECTED")
- def on_disconnect(self, shard, _):
+ def on_disconnect(self, shard, _) -> None:
"""Handle DISCONNECTED events."""
event = events.DisconnectedEvent(shard=shard)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("RESUME")
- def on_resume(self, shard, _):
+ def on_resume(self, shard, _) -> None:
"""Handle RESUME events."""
event = events.ResumedEvent(shard=shard)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("READY")
- def on_ready(self, _, payload):
+ def on_ready(self, _, payload) -> None:
"""Handle READY events."""
event = events.ReadyEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("CHANNEL_CREATE")
- def on_channel_create(self, _, payload):
+ def on_channel_create(self, _, payload) -> None:
"""Handle CHANNEL_CREATE events."""
event = events.ChannelCreateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("CHANNEL_UPDATE")
- def on_channel_update(self, _, payload):
+ def on_channel_update(self, _, payload) -> None:
"""Handle CHANNEL_UPDATE events."""
event = events.ChannelUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("CHANNEL_DELETE")
- def on_channel_delete(self, _, payload):
+ def on_channel_delete(self, _, payload) -> None:
"""Handle CHANNEL_DELETE events."""
event = events.ChannelDeleteEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("CHANNEL_PIN_UPDATE")
- def on_channel_pin_update(self, _, payload):
+ def on_channel_pin_update(self, _, payload) -> None:
"""Handle CHANNEL_PIN_UPDATE events."""
event = events.ChannelPinUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_CREATE")
- def on_guild_create(self, _, payload):
+ def on_guild_create(self, _, payload) -> None:
"""Handle GUILD_CREATE events."""
event = events.GuildCreateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_UPDATE")
- def on_guild_update(self, _, payload):
+ def on_guild_update(self, _, payload) -> None:
"""Handle GUILD_UPDATE events."""
event = events.GuildUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_LEAVE")
- def on_guild_leave(self, _, payload):
+ def on_guild_leave(self, _, payload) -> None:
"""Handle GUILD_LEAVE events."""
event = events.GuildLeaveEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_UNAVAILABLE")
- def on_guild_unavailable(self, _, payload):
+ def on_guild_unavailable(self, _, payload) -> None:
"""Handle GUILD_UNAVAILABLE events."""
event = events.GuildUnavailableEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_BAN_ADD")
- def on_guild_ban_add(self, _, payload):
+ def on_guild_ban_add(self, _, payload) -> None:
"""Handle GUILD_BAN_ADD events."""
event = events.GuildBanAddEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_BAN_REMOVE")
- def on_guild_ban_remove(self, _, payload):
+ def on_guild_ban_remove(self, _, payload) -> None:
"""Handle GUILD_BAN_REMOVE events."""
event = events.GuildBanRemoveEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_EMOJIS_UPDATE")
- def on_guild_emojis_update(self, _, payload):
+ def on_guild_emojis_update(self, _, payload) -> None:
"""Handle GUILD_EMOJIS_UPDATE events."""
event = events.GuildEmojisUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_INTEGRATIONS_UPDATE")
- def on_guild_integrations_update(self, _, payload):
+ def on_guild_integrations_update(self, _, payload) -> None:
"""Handle GUILD_INTEGRATIONS_UPDATE events."""
event = events.GuildIntegrationsUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_MEMBER_ADD")
- def on_guild_member_add(self, _, payload):
+ def on_guild_member_add(self, _, payload) -> None:
"""Handle GUILD_MEMBER_ADD events."""
event = events.GuildMemberAddEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_MEMBER_UPDATE")
- def on_guild_member_update(self, _, payload):
+ def on_guild_member_update(self, _, payload) -> None:
"""Handle GUILD_MEMBER_UPDATE events."""
event = events.GuildMemberUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_MEMBER_REMOVE")
- def on_guild_member_remove(self, _, payload):
+ def on_guild_member_remove(self, _, payload) -> None:
"""Handle GUILD_MEMBER_REMOVE events."""
event = events.GuildMemberRemoveEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_ROLE_CREATE")
- def on_guild_role_create(self, _, payload):
+ def on_guild_role_create(self, _, payload) -> None:
"""Handle GUILD_ROLE_CREATE events."""
event = events.GuildRoleCreateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_ROLE_UPDATE")
- def on_guild_role_update(self, _, payload):
+ def on_guild_role_update(self, _, payload) -> None:
"""Handle GUILD_ROLE_UPDATE events."""
event = events.GuildRoleUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("GUILD_ROLE_DELETE")
- def on_guild_role_delete(self, _, payload):
+ def on_guild_role_delete(self, _, payload) -> None:
"""Handle GUILD_ROLE_DELETE events."""
event = events.GuildRoleDeleteEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("INVITE_CREATE")
- def on_invite_create(self, _, payload):
+ def on_invite_create(self, _, payload) -> None:
"""Handle INVITE_CREATE events."""
event = events.InviteCreateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("INVITE_DELETE")
- def on_invite_delete(self, _, payload):
+ def on_invite_delete(self, _, payload) -> None:
"""Handle INVITE_DELETE events."""
event = events.InviteDeleteEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("MESSAGE_CREATE")
- def on_message_create(self, _, payload):
+ def on_message_create(self, _, payload) -> None:
"""Handle MESSAGE_CREATE events."""
event = events.MessageCreateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("MESSAGE_UPDATE")
- def on_message_update(self, _, payload):
+ def on_message_update(self, _, payload) -> None:
"""Handle MESSAGE_UPDATE events."""
event = events.MessageUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("MESSAGE_DELETE")
- def on_message_delete(self, _, payload):
+ def on_message_delete(self, _, payload) -> None:
"""Handle MESSAGE_DELETE events."""
event = events.MessageDeleteEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("MESSAGE_DELETE_BULK")
- def on_message_delete_bulk(self, _, payload):
+ def on_message_delete_bulk(self, _, payload) -> None:
"""Handle MESSAGE_DELETE_BULK events."""
event = events.MessageDeleteBulkEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("MESSAGE_REACTION_ADD")
- def on_message_reaction_add(self, _, payload):
+ def on_message_reaction_add(self, _, payload) -> None:
"""Handle MESSAGE_REACTION_ADD events."""
event = events.MessageReactionAddEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("MESSAGE_REACTION_REMOVE")
- def on_message_reaction_remove(self, _, payload):
+ def on_message_reaction_remove(self, _, payload) -> None:
"""Handle MESSAGE_REACTION_REMOVE events."""
payload["emoji"].setdefault("animated", None)
@@ -216,7 +216,7 @@ def on_message_reaction_remove(self, _, payload):
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("MESSAGE_REACTION_REMOVE_EMOJI")
- def on_message_reaction_remove_emoji(self, _, payload):
+ def on_message_reaction_remove_emoji(self, _, payload) -> None:
"""Handle MESSAGE_REACTION_REMOVE_EMOJI events."""
payload["emoji"].setdefault("animated", None)
@@ -224,37 +224,37 @@ def on_message_reaction_remove_emoji(self, _, payload):
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("PRESENCE_UPDATE")
- def on_presence_update(self, _, payload):
+ def on_presence_update(self, _, payload) -> None:
"""Handle PRESENCE_UPDATE events."""
event = events.PresenceUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("TYPING_START")
- def on_typing_start(self, _, payload):
+ def on_typing_start(self, _, payload) -> None:
"""Handle TYPING_START events."""
event = events.TypingStartEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("USER_UPDATE")
- def on_user_update(self, _, payload):
+ def on_user_update(self, _, payload) -> None:
"""Handle USER_UPDATE events."""
event = events.UserUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("VOICE_STATE_UPDATE")
- def on_voice_state_update(self, _, payload):
+ def on_voice_state_update(self, _, payload) -> None:
"""Handle VOICE_STATE_UPDATE events."""
event = events.VoiceStateUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("VOICE_SERVER_UPDATE")
- def on_voice_server_update(self, _, payload):
+ def on_voice_server_update(self, _, payload) -> None:
"""Handle VOICE_SERVER_UPDATE events."""
event = events.VoiceStateUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
@event_managers.raw_event_mapper("WEBHOOK_UPDATE")
- def on_webhook_update(self, _, payload):
+ def on_webhook_update(self, _, payload) -> None:
"""Handle WEBHOOK_UPDATE events."""
event = events.WebhookUpdateEvent.deserialize(payload)
self.event_dispatcher.dispatch_event(event)
diff --git a/hikari/unset.py b/hikari/unset.py
index 36af4e339e..02f10b9671 100644
--- a/hikari/unset.py
+++ b/hikari/unset.py
@@ -50,20 +50,20 @@ def ___defer___(self, *_, **__) -> typing.NoReturn:
T = typing.TypeVar("T")
MayBeUnset = typing.Union[T, Unset]
-#: A global instance of :class:`~Unset`.
UNSET: typing.Final[Unset] = Unset()
+"""A global instance of `Unset`."""
@typing.overload
def is_unset(obj: UNSET) -> typing.Literal[True]:
- """Return ``True`` always."""
+ """Return `True` always."""
@typing.overload
def is_unset(obj: typing.Any) -> typing.Literal[False]:
- """Return ``False`` always."""
+ """Return `False` always."""
def is_unset(obj):
- """Return ``True`` if the object is an :obj:`~Unset` value."""
+ """Return `True` if the object is an `Unset` value."""
return isinstance(obj, Unset)
diff --git a/hikari/users.py b/hikari/users.py
index 209f86a059..525fc788af 100644
--- a/hikari/users.py
+++ b/hikari/users.py
@@ -33,61 +33,61 @@
class UserFlag(enum.IntFlag):
"""The known user flags that represent account badges."""
- #: None
NONE = 0
+ """None"""
- #: Discord Empoloyee
DISCORD_EMPLOYEE = 1 << 0
+ """Discord Employee"""
- #: Discord Partner
DISCORD_PARTNER = 1 << 1
+ """Discord Partner"""
- #: HypeSquad Events
HYPESQUAD_EVENTS = 1 << 2
+ """HypeSquad Events"""
- #: Bug Hunter Level 1
BUG_HUNTER_LEVEL_1 = 1 << 3
+ """Bug Hunter Level 1"""
- #: House of Bravery
HOUSE_BRAVERY = 1 << 6
+ """House of Bravery"""
- #: House of Brilliance
HOUSE_BRILLIANCE = 1 << 7
+ """House of Brilliance"""
- #: House of Balance
HOUSE_BALANCE = 1 << 8
+ """House of Balance"""
- #: Early Supporter
EARLY_SUPPORTER = 1 << 9
+ """Early Supporter"""
- #: Team user
TEAM_USER = 1 << 10
+ """Team user"""
- #: System
SYSTEM = 1 << 12
+ """System"""
- #: Bug Hunter Level 2
BUG_HUNTER_LEVEL_2 = 1 << 14
+ """Bug Hunter Level 2"""
- #: Verified Bot
VERIFIED_BOT = 1 << 16
+ """Verified Bot"""
- #: Verified Bot Developer
VERIFIED_BOT_DEVELOPER = 1 << 17
+ """Verified Bot Developer"""
@enum.unique
class PremiumType(enum.IntEnum):
"""The types of Nitro."""
- #: No premium.
NONE = 0
+ """No premium."""
- #: Premium including basic perks like animated emojis and avatars.
NITRO_CLASSIC = 1
+ """Premium including basic perks like animated emojis and avatars."""
- #: Premium including all perks (e.g. 2 server boosts).
NITRO = 2
+ """Premium including all perks (e.g. 2 server boosts)."""
@marshaller.marshallable()
@@ -95,42 +95,29 @@ class PremiumType(enum.IntEnum):
class User(bases.UniqueEntity, marshaller.Deserializable):
"""Represents a user."""
- #: This user's discriminator.
- #:
- #: :type: :obj:`~str`
discriminator: str = marshaller.attrib(deserializer=str)
+ """This user's discriminator."""
- #: This user's username.
- #:
- #: :type: :obj:`~str`
username: str = marshaller.attrib(deserializer=str)
+ """This user's username."""
- #: This user's avatar hash, if set.
- #:
- #: :type: :obj:`~str`, optional
avatar_hash: typing.Optional[str] = marshaller.attrib(raw_name="avatar", deserializer=str, if_none=None)
+ """This user's avatar hash, if set."""
- #: Whether this user is a bot account.
- #:
- #: :type: :obj:`~bool`
is_bot: bool = marshaller.attrib(raw_name="bot", deserializer=bool, if_undefined=False, default=False)
+ """Whether this user is a bot account."""
- #: Whether this user is a system account.
- #:
- #: :type: :obj:`~bool`
is_system: bool = marshaller.attrib(raw_name="system", deserializer=bool, if_undefined=False, default=False)
+ """Whether this user is a system account."""
- #: The public flags for this user.
- #:
- #: Note
- #: ----
- #: This will be :obj:`~None` if it's a webhook user.
- #:
- #:
- #: :type: :obj:`~UserFlag`, optional
flags: typing.Optional[UserFlag] = marshaller.attrib(
raw_name="public_flags", deserializer=UserFlag, if_undefined=None, default=None
)
+ """The public flags for this user.
+
+ !!! info
+ This will be `None` if it's a webhook user.
+ """
@property
def avatar_url(self) -> str:
@@ -142,25 +129,25 @@ def format_avatar_url(self, fmt: typing.Optional[str] = None, size: int = 4096)
Parameters
----------
- fmt : :obj:`~str`
- The format to use for this URL, defaults to ``png`` or ``gif``.
- Supports ``png``, ``jpeg``, ``jpg``, ``webp`` and ``gif`` (when
+ fmt : str
+ The format to use for this URL, defaults to `png` or `gif`.
+ Supports `png`, `jpeg`, `jpg`, `webp` and `gif` (when
animated). Will be ignored for default avatars which can only be
- ``png``.
- size : :obj:`~int`
- The size to set for the URL, defaults to ``4096``.
+ `png`.
+ size : int
+ The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Will be ignored for default avatars.
Returns
-------
- :obj:`~str`
+ str
The string URL.
Raises
------
- :obj:`~ValueError`
- If ``size`` is not a power of two or not between 16 and 4096.
+ ValueError
+ If `size` is not a power of two or not between 16 and 4096.
"""
if not self.avatar_hash:
return urls.generate_cdn_url("embed/avatars", str(self.default_avatar), fmt="png", size=None)
@@ -181,41 +168,35 @@ def default_avatar(self) -> int:
class MyUser(User):
"""Represents a user with extended oauth2 information."""
- #: Whether the user's account has 2fa enabled.
- #:
- #: :type: :obj:`~bool`
is_mfa_enabled: bool = marshaller.attrib(raw_name="mfa_enabled", deserializer=bool)
+ """Whether the user's account has 2fa enabled."""
- #: The user's set language. This is not provided by the ``READY`` event.
- #:
- #: :type: :obj:`~str`, optional
locale: typing.Optional[str] = marshaller.attrib(deserializer=str, if_none=None, if_undefined=None, default=None)
+ """The user's set language. This is not provided by the `READY` event."""
- #: Whether the email for this user's account has been verified.
- #: Will be :obj:`~None` if retrieved through the oauth2 flow without the
- #: ``email`` scope.
- #:
- #: :type: :obj:`~bool`, optional
is_verified: typing.Optional[bool] = marshaller.attrib(
raw_name="verified", deserializer=bool, if_undefined=None, default=None
)
+ """Whether the email for this user's account has been verified.
+
+ Will be `None` if retrieved through the oauth2 flow without the `email`
+ scope.
+ """
- #: The user's set email.
- #: Will be :obj:`~None` if retrieved through the oauth2 flow without the
- #: ``email`` scope and for bot users.
- #:
- #: :type: :obj:`~str`, optional
email: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, if_none=None, default=None)
+ """The user's set email.
+
+ Will be `None` if retrieved through the oauth2 flow without the `email`
+ scope and for bot users.
+ """
- #: This user account's flags.
- #:
- #: :type: :obj:`~UserFlag`
flags: UserFlag = marshaller.attrib(deserializer=UserFlag)
+ """This user account's flags."""
- #: The type of Nitro Subscription this user account had.
- #: This will always be :obj:`~None` for bots.
- #:
- #: :type: :obj:`~PremiumType`, optional
premium_type: typing.Optional[PremiumType] = marshaller.attrib(
deserializer=PremiumType, if_undefined=None, default=None
)
+ """The type of Nitro Subscription this user account had.
+
+ This will always be `None` for bots.
+ """
diff --git a/hikari/voices.py b/hikari/voices.py
index 1d50583388..78d689e158 100644
--- a/hikari/voices.py
+++ b/hikari/voices.py
@@ -33,68 +33,47 @@
class VoiceState(bases.HikariEntity, marshaller.Deserializable):
"""Represents a user's voice connection status."""
- #: The ID of the guild this voice state is in, if applicable.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The ID of the guild this voice state is in, if applicable."""
- #: The ID of the channel this user is connected to, will be :obj:`~None` if
- #: they are leaving voice.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
channel_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_none=None
)
+ """The ID of the channel this user is connected to.
+
+ This will be `None` if they are leaving voice.
+ """
- #: The ID of the user this voice state is for.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
user_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The ID of the user this voice state is for."""
- #: The guild member this voice state is for if the voice state is in a
- #: guild.
- #:
- #: :type: :obj:`~hikari.guilds.GuildMember`, optional
member: typing.Optional[guilds.GuildMember] = marshaller.attrib(
deserializer=guilds.GuildMember.deserialize, if_undefined=None, default=None
)
+ """The guild member this voice state is for if the voice state is in a guild."""
- #: The ID of this voice state's session.
- #:
- #: :type: :obj:`~str`
session_id: str = marshaller.attrib(deserializer=str)
+ """The string ID of this voice state's session."""
- #: Whether this user is deafened by the guild.
- #:
- #: :type: :obj:`~bool`
is_guild_deafened: bool = marshaller.attrib(raw_name="deaf", deserializer=bool)
+ """Whether this user is deafened by the guild."""
- #: Whether this user is muted by the guild.
- #:
- #: :type: :obj:`~bool`
is_guild_muted: bool = marshaller.attrib(raw_name="mute", deserializer=bool)
+ """Whether this user is muted by the guild."""
- #: Whether this user is deafened by their client.
- #:
- #: :type: :obj:`~bool`
is_self_deafened: bool = marshaller.attrib(raw_name="self_deaf", deserializer=bool)
+ """Whether this user is deafened by their client."""
- #: Whether this user is muted by their client.
- #:
- #: :type: :obj:`~bool`
is_self_muted: bool = marshaller.attrib(raw_name="self_mute", deserializer=bool)
+ """Whether this user is muted by their client."""
- #: Whether this user is streaming using "Go Live".
- #:
- #: :type: :obj:`~bool`
is_streaming: bool = marshaller.attrib(raw_name="self_stream", deserializer=bool, if_undefined=False, default=False)
+ """Whether this user is streaming using "Go Live"."""
- #: Whether this user is muted by the current user.
- #:
- #: :type: :obj:`~bool`
is_suppressed: bool = marshaller.attrib(raw_name="suppress", deserializer=bool)
+ """Whether this user is muted by the current user."""
@marshaller.marshallable()
@@ -102,32 +81,20 @@ class VoiceState(bases.HikariEntity, marshaller.Deserializable):
class VoiceRegion(bases.HikariEntity, marshaller.Deserializable):
"""Represent's a voice region server."""
- #: The ID of this region
- #:
- #: :type: :obj:`~str`
id: str = marshaller.attrib(deserializer=str)
+ """The string ID of this region."""
- #: The name of this region
- #:
- #: :type: :obj:`~str`
name: str = marshaller.attrib(deserializer=str)
+ """The name of this region."""
- #: Whether this region is vip-only.
- #:
- #: :type: :obj:`~bool`
is_vip: bool = marshaller.attrib(raw_name="vip", deserializer=bool)
+ """Whether this region is vip-only."""
- #: Whether this region's server is closest to the current user's client.
- #:
- #: :type: :obj:`~bool`
is_optimal_location: bool = marshaller.attrib(raw_name="optimal", deserializer=bool)
+ """Whether this region's server is closest to the current user's client."""
- #: Whether this region is deprecated.
- #:
- #: :type: :obj:`~bool`
is_deprecated: bool = marshaller.attrib(raw_name="deprecated", deserializer=bool)
+ """Whether this region is deprecated."""
- #: Whether this region is custom (e.g. used for events).
- #:
- #: :type: :obj:`~bool`
is_custom: bool = marshaller.attrib(raw_name="custom", deserializer=bool)
+ """Whether this region is custom (e.g. used for events)."""
diff --git a/hikari/webhooks.py b/hikari/webhooks.py
index 39b2553ce2..bae5c916c1 100644
--- a/hikari/webhooks.py
+++ b/hikari/webhooks.py
@@ -33,11 +33,11 @@
class WebhookType(enum.IntEnum):
"""Types of webhook."""
- #: Incoming webhook.
INCOMING = 1
+ """Incoming webhook."""
- #: Channel Follower webhook.
CHANNEL_FOLLOWER = 2
+ """Channel Follower webhook."""
@marshaller.marshallable()
@@ -50,52 +50,36 @@ class Webhook(bases.UniqueEntity, marshaller.Deserializable):
send informational messages to specific channels.
"""
- #: The type of the webhook.
- #:
- #: :type: :obj:`~WebhookType`
type: WebhookType = marshaller.attrib(deserializer=WebhookType)
+ """The type of the webhook."""
- #: The guild ID of the webhook.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`, optional
guild_id: typing.Optional[bases.Snowflake] = marshaller.attrib(
deserializer=bases.Snowflake.deserialize, if_undefined=None, default=None
)
+ """The guild ID of the webhook."""
- #: The channel ID this webhook is for.
- #:
- #: :type: :obj:`~hikari.bases.Snowflake`
channel_id: bases.Snowflake = marshaller.attrib(deserializer=bases.Snowflake.deserialize)
+ """The channel ID this webhook is for."""
- #: The user that created the webhook
- #:
- #: Note
- #: ----
- #: This will be :obj:`~None` when getting a webhook with bot authorization
- #: rather than the webhook's token.
- #:
- #:
- #: :type: :obj:`~hikari.users.User`, optional
user: typing.Optional[users.User] = marshaller.attrib(
deserializer=users.User.deserialize, if_undefined=None, default=None
)
+ """The user that created the webhook
+
+ !!! info
+ This will be `None` when getting a webhook with bot authorization rather
+ than the webhook's token.
+ """
- #: The default name of the webhook.
- #:
- #: :type: :obj:`~str`, optional
name: typing.Optional[str] = marshaller.attrib(deserializer=str, if_none=None)
+ """The default name of the webhook."""
- #: The default avatar hash of the webhook.
- #:
- #: :type: :obj:`~str`, optional
avatar_hash: typing.Optional[str] = marshaller.attrib(raw_name="avatar", deserializer=str, if_none=None)
+ """The default avatar hash of the webhook."""
- #: The token of the webhook.
- #:
- #: Note
- #: ----
- #: This is only available for Incoming webhooks.
- #:
- #:
- #: :type: :obj:`~str`, optional
token: typing.Optional[str] = marshaller.attrib(deserializer=str, if_undefined=None, default=None)
+ """The token of the webhook.
+
+ !!! info
+ This is only available for Incoming webhooks.
+ """
From 7b1188e7763956fc5b4bd65733a228755752ad48 Mon Sep 17 00:00:00 2001
From: Faster Speeding
Date: Tue, 21 Apr 2020 19:47:27 +0100
Subject: [PATCH 185/922] Add gitlab merge review app toolbar script
integration
---
ci/config.py | 1 +
ci/pages.gitlab-ci.yml | 4 ++--
ci/pdoc.nox.py | 18 ++++++++++++++++++
docs/head.mako | 16 +++++++++++++++-
docs/index.html | 31 +++++++++++++++++++++++++++++++
docs/logo.mako | 4 ++--
6 files changed, 69 insertions(+), 5 deletions(-)
create mode 100644 docs/index.html
diff --git a/ci/config.py b/ci/config.py
index c21b474495..ab19383161 100644
--- a/ci/config.py
+++ b/ci/config.py
@@ -32,6 +32,7 @@
# Generating documentation and artifacts.
ARTIFACT_DIRECTORY = "public"
DOCUMENTATION_DIRECTORY = "docs"
+ROOT_INDEX_SOURCE = "index.html"
# Linting and test configs.
PYDOCSTYLE_INI = "pydocstyle.ini"
diff --git a/ci/pages.gitlab-ci.yml b/ci/pages.gitlab-ci.yml
index 8cad99b837..130cc79b8c 100644
--- a/ci/pages.gitlab-ci.yml
+++ b/ci/pages.gitlab-ci.yml
@@ -32,7 +32,7 @@
script: |+
set -x
apt-get update
- apt-get install -qy graphviz git
+ apt-get install -qy graphviz git # FIXME: Remove once in master.
pip install nox
git clone ${CI_REPOSITORY_URL} -b ${TARGET_BRANCH} hikari_docs_${TARGET_BRANCH} --depth=1
cd "hikari_docs_${TARGET_BRANCH}"
@@ -95,7 +95,7 @@
set -e
set -x
apt-get update
- apt-get install -qy graphviz
+ apt-get install -qy graphviz # FIXME: remove once in master
pip install nox
nox -s pdoc || nox -s documentation # FIXME: remove once in master.
except:
diff --git a/ci/pdoc.nox.py b/ci/pdoc.nox.py
index a9cbdb512b..f1cb8ffa1c 100644
--- a/ci/pdoc.nox.py
+++ b/ci/pdoc.nox.py
@@ -17,6 +17,9 @@
# You should have received a copy of the GNU Lesser General Public License
# along with Hikari. If not, see .
"""Pdoc documentation generation."""
+import os
+import shutil
+
from ci import config
from ci import nox
@@ -24,6 +27,21 @@
@nox.session(reuse_venv=True, default=True)
def pdoc(session: nox.Session) -> None:
"""Generate documentation with pdoc."""
+
+ # Inherit environment GitLab CI vars, where appropriate.
+ for n, v in os.environ.items():
+ if n.startswith(("GITLAB_", "CI")) or n == "CI":
+ session.env[n] = v
+
+ #: Copy over the root index html file if it's set.
+ if config.ROOT_INDEX_SOURCE:
+ if not os.path.exists(config.ARTIFACT_DIRECTORY):
+ os.mkdir(config.ARTIFACT_DIRECTORY)
+ shutil.copy(
+ os.path.join(config.DOCUMENTATION_DIRECTORY, config.ROOT_INDEX_SOURCE),
+ os.path.join(config.ARTIFACT_DIRECTORY, "index.html")
+ )
+
session.install("-r", config.REQUIREMENTS, "pdoc3==0.8.1")
session.run(
diff --git a/docs/head.mako b/docs/head.mako
index 34a415341b..28682e2422 100644
--- a/docs/head.mako
+++ b/docs/head.mako
@@ -17,11 +17,25 @@
| along with Hikari. If not, see .
!-->
<%!
+ import os
from pdoc.html_helpers import minify_css
%>
+% if "CI_MERGE_REQUEST_IID" in os.environ:
+
+% endif
-
+% if "." in module.name:
+
+% else:
+
+% endif
diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 0000000000..1a98c715e2
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,31 @@
+
+
+
+
+
+
+
+
+
+
+ Redirecting...
+
+
+
diff --git a/docs/logo.mako b/docs/logo.mako
index 0bd3681aa1..809f1f9cd1 100644
--- a/docs/logo.mako
+++ b/docs/logo.mako
@@ -23,7 +23,7 @@
%>
-
+
Hikari
@@ -31,7 +31,7 @@
% if version == "production":
A new, powerful, sane Python API for writing Discord bots.
+
+ This API is still in a pre-alpha state, and is a work in progress! Features may change
+ or undergo improvements before the design is finalized. Until then, why not join our Discord? Feel free
+ to drop in to ask questions, get updates on progress, and be able to provide valuable contributions and
+ feedback.
+
+
+ Tutorials, tips, and additional resources will come soon!
+
A new, powerful, sane Python API for writing Discord bots.
-
- This API is still in a pre-alpha state, and is a work in progress! Features may change
- or undergo improvements before the design is finalized. Until then, why not join our Discord? Feel free
- to drop in to ask questions, get updates on progress, and be able to provide valuable contributions and
- feedback.
-
-
- Tutorials, tips, and additional resources will come soon!
-
A new, powerful, sane Python API for writing Discord bots.
+
+ This API is still in a pre-alpha state, and is a work in progress! Features may change
+ or undergo improvements before the design is finalized. Until then, why not join our Discord? Feel free
+ to drop in to ask questions, get updates on progress, and be able to provide valuable contributions and
+ feedback.
+
+
+ Tutorials, tips, and additional resources will come soon!
+
+ Hikari
+