diff --git a/discord/utils.py b/discord/utils.py index cf59e979d1..c746b89b3c 100644 --- a/discord/utils.py +++ b/discord/utils.py @@ -73,13 +73,19 @@ __all__ = ( + "parse_time", + "warn_deprecated", + "deprecated", "oauth_url", "snowflake_time", "time_snowflake", "find", "get", + "get_or_fetch", "sleep_until", "utcnow", + "resolve_invite", + "resolve_template", "remove_markdown", "escape_markdown", "escape_mentions", @@ -88,8 +94,8 @@ "raw_role_mentions", "as_chunks", "format_dt", - "basic_autocomplete", "generate_snowflake", + "basic_autocomplete", "filter_params", ) @@ -252,6 +258,18 @@ def parse_time(timestamp: str | None) -> datetime.datetime | None: def parse_time(timestamp: str | None) -> datetime.datetime | None: + """A helper function to convert an ISO 8601 timestamp to a datetime object. + + Parameters + ---------- + timestamp: Optional[:class:`str`] + The timestamp to convert. + + Returns + ------- + Optional[:class:`datetime.datetime`] + The converted datetime object. + """ if timestamp: return datetime.datetime.fromisoformat(timestamp) return None @@ -408,7 +426,8 @@ def oauth_url( def snowflake_time(id: int) -> datetime.datetime: - """ + """Converts a Discord snowflake ID to a UTC-aware datetime object. + Parameters ---------- id: :class:`int` @@ -542,8 +561,49 @@ def get(iterable: Iterable[T], **attrs: Any) -> T | None: return None -async def get_or_fetch(obj, attr: str, id: int, *, default: Any = MISSING): - # TODO: Document this +async def get_or_fetch(obj, attr: str, id: int, *, default: Any = MISSING) -> Any: + """This is a :ref:`coroutine ` + Attempts to get an attribute from the object in cache. If it fails, it will attempt to fetch it. + If the fetch also fails, an error will be raised. + + Parameters + ---------- + obj: Any + The object to use the get or fetch methods in + attr: :class:`str` + The attribute to get or fetch. Note the object must have both a ``get_`` and ``fetch_`` method for this attribute. + id: :class:`int` + The ID of the object + default: Any + The default value to return if the object is not found, instead of raising an error. + + Returns + ------- + Any + The object found or the default value. + + Raises + ------ + :exc:`AttributeError` + The object is missing a ``get_`` or ``fetch_`` method + :exc:`NotFound` + Invalid ID for the object + :exc:`HTTPException` + An error occurred fetching the object + :exc:`Forbidden` + You do not have permission to fetch the object + + Examples + -------- + + Getting a guild from a guild ID: :: + + guild = await utils.get_or_fetch(client, 'guild', guild_id) + + Getting a channel from the guild. If the channel is not found, return None: :: + + channel = await utils.get_or_fetch(guild, 'channel', channel_id, default=None) + """ getter = getattr(obj, f"get_{attr}")(id) if getter is None: try: @@ -944,6 +1004,8 @@ def escape_mentions(text: str) -> str: def raw_mentions(text: str) -> list[int]: """Returns a list of user IDs matching ``<@user_id>`` in the string. + .. versionadded:: 2.2 + Parameters ---------- text: :class:`str` @@ -960,6 +1022,8 @@ def raw_mentions(text: str) -> list[int]: def raw_channel_mentions(text: str) -> list[int]: """Returns a list of channel IDs matching ``<@#channel_id>`` in the string. + .. versionadded:: 2.2 + Parameters ---------- text: :class:`str` @@ -976,6 +1040,8 @@ def raw_channel_mentions(text: str) -> list[int]: def raw_role_mentions(text: str) -> list[int]: """Returns a list of role IDs matching ``<@&role_id>`` in the string. + .. versionadded:: 2.2 + Parameters ---------- text: :class:`str` diff --git a/docs/api.rst b/docs/api.rst index fa2c9fe215..8c390adcaf 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1493,7 +1493,7 @@ Utility Functions .. autofunction:: discord.utils.get -.. autofunction:: discord.utils.snowflake_time +.. autofunction:: discord.utils.get_or_fetch .. autofunction:: discord.utils.oauth_url @@ -1503,6 +1503,12 @@ Utility Functions .. autofunction:: discord.utils.escape_mentions +.. autofunction:: discord.utils.raw_mentions + +.. autofunction:: discord.utils.raw_channel_mentions + +.. autofunction:: discord.utils.raw_role_mentions + .. autofunction:: discord.utils.resolve_invite .. autofunction:: discord.utils.resolve_template @@ -1511,9 +1517,11 @@ Utility Functions .. autofunction:: discord.utils.utcnow -.. autofunction:: discord.utils.format_dt +.. autofunction:: discord.utils.snowflake_time -.. autofunction:: discord.utils.as_chunks +.. autofunction:: discord.utils.parse_time + +.. autofunction:: discord.utils.format_dt .. autofunction:: discord.utils.time_snowflake @@ -1521,8 +1529,14 @@ Utility Functions .. autofunction:: discord.utils.basic_autocomplete +.. autofunction:: discord.utils.as_chunks + .. autofunction:: discord.utils.filter_params +.. autofunction:: discord.utils.warn_deprecated + +.. autofunction:: discord.utils.deprecated + .. _discord-api-enums: Enumerations