Some consistency fixes for arg positionality + have black skip magic …

…commas (#451)
FasterSpeeding · Dec 1, 2022 · a06b43d · a06b43d
1 parent 304cfe5
commit a06b43d
Show file tree

Hide file tree

Showing 44 changed files with 355 additions and 1,149 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -39,6 +39,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   [int][] nor [float][] to be passed.
 - [TimeSchedule.\_\_init\_\_][tanjun.schedules.TimeSchedule.__init__] and [tanjun.as_time_schedule][] now
   raise a [TypeError][] instead of [ValueError][] when a float is passed in or for any of its arguments.
+- The arguments for [tanjun.clients.on_parser_error][] and
+  [Client.set_human_only][tanjun.Client.set_human_only].
+- The signatures of several internally used but publicly exported functions have been fixed to ensure
+  they better follow the library's rules for positional and keyword arguments.
+  For more information see <>.
 
 ### Deprecated
 - `BaseConverter.async_caches`, `BaseConverter.cache_components` and `BaseConverter.intents`.

diff --git a/pyproject.toml b/pyproject.toml
@@ -40,10 +40,11 @@ Changelog = "https://github.com/FasterSpeeding/tanjun/blob/master/CHANGELOG.md"
 name = "tanjun"
 
 [tool.black]
-line-length     = 120
-target-version  = ["py39"]
-include         = ".*pyi?$"
+line-length = 120
+target-version = ["py39"]
+include = ".*pyi?$"
 extend-exclude = ["^/tanjun/_internal/vendor/.*"]
+skip-magic-trailing-comma = true
 
 [tool.coverage.run]
 concurrency = ["multiprocessing"]

diff --git a/tanjun/_internal/__init__.py b/tanjun/_internal/__init__.py
@@ -130,7 +130,7 @@ class CastedView(collections.Mapping[_KeyT, _OtherT], typing.Generic[_KeyT, _Oth
 
     __slots__ = ("_buffer", "_cast", "_raw_data")
 
-    def __init__(self, raw_data: dict[_KeyT, _T], cast: collections.Callable[[_T], _OtherT]) -> None:
+    def __init__(self, raw_data: dict[_KeyT, _T], cast: collections.Callable[[_T], _OtherT], /) -> None:
         self._buffer: dict[_KeyT, _OtherT] = {} if raw_data else _EMPTY_BUFFER
         self._cast = cast
         self._raw_data = raw_data
@@ -157,7 +157,7 @@ def __len__(self) -> int:
 _KEYWORD_TYPES = {inspect.Parameter.KEYWORD_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD}
 
 
-def get_kwargs(callback: collections.Callable[..., typing.Any]) -> list[str] | None:
+def get_kwargs(callback: collections.Callable[..., typing.Any], /) -> list[str] | None:
     """Get a list of the keyword argument names for a callback.
 
     Parameters
@@ -288,7 +288,7 @@ class _WrappedProto(typing.Protocol):
     wrapped_command: typing.Optional[tanjun.ExecutableCommand[typing.Any]]
 
 
-def _has_wrapped(value: typing.Any) -> typing_extensions.TypeGuard[_WrappedProto]:
+def _has_wrapped(value: typing.Any, /) -> typing_extensions.TypeGuard[_WrappedProto]:
     try:
         value.wrapped_command
 
@@ -298,7 +298,7 @@ def _has_wrapped(value: typing.Any) -> typing_extensions.TypeGuard[_WrappedProto
     return True
 
 
-def collect_wrapped(command: tanjun.ExecutableCommand[typing.Any]) -> list[tanjun.ExecutableCommand[typing.Any]]:
+def collect_wrapped(command: tanjun.ExecutableCommand[typing.Any], /) -> list[tanjun.ExecutableCommand[typing.Any]]:
     """Collect all the commands a command object has wrapped in decorator calls.
 
     Parameters
@@ -411,6 +411,7 @@ def parse_channel_types(*channel_types: typing.Union[type[hikari.PartialChannel]
 def cmp_command(
     cmd: typing.Union[hikari.PartialCommand, hikari.api.CommandBuilder],
     other: typing.Union[hikari.PartialCommand, hikari.api.CommandBuilder, None],
+    /,
 ) -> bool:
     """Compare application command objects and command builders."""
     if not other or other.type != cmd.type:

diff --git a/tanjun/_internal/localisation.py b/tanjun/_internal/localisation.py
@@ -213,13 +213,7 @@ def assert_length(self, min_length: int, max_length: int, /) -> Self:
 
 
 @typing.overload
-def to_localise_id(
-    command_type: _CommandTypes,
-    command_name: str,
-    field_type: _NamedFields,
-    field_name: str,
-    /,
-) -> str:
+def to_localise_id(command_type: _CommandTypes, command_name: str, field_type: _NamedFields, field_name: str, /) -> str:
     ...
 
 
@@ -235,11 +229,7 @@ def to_localise_id(
 
 
 def to_localise_id(
-    command_type: _CommandTypes,
-    command_name: str,
-    field_type: _FieldType,
-    field_name: typing.Optional[str] = None,
-    /,
+    command_type: _CommandTypes, command_name: str, field_type: _FieldType, field_name: typing.Optional[str] = None, /
 ) -> str:
     """Generate an ID for a localised field.
 

diff --git a/tanjun/abc.py b/tanjun/abc.py
@@ -2316,40 +2316,28 @@ async def on_success(ctx: tanjun.abc.Context) -> None:
     async def trigger_error(
         self,
         ctx: _ContextT_contra,
-        /,
         exception: Exception,
+        /,
         *,
         hooks: typing.Optional[collections.Set[Hooks[_ContextT_contra]]] = None,
     ) -> int:
         raise NotImplementedError
 
     @abc.abstractmethod
     async def trigger_post_execution(
-        self,
-        ctx: _ContextT_contra,
-        /,
-        *,
-        hooks: typing.Optional[collections.Set[Hooks[_ContextT_contra]]] = None,
+        self, ctx: _ContextT_contra, /, *, hooks: typing.Optional[collections.Set[Hooks[_ContextT_contra]]] = None
     ) -> None:
         raise NotImplementedError
 
     @abc.abstractmethod
     async def trigger_pre_execution(
-        self,
-        ctx: _ContextT_contra,
-        /,
-        *,
-        hooks: typing.Optional[collections.Set[Hooks[_ContextT_contra]]] = None,
+        self, ctx: _ContextT_contra, /, *, hooks: typing.Optional[collections.Set[Hooks[_ContextT_contra]]] = None
     ) -> None:
         raise NotImplementedError
 
     @abc.abstractmethod
     async def trigger_success(
-        self,
-        ctx: _ContextT_contra,
-        /,
-        *,
-        hooks: typing.Optional[collections.Set[Hooks[_ContextT_contra]]] = None,
+        self, ctx: _ContextT_contra, /, *, hooks: typing.Optional[collections.Set[Hooks[_ContextT_contra]]] = None
     ) -> None:
         raise NotImplementedError
 
@@ -2672,18 +2660,16 @@ async def execute(
         self,
         ctx: SlashContext,
         /,
-        option: typing.Optional[hikari.CommandInteractionOption] = None,
         *,
+        option: typing.Optional[hikari.CommandInteractionOption] = None,
         hooks: typing.Optional[collections.MutableSet[SlashHooks]] = None,
     ) -> None:
         raise NotImplementedError
         ...
 
+    @abc.abstractmethod
     async def execute_autocomplete(
-        self,
-        ctx: AutocompleteContext,
-        /,
-        option: typing.Optional[hikari.AutocompleteInteractionOption] = None,
+        self, ctx: AutocompleteContext, /, *, option: typing.Optional[hikari.AutocompleteInteractionOption] = None
     ) -> None:
         ...
 
@@ -3432,11 +3418,7 @@ def unbind_client(self, client: Client, /) -> Self:
 
     @abc.abstractmethod
     def check_message_name(
-        self,
-        name: str,
-        /,
-        *,
-        case_sensitive: bool = True,
+        self, name: str, /, *, case_sensitive: bool = True
     ) -> collections.Iterator[tuple[str, MessageCommand[typing.Any]]]:
         """Check whether a name matches any of this component's registered message commands.
 
@@ -3483,11 +3465,7 @@ def check_slash_name(self, name: str, /) -> collections.Iterator[BaseSlashComman
         """
 
     @abc.abstractmethod
-    def execute_autocomplete(
-        self,
-        ctx: AutocompleteContext,
-        /,
-    ) -> typing.Optional[_CoroT[None]]:
+    def execute_autocomplete(self, ctx: AutocompleteContext, /) -> typing.Optional[_CoroT[None]]:
         """Execute an autocomplete context.
 
         !!! note
@@ -3512,11 +3490,7 @@ def execute_autocomplete(
 
     @abc.abstractmethod
     async def execute_menu(
-        self,
-        ctx: MenuContext,
-        /,
-        *,
-        hooks: typing.Optional[collections.MutableSet[MenuHooks]] = None,
+        self, ctx: MenuContext, /, *, hooks: typing.Optional[collections.MutableSet[MenuHooks]] = None
     ) -> typing.Optional[_CoroT[None]]:
         """Execute a menu context.
 
@@ -3548,11 +3522,7 @@ async def execute_menu(
 
     @abc.abstractmethod
     async def execute_slash(
-        self,
-        ctx: SlashContext,
-        /,
-        *,
-        hooks: typing.Optional[collections.MutableSet[SlashHooks]] = None,
+        self, ctx: SlashContext, /, *, hooks: typing.Optional[collections.MutableSet[SlashHooks]] = None
     ) -> typing.Optional[_CoroT[None]]:
         """Execute a slash context.
 
@@ -4393,39 +4363,27 @@ def iter_commands(self) -> collections.Iterator[ExecutableCommand[Context]]:
     @typing.overload
     @abc.abstractmethod
     def iter_menu_commands(
-        self,
-        *,
-        global_only: bool = False,
-        type: typing.Literal[hikari.CommandType.MESSAGE],  # noqa: A002
+        self, *, global_only: bool = False, type: typing.Literal[hikari.CommandType.MESSAGE]  # noqa: A002
     ) -> collections.Iterator[MenuCommand[typing.Any, typing.Literal[hikari.CommandType.MESSAGE]]]:
         ...
 
     @typing.overload
     @abc.abstractmethod
     def iter_menu_commands(
-        self,
-        *,
-        global_only: bool = False,
-        type: typing.Literal[hikari.CommandType.USER],  # noqa: A002
+        self, *, global_only: bool = False, type: typing.Literal[hikari.CommandType.USER]  # noqa: A002
     ) -> collections.Iterator[MenuCommand[typing.Any, typing.Literal[hikari.CommandType.USER]]]:
         ...
 
     @typing.overload
     @abc.abstractmethod
     def iter_menu_commands(
-        self,
-        *,
-        global_only: bool = False,
-        type: typing.Optional[hikari.CommandType] = None,  # noqa: A002
+        self, *, global_only: bool = False, type: typing.Optional[hikari.CommandType] = None  # noqa: A002
     ) -> collections.Iterator[MenuCommand[typing.Any, typing.Any]]:
         ...
 
     @abc.abstractmethod
     def iter_menu_commands(
-        self,
-        *,
-        global_only: bool = False,
-        type: typing.Optional[hikari.CommandType] = None,  # noqa: A002
+        self, *, global_only: bool = False, type: typing.Optional[hikari.CommandType] = None  # noqa: A002
     ) -> collections.Iterator[MenuCommand[typing.Any, typing.Any]]:
         """Iterator over the menu commands registered to this client.
 
@@ -4469,11 +4427,7 @@ def iter_slash_commands(self, *, global_only: bool = False) -> collections.Itera
 
     @abc.abstractmethod
     def check_message_name(
-        self,
-        name: str,
-        /,
-        *,
-        case_sensitive: bool = True,
+        self, name: str, /, *, case_sensitive: bool = True
     ) -> collections.Iterator[tuple[str, MessageCommand[typing.Any]]]:
         """Check whether a message command name is present in the current client.
 
@@ -4514,11 +4468,7 @@ def check_slash_name(self, name: str, /) -> collections.Iterator[BaseSlashComman
 
     @abc.abstractmethod
     def load_directory(
-        self,
-        directory: typing.Union[str, pathlib.Path],
-        /,
-        *,
-        namespace: typing.Optional[str] = None,
+        self, directory: typing.Union[str, pathlib.Path], /, *, namespace: typing.Optional[str] = None
     ) -> Self:
         """Load entities into this client from the modules in a directory.
 

diff --git a/tanjun/annotations.py b/tanjun/annotations.py
@@ -1020,12 +1020,7 @@ class TheseChannels(_ConfigIdentifier, metaclass=_TheseChannelsMeta):
 
     __slots__ = ("_channel_types",)
 
-    def __init__(
-        self,
-        channel_type: _ChannelTypeIsh,
-        /,
-        *other_types: _ChannelTypeIsh,
-    ) -> None:
+    def __init__(self, channel_type: _ChannelTypeIsh, /, *other_types: _ChannelTypeIsh) -> None:
         """Create a channel argument restraint.
 
         Parameters
@@ -1046,7 +1041,7 @@ def set_config(self, config: _ArgConfig, /) -> None:
         config.channel_types = self._channel_types
 
 
-def _ensure_value(name: str, type_: type[_T], value: typing.Optional[typing.Any]) -> typing.Optional[_T]:
+def _ensure_value(name: str, type_: type[_T], value: typing.Optional[typing.Any], /) -> typing.Optional[_T]:
     if value is None or isinstance(value, type_):
         return value
 
@@ -1235,8 +1230,7 @@ def to_slash_option(self, command: slash.SlashCommand[typing.Any], /) -> None:
             self.SLASH_OPTION_ADDER[option_type](self, command, self.description)
 
     SLASH_OPTION_ADDER: dict[
-        typing.Any,
-        collections.Callable[[Self, slash.SlashCommand[typing.Any], str], slash.SlashCommand[typing.Any]],
+        typing.Any, collections.Callable[[Self, slash.SlashCommand[typing.Any], str], slash.SlashCommand[typing.Any]]
     ] = {
         hikari.Attachment: lambda self, c, d: c.add_attachment_option(
             self.slash_name, d, default=self._slash_default(), key=self.parameter.name
@@ -1295,7 +1289,7 @@ def to_slash_option(self, command: slash.SlashCommand[typing.Any], /) -> None:
     SLASH_OPTION_ADDER[hikari.InteractionMember] = SLASH_OPTION_ADDER[hikari.Member]
 
 
-def _snoop_annotation_args(type_: typing.Any) -> collections.Iterator[typing.Any]:
+def _snoop_annotation_args(type_: typing.Any, /) -> collections.Iterator[typing.Any]:
     origin = typing.get_origin(type_)
     if origin is typing.Annotated:
         args = typing.get_args(type_)