lint(docs): add basic pydocstyle rules (DisnakeDev#957)

Add some pydocstyle rules to the ruff configuration. These rules are all
automatically fixed, and there was no manual changes. This should make
it easy to add, because merge conflicts can be fixed by just running
ruff.

Author: onerandomusername

disnake/__init__.py

@@ -1,7 +1,6 @@
 # SPDX-License-Identifier: MIT
 
-"""
-Discord API Wrapper
+"""Discord API Wrapper
 ~~~~~~~~~~~~~~~~~~~
 
 A basic wrapper for the Discord API.

disnake/abc.py

@@ -483,7 +483,8 @@ def _fill_overwrites(self, data: GuildChannelPayload) -> None:
     @property
     def changed_roles(self) -> List[Role]:
         """List[:class:`.Role`]: Returns a list of roles that have been overridden from
-        their default values in the :attr:`.Guild.roles` attribute."""
+        their default values in the :attr:`.Guild.roles` attribute.
+        """
         ret = []
         g = self.guild
         for overwrite in filter(lambda o: o.is_role(), self._overwrites):
@@ -603,8 +604,7 @@ def flags(self) -> ChannelFlags:
 
     @property
     def jump_url(self) -> str:
-        """
-        A URL that can be used to jump to this channel.
+        """A URL that can be used to jump to this channel.
 
         .. versionadded:: 2.4
 
@@ -881,8 +881,7 @@ async def set_permissions(
     async def set_permissions(
         self, target, *, overwrite=MISSING, reason=None, **permissions
     ) -> None:
-        """
-        |coro|
+        """|coro|
 
         Sets the channel specific permission overwrites for a target in the
         channel.

disnake/activity.py

@@ -610,14 +610,16 @@ def type(self) -> Literal[ActivityType.listening]:
     def colour(self) -> Colour:
         """:class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`.
 
-        There is an alias for this named :attr:`color`"""
+        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`.
 
-        There is an alias for this named :attr:`colour`"""
+        There is an alias for this named :attr:`colour`
+        """
         return self.colour
 
     def to_dict(self) -> Dict[str, Any]:

disnake/app_commands.py

@@ -364,7 +364,8 @@ def add_option(
         max_length: Optional[int] = None,
     ) -> None:
         """Adds an option to the current list of options,
-        parameters are the same as for :class:`Option`."""
+        parameters are the same as for :class:`Option`.
+        """
         type = type or OptionType.string
         self.options.append(
             Option(
@@ -428,8 +429,7 @@ def localize(self, store: LocalizationProtocol) -> None:
 
 
 class ApplicationCommand(ABC):
-    """
-    The base class for application commands.
+    """The base class for application commands.
 
     The following classes implement this ABC:
 
@@ -580,8 +580,7 @@ def _update_common(self, data: ApplicationCommandPayload) -> None:
 
 
 class UserCommand(ApplicationCommand):
-    """
-    A user context menu command.
+    """A user context menu command.
 
     Attributes
     ----------
@@ -624,8 +623,7 @@ def __init__(
 
 
 class APIUserCommand(UserCommand, _APIApplicationCommandMixin):
-    """
-    A user context menu command returned by the API.
+    """A user context menu command returned by the API.
 
     .. versionadded:: 2.4
 
@@ -677,8 +675,7 @@ def from_dict(cls, data: ApplicationCommandPayload) -> Self:
 
 
 class MessageCommand(ApplicationCommand):
-    """
-    A message context menu command
+    """A message context menu command
 
     Attributes
     ----------
@@ -721,8 +718,7 @@ def __init__(
 
 
 class APIMessageCommand(MessageCommand, _APIApplicationCommandMixin):
-    """
-    A message context menu command returned by the API.
+    """A message context menu command returned by the API.
 
     .. versionadded:: 2.4
 
@@ -774,8 +770,7 @@ def from_dict(cls, data: ApplicationCommandPayload) -> Self:
 
 
 class SlashCommand(ApplicationCommand):
-    """
-    The base class for building slash commands.
+    """The base class for building slash commands.
 
     Attributes
     ----------
@@ -905,8 +900,7 @@ def localize(self, store: LocalizationProtocol) -> None:
 
 
 class APISlashCommand(SlashCommand, _APIApplicationCommandMixin):
-    """
-    A slash command returned by the API.
+    """A slash command returned by the API.
 
     .. versionadded:: 2.4
 

disnake/audit_logs.py

@@ -507,8 +507,7 @@ class _AuditLogProxyAutoModBlockMessage:
 
 
 class AuditLogEntry(Hashable):
-    """
-    Represents an Audit Log entry.
+    """Represents an Audit Log entry.
 
     You retrieve these via :meth:`Guild.audit_logs`.
 

disnake/automod.py

@@ -60,8 +60,7 @@
 
 
 class AutoModAction:
-    """
-    A base class for auto moderation actions.
+    """A base class for auto moderation actions.
 
     This class is not meant to be instantiated by the user.
     The user-constructible subclasses are:
@@ -111,8 +110,7 @@ def to_dict(self) -> AutoModActionPayload:
 
 
 class AutoModBlockMessageAction(AutoModAction):
-    """
-    Represents an auto moderation action that blocks content from being sent.
+    """Represents an auto moderation action that blocks content from being sent.
 
     .. versionadded:: 2.6
 
@@ -154,8 +152,7 @@ def __repr__(self) -> str:
 
 
 class AutoModSendAlertAction(AutoModAction):
-    """
-    Represents an auto moderation action that sends an alert to a channel.
+    """Represents an auto moderation action that sends an alert to a channel.
 
     .. versionadded:: 2.6
 
@@ -190,8 +187,7 @@ def __repr__(self) -> str:
 
 
 class AutoModTimeoutAction(AutoModAction):
-    """
-    Represents an auto moderation action that times out the user.
+    """Represents an auto moderation action that times out the user.
 
     .. versionadded:: 2.6
 
@@ -221,16 +217,16 @@ def __init__(self, duration: Union[int, timedelta]) -> None:
     @property
     def duration(self) -> int:
         """:class:`int`: The duration (in seconds) for which to timeout
-        the user when the rule is triggered."""
+        the user when the rule is triggered.
+        """
         return self._metadata["duration_seconds"]
 
     def __repr__(self) -> str:
         return f"<{type(self).__name__} duration={self.duration!r}>"
 
 
 class AutoModTriggerMetadata:
-    """
-    Metadata for an auto moderation trigger.
+    """Metadata for an auto moderation trigger.
 
     Based on the trigger type, different fields can be used with various limits:
 
@@ -342,8 +338,7 @@ def with_changes(
         allow_list: Optional[Sequence[str]] = MISSING,
         mention_total_limit: Optional[int] = MISSING,
     ) -> Self:
-        """
-        Returns a new instance with the given changes applied.
+        """Returns a new instance with the given changes applied.
         All other fields will be kept intact.
 
         Returns
@@ -406,8 +401,7 @@ def __repr__(self) -> str:
 
 
 class AutoModRule:
-    """
-    Represents an auto moderation rule.
+    """Represents an auto moderation rule.
 
     .. versionadded:: 2.6
 
@@ -478,7 +472,8 @@ def __init__(self, *, data: AutoModRulePayload, guild: Guild) -> None:
     @property
     def actions(self) -> List[AutoModAction]:
         """List[Union[:class:`AutoModBlockMessageAction`, :class:`AutoModSendAlertAction`, :class:`AutoModTimeoutAction`, :class:`AutoModAction`]]:
-        The list of actions that will execute if a matching event triggered this rule."""
+        The list of actions that will execute if a matching event triggered this rule.
+        """
         return list(self._actions)  # return a copy
 
     @property
@@ -593,7 +588,6 @@ async def edit(
         :class:`AutoModRule`
             The newly updated auto moderation rule.
         """
-
         payload: EditAutoModRulePayload = {}
 
         if name is not MISSING:
@@ -748,14 +742,16 @@ def channel(self) -> Optional[Union[GuildChannel, Thread]]:
     def message(self) -> Optional[Message]:
         """Optional[:class:`Message`]: The message that matched, if any.
         Not available if the message was blocked, if the content was not part of a message,
-        or if the message was not found in the message cache."""
+        or if the message was not found in the message cache.
+        """
         return self.guild._state._get_message(self.message_id)
 
     @property
     def alert_message(self) -> Optional[Message]:
         """Optional[:class:`Message`]: The alert message sent as a result of this action, if any.
         Only available if :attr:`action.type <AutoModAction.type>` is :attr:`~AutoModActionType.send_alert_message`
-        and the message was found in the message cache."""
+        and the message was found in the message cache.
+        """
         return self.guild._state._get_message(self.alert_message_id)
 
 

disnake/channel.py

@@ -3825,8 +3825,7 @@ def created_at(self) -> datetime.datetime:
 
     @property
     def jump_url(self) -> str:
-        """
-        A URL that can be used to jump to this channel.
+        """A URL that can be used to jump to this channel.
 
         .. versionadded:: 2.4
         """

disnake/client.py

@@ -183,8 +183,7 @@ def __repr__(self) -> str:
 
 
 class GatewayParams(NamedTuple):
-    """
-    Container type for configuring gateway connections.
+    """Container type for configuring gateway connections.
 
     .. versionadded:: 2.6
 
@@ -203,8 +202,7 @@ class GatewayParams(NamedTuple):
 
 
 class Client:
-    """
-    Represents a client connection that connects to Discord.
+    """Represents a client connection that connects to Discord.
     This class is used to interact with the Discord WebSocket and API.
 
     A number of options can be passed to the :class:`Client`.
@@ -1383,8 +1381,7 @@ def get_guild_application_commands(self, guild_id: int) -> List[APIApplicationCo
         return list(data.values())
 
     def get_guild_slash_commands(self, guild_id: int) -> List[APISlashCommand]:
-        """
-        Returns a list of all slash commands in the guild with the given ID.
+        """Returns a list of all slash commands in the guild with the given ID.
 
         Parameters
         ----------
@@ -1400,8 +1397,7 @@ def get_guild_slash_commands(self, guild_id: int) -> List[APISlashCommand]:
         return [cmd for cmd in data.values() if isinstance(cmd, APISlashCommand)]
 
     def get_guild_user_commands(self, guild_id: int) -> List[APIUserCommand]:
-        """
-        Returns a list of all user commands in the guild with the given ID.
+        """Returns a list of all user commands in the guild with the given ID.
 
         Parameters
         ----------
@@ -1417,8 +1413,7 @@ def get_guild_user_commands(self, guild_id: int) -> List[APIUserCommand]:
         return [cmd for cmd in data.values() if isinstance(cmd, APIUserCommand)]
 
     def get_guild_message_commands(self, guild_id: int) -> List[APIMessageCommand]:
-        """
-        Returns a list of all message commands in the guild with the given ID.
+        """Returns a list of all message commands in the guild with the given ID.
 
         Parameters
         ----------
@@ -1434,8 +1429,7 @@ def get_guild_message_commands(self, guild_id: int) -> List[APIMessageCommand]:
         return [cmd for cmd in data.values() if isinstance(cmd, APIMessageCommand)]
 
     def get_global_command(self, id: int) -> Optional[APIApplicationCommand]:
-        """
-        Returns a global application command with the given ID.
+        """Returns a global application command with the given ID.
 
         Parameters
         ----------
@@ -1450,8 +1444,7 @@ def get_global_command(self, id: int) -> Optional[APIApplicationCommand]:
         return self._connection._get_global_application_command(id)
 
     def get_guild_command(self, guild_id: int, id: int) -> Optional[APIApplicationCommand]:
-        """
-        Returns a guild application command with the given guild ID and application command ID.
+        """Returns a guild application command with the given guild ID and application command ID.
 
         Parameters
         ----------
@@ -1470,8 +1463,7 @@ def get_guild_command(self, guild_id: int, id: int) -> Optional[APIApplicationCo
     def get_global_command_named(
         self, name: str, cmd_type: Optional[ApplicationCommandType] = None
     ) -> Optional[APIApplicationCommand]:
-        """
-        Returns a global application command matching the given name.
+        """Returns a global application command matching the given name.
 
         Parameters
         ----------
@@ -1490,8 +1482,7 @@ def get_global_command_named(
     def get_guild_command_named(
         self, guild_id: int, name: str, cmd_type: Optional[ApplicationCommandType] = None
     ) -> Optional[APIApplicationCommand]:
-        """
-        Returns a guild application command matching the given name.
+        """Returns a guild application command matching the given name.
 
         Parameters
         ----------