Skip to content

Update utils.py documentation #1682

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 9, 2022
Merged

Update utils.py documentation #1682

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b8c8683
Update documentation and __all__
NeloBlivion Oct 8, 2022
cec0630
Update docs for utils.py
NeloBlivion Oct 8, 2022
656f457
Add versionadded info
NeloBlivion Oct 8, 2022
10abae1
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Oct 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 70 additions & 4 deletions discord/utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -88,8 +94,8 @@
"raw_role_mentions",
"as_chunks",
"format_dt",
"basic_autocomplete",
"generate_snowflake",
"basic_autocomplete",
"filter_params",
)

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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 <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:
Expand Down Expand Up @@ -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`
Expand All @@ -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`
Expand All @@ -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`
Expand Down
20 changes: 17 additions & 3 deletions docs/api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -1511,18 +1517,26 @@ 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

.. autofunction:: discord.utils.generate_snowflake

.. 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
Expand Down