Skip to content

Commit

Permalink
Autodoc typehints (#1710)
Browse files Browse the repository at this point in the history 
* Autodoc typehints config

* Remove redundant property types

* Update more property return typings

* Remove remaining property types from docstrings

* Add __future__ annotations import
  • Loading branch information
@BobDotCom
BobDotCom authored Nov 8, 2022
1 parent c795ec7 commit 91ca670
Show file tree
Hide file tree
Showing 55 changed files with 404 additions and 397 deletions.
16 changes: 8 additions & 8 deletions discord/abc.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -229,12 +229,12 @@ class User(Snowflake, Protocol):

@property
def display_name(self) -> str:
""":class:`str`: Returns the user's display name."""
"""Returns the user's display name."""
raise NotImplementedError

@property
def mention(self) -> str:
""":class:`str`: Returns a string that allows you to mention the given user."""
"""Returns a string that allows you to mention the given user."""
raise NotImplementedError


Expand Down Expand Up @@ -507,7 +507,7 @@ def _fill_overwrites(self, data: GuildChannelPayload) -> None:

@property
def changed_roles(self) -> list[Role]:
"""List[:class:`~discord.Role`]: Returns a list of roles that have been overridden from
"""Returns a list of roles that have been overridden from
their default values in the :attr:`~discord.Guild.roles` attribute.
"""
ret = []
Expand All @@ -524,20 +524,20 @@ def changed_roles(self) -> list[Role]:

@property
def mention(self) -> str:
""":class:`str`: The string that allows you to mention the channel."""
"""The string that allows you to mention the channel."""
return f"<#{self.id}>"

@property
def jump_url(self) -> str:
""":class:`str`: Returns a URL that allows the client to jump to the channel.
"""Returns a URL that allows the client to jump to the channel.
.. versionadded:: 2.0
"""
return f"https://discord.com/channels/{self.guild.id}/{self.id}"

@property
def created_at(self) -> datetime:
""":class:`datetime.datetime`: Returns the channel's creation time in UTC."""
"""Returns the channel's creation time in UTC."""
return utils.snowflake_time(self.id)

def overwrites_for(self, obj: Role | User) -> PermissionOverwrite:
Expand Down Expand Up @@ -606,15 +606,15 @@ def overwrites(self) -> dict[Role | Member, PermissionOverwrite]:

@property
def category(self) -> CategoryChannel | None:
"""Optional[:class:`~discord.CategoryChannel`]: The category this channel belongs to.
"""The category this channel belongs to.
If there is no category then this is ``None``.
"""
return self.guild.get_channel(self.category_id) # type: ignore

@property
def permissions_synced(self) -> bool:
""":class:`bool`: Whether the permissions for this channel are synced with the
"""Whether the permissions for this channel are synced with the
category it belongs to.
If there is no category then this is ``False``.
Expand Down
60 changes: 30 additions & 30 deletions discord/activity.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ def __init__(self, **kwargs):

@property
def created_at(self) -> datetime.datetime | None:
"""Optional[:class:`datetime.datetime`]: When the user started doing this activity in UTC.
"""When the user started doing this activity in UTC.
.. versionadded:: 1.3
"""
Expand Down Expand Up @@ -279,7 +279,7 @@ def to_dict(self) -> dict[str, Any]:

@property
def start(self) -> datetime.datetime | None:
"""Optional[:class:`datetime.datetime`]: When the user started doing this activity in UTC, if applicable."""
"""When the user started doing this activity in UTC, if applicable."""
try:
timestamp = self.timestamps["start"] / 1000
except KeyError:
Expand All @@ -289,7 +289,7 @@ def start(self) -> datetime.datetime | None:

@property
def end(self) -> datetime.datetime | None:
"""Optional[:class:`datetime.datetime`]: When the user will stop doing this activity in UTC, if applicable."""
"""When the user will stop doing this activity in UTC, if applicable."""
try:
timestamp = self.timestamps["end"] / 1000
except KeyError:
Expand All @@ -299,7 +299,7 @@ def end(self) -> datetime.datetime | None:

@property
def large_image_url(self) -> str | None:
"""Optional[:class:`str`]: Returns a URL pointing to the large image asset of this activity if applicable."""
"""Returns a URL pointing to the large image asset of this activity if applicable."""
if self.application_id is None:
return None

Expand All @@ -312,7 +312,7 @@ def large_image_url(self) -> str | None:

@property
def small_image_url(self) -> str | None:
"""Optional[:class:`str`]: Returns a URL pointing to the small image asset of this activity if applicable."""
"""Returns a URL pointing to the small image asset of this activity if applicable."""
if self.application_id is None:
return None

Expand All @@ -325,12 +325,12 @@ def small_image_url(self) -> str | None:

@property
def large_image_text(self) -> str | None:
"""Optional[:class:`str`]: Returns the large image asset hover text of this activity if applicable."""
"""Returns the large image asset hover text of this activity if applicable."""
return self.assets.get("large_text", None)

@property
def small_image_text(self) -> str | None:
"""Optional[:class:`str`]: Returns the small image asset hover text of this activity if applicable."""
"""Returns the small image asset hover text of this activity if applicable."""
return self.assets.get("small_text", None)


Expand Down Expand Up @@ -385,15 +385,15 @@ def __init__(self, name: str, **extra):

@property
def type(self) -> ActivityType:
""":class:`ActivityType`: Returns the game's type. This is for compatibility with :class:`Activity`.
"""Returns the game's type. This is for compatibility with :class:`Activity`.
It always returns :attr:`ActivityType.playing`.
"""
return ActivityType.playing

@property
def start(self) -> datetime.datetime | None:
"""Optional[:class:`datetime.datetime`]: When the user started playing this game in UTC, if applicable."""
"""When the user started playing this game in UTC, if applicable."""
if self._start:
return datetime.datetime.fromtimestamp(
self._start / 1000, tz=datetime.timezone.utc
Expand All @@ -402,7 +402,7 @@ def start(self) -> datetime.datetime | None:

@property
def end(self) -> datetime.datetime | None:
"""Optional[:class:`datetime.datetime`]: When the user will stop playing this game in UTC, if applicable."""
"""When the user will stop playing this game in UTC, if applicable."""
if self._end:
return datetime.datetime.fromtimestamp(
self._end / 1000, tz=datetime.timezone.utc
Expand Down Expand Up @@ -497,7 +497,7 @@ def __init__(self, *, name: str | None, url: str, **extra: Any):

@property
def type(self) -> ActivityType:
""":class:`ActivityType`: Returns the game's type. This is for compatibility with :class:`Activity`.
"""Returns the game's type. This is for compatibility with :class:`Activity`.
It always returns :attr:`ActivityType.streaming`.
"""
Expand All @@ -510,8 +510,8 @@ def __repr__(self) -> str:
return f"<Streaming name={self.name!r}>"

@property
def twitch_name(self):
"""Optional[:class:`str`]: If provided, the twitch name of the user streaming.
def twitch_name(self) -> str | None:
"""If provided, the twitch name of the user streaming.
This corresponds to the ``large_image`` key of the :attr:`Streaming.assets`
dictionary if it starts with ``twitch:``. Typically this is set by the Discord client.
Expand Down Expand Up @@ -595,15 +595,15 @@ def __init__(self, **data):

@property
def type(self) -> ActivityType:
""":class:`ActivityType`: Returns the activity's type. This is for compatibility with :class:`Activity`.
"""Returns the activity's type. This is for compatibility with :class:`Activity`.
It always returns :attr:`ActivityType.listening`.
"""
return ActivityType.listening

@property
def created_at(self) -> datetime.datetime | None:
"""Optional[:class:`datetime.datetime`]: When the user started listening in UTC.
"""When the user started listening in UTC.
.. versionadded:: 1.3
"""
Expand All @@ -614,15 +614,15 @@ def created_at(self) -> datetime.datetime | None:

@property
def colour(self) -> Colour:
""":class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`.
"""Returns the Spotify integration colour, as a :class:`Colour`.
There is an alias for this named :attr:`color`
"""
return Colour(0x1DB954)

@property
def color(self) -> Colour:
""":class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`.
"""Returns the Spotify integration colour, as a :class:`Colour`.
There is an alias for this named :attr:`colour`
"""
Expand All @@ -643,7 +643,7 @@ def to_dict(self) -> dict[str, Any]:

@property
def name(self) -> str:
""":class:`str`: The activity's name. This will always return "Spotify"."""
"""The activity's name. This will always return "Spotify"."""
return "Spotify"

def __eq__(self, other: Any) -> bool:
Expand Down Expand Up @@ -671,17 +671,17 @@ def __repr__(self) -> str:

@property
def title(self) -> str:
""":class:`str`: The title of the song being played."""
"""The title of the song being played."""
return self._details

@property
def artists(self) -> list[str]:
"""List[:class:`str`]: The artists of the song being played."""
"""The artists of the song being played."""
return self._state.split("; ")

@property
def artist(self) -> str:
""":class:`str`: The artist of the song being played.
"""The artist of the song being played.
This does not attempt to split the artist information into
multiple artists. Useful if there's only a single artist.
Expand All @@ -690,12 +690,12 @@ def artist(self) -> str:

@property
def album(self) -> str:
""":class:`str`: The album that the song being played belongs to."""
"""The album that the song being played belongs to."""
return self._assets.get("large_text", "")

@property
def album_cover_url(self) -> str:
""":class:`str`: The album cover image URL from Spotify's CDN."""
"""The album cover image URL from Spotify's CDN."""
large_image = self._assets.get("large_image", "")
if large_image[:8] != "spotify:":
return ""
Expand All @@ -704,39 +704,39 @@ def album_cover_url(self) -> str:

@property
def track_id(self) -> str:
""":class:`str`: The track ID used by Spotify to identify this song."""
"""The track ID used by Spotify to identify this song."""
return self._sync_id

@property
def track_url(self) -> str:
""":class:`str`: The track URL to listen on Spotify.
"""The track URL to listen on Spotify.
.. versionadded:: 2.0
"""
return f"https://open.spotify.com/track/{self.track_id}"

@property
def start(self) -> datetime.datetime:
""":class:`datetime.datetime`: When the user started playing this song in UTC."""
"""When the user started playing this song in UTC."""
return datetime.datetime.fromtimestamp(
self._timestamps["start"] / 1000, tz=datetime.timezone.utc
)

@property
def end(self) -> datetime.datetime:
""":class:`datetime.datetime`: When the user will stop playing this song in UTC."""
"""When the user will stop playing this song in UTC."""
return datetime.datetime.fromtimestamp(
self._timestamps["end"] / 1000, tz=datetime.timezone.utc
)

@property
def duration(self) -> datetime.timedelta:
""":class:`datetime.timedelta`: The duration of the song being played."""
"""The duration of the song being played."""
return self.end - self.start

@property
def party_id(self) -> str:
""":class:`str`: The party ID of the listening party."""
"""The party ID of the listening party."""
return self._party.get("id", "")


Expand Down Expand Up @@ -799,7 +799,7 @@ def __init__(

@property
def type(self) -> ActivityType:
""":class:`ActivityType`: Returns the activity's type. This is for compatibility with :class:`Activity`.
"""Returns the activity's type. This is for compatibility with :class:`Activity`.
It always returns :attr:`ActivityType.custom`.
"""
Expand Down
8 changes: 4 additions & 4 deletions discord/appinfo.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -171,14 +171,14 @@ def __repr__(self) -> str:

@property
def icon(self) -> Asset | None:
"""Optional[:class:`.Asset`]: Retrieves the application's icon asset, if any."""
"""Retrieves the application's icon asset, if any."""
if self._icon is None:
return None
return Asset._from_icon(self._state, self.id, self._icon, path="app")

@property
def cover_image(self) -> Asset | None:
"""Optional[:class:`.Asset`]: Retrieves the cover image on a store embed, if any.
"""Retrieves the cover image on a store embed, if any.
This is only available if the application is a game sold on Discord.
"""
Expand All @@ -188,7 +188,7 @@ def cover_image(self) -> Asset | None:

@property
def guild(self) -> Guild | None:
"""Optional[:class:`Guild`]: If this application is a game sold on Discord,
"""If this application is a game sold on Discord,
this field will be the guild to which it has been linked.
.. versionadded:: 1.3
Expand Down Expand Up @@ -253,7 +253,7 @@ def __repr__(self) -> str:

@property
def icon(self) -> Asset | None:
"""Optional[:class:`.Asset`]: Retrieves the application's icon asset, if any."""
"""Retrieves the application's icon asset, if any."""
if self._icon is None:
return None
return Asset._from_icon(self._state, self.id, self._icon, path="app")
6 changes: 3 additions & 3 deletions discord/asset.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -288,16 +288,16 @@ def __hash__(self):

@property
def url(self) -> str:
""":class:`str`: Returns the underlying URL of the asset."""
"""Returns the underlying URL of the asset."""
return self._url

@property
def key(self) -> str:
""":class:`str`: Returns the identifying key of the asset."""
"""Returns the identifying key of the asset."""
return self._key

def is_animated(self) -> bool:
""":class:`bool`: Returns whether the asset is animated."""
"""Returns whether the asset is animated."""
return self._animated

def replace(
Expand Down
Loading

0 comments on commit 91ca670

Please sign in to comment.