From aae8df822e85fd83abf1821d7c69c2df21563e1d Mon Sep 17 00:00:00 2001 From: hypergonial Date: Fri, 24 May 2024 11:19:34 +0200 Subject: [PATCH] Improve docstring formatting --- arc/abc/client.py | 30 ++++++++++++++--------------- arc/abc/concurrency_limiting.py | 2 +- arc/abc/error_handler.py | 2 +- arc/abc/hookable.py | 4 ++-- arc/abc/option.py | 2 +- arc/abc/plugin.py | 6 +++--- arc/client.py | 4 ++-- arc/command/message.py | 2 +- arc/command/option/attachment.py | 3 --- arc/command/option/bool.py | 3 --- arc/command/option/channel.py | 3 --- arc/command/option/custom/color.py | 3 --- arc/command/option/custom/member.py | 3 --- arc/command/option/float.py | 3 --- arc/command/option/int.py | 3 --- arc/command/option/mentionable.py | 3 --- arc/command/option/role.py | 3 --- arc/command/option/str.py | 3 --- arc/command/option/user.py | 3 --- arc/command/slash.py | 4 ++-- arc/command/user.py | 2 +- arc/context/base.py | 2 +- arc/extension.py | 4 ++-- arc/plugin.py | 4 ++-- arc/utils/concurrency_limiter.py | 12 ++++++------ arc/utils/hooks/basic.py | 10 +++++----- arc/utils/hooks/limiters.py | 12 ++++++------ arc/utils/loops.py | 10 +++++----- 28 files changed, 56 insertions(+), 89 deletions(-) diff --git a/arc/abc/client.py b/arc/abc/client.py index 1041014..271f70c 100644 --- a/arc/abc/client.py +++ b/arc/abc/client.py @@ -483,7 +483,7 @@ def walk_commands( # noqa: C901 CommandT[te.Self] The next command that matches the given criteria. - Examples + Example -------- ```py for cmd in plugin.walk_commands(hikari.CommandType.SLASH): @@ -561,7 +561,7 @@ def include( RuntimeError If the command is already added to a plugin. - Examples + Example -------- ```py @client.include # Add the command to the client. @@ -637,7 +637,7 @@ def include_slash_group( !!! note Parameters left as `hikari.UNDEFINED` will be inherited from the parent client. - Examples + Example -------- ```py group = client.include_slash_group("Group", "A group of commands.") @@ -891,7 +891,7 @@ def set_error_handler( te.Self The client for chaining calls. - Examples + Example -------- ```py @client.set_error_handler @@ -942,7 +942,7 @@ def add_startup_hook( te.Self The client for chaining calls. - Examples + Example -------- ```py @client.add_startup_hook @@ -989,7 +989,7 @@ def add_shutdown_hook( te.Self The client for chaining calls. - Examples + Example -------- ```py @client.add_shutdown_hook @@ -1040,7 +1040,7 @@ def set_startup_hook( te.Self The client for chaining calls. - Examples + Example -------- ```py @client.set_startup_hook @@ -1092,7 +1092,7 @@ def set_shutdown_hook( te.Self The client for chaining calls. - Examples + Example -------- ```py @client.set_shutdown_hook @@ -1140,7 +1140,7 @@ def set_command_locale_provider( te.Self The client for chaining calls. - Examples + Example -------- ```py @client.set_command_locale_provider @@ -1187,7 +1187,7 @@ def set_option_locale_provider( te.Self The client for chaining calls. - Examples + Example -------- ```py @client.set_option_locale_provider @@ -1229,7 +1229,7 @@ def set_custom_locale_provider( provider : CustomLocaleRequestT The custom locale provider to set. - Examples + Example -------- ```py @client.set_custom_locale_provider @@ -1272,7 +1272,7 @@ def load_extension(self, path: str) -> te.Self: ValueError If the module does not have a loader. - Examples + Example -------- ```py client = arc.GatewayClient(...) @@ -1337,7 +1337,7 @@ def load_extensions_from(self, dir_path: str | pathlib.Path, recursive: bool = F ExtensionLoadError If a module does not have a loader defined. - Examples + Example -------- ```py client = arc.GatewayClient(...) @@ -1438,7 +1438,7 @@ def set_type_dependency(self, type_: type[T], instance: T) -> te.Self: te.Self The client for chaining calls. - Examples + Example -------- ```py class MyDependency: @@ -1513,7 +1513,7 @@ def inject_dependencies( Command callbacks are automatically injected with dependencies, thus this decorator is not needed for them. - Examples + Example -------- ```py class MyDependency: diff --git a/arc/abc/concurrency_limiting.py b/arc/abc/concurrency_limiting.py index 39f4d14..abcb03e 100644 --- a/arc/abc/concurrency_limiting.py +++ b/arc/abc/concurrency_limiting.py @@ -86,7 +86,7 @@ def with_concurrency_limit( t.Callable[[HasConcurrencyLimiterT], HasConcurrencyLimiterT] The object with the concurrency limiter set. - Examples + Example -------- ```py @client.include diff --git a/arc/abc/error_handler.py b/arc/abc/error_handler.py index d243e88..c7f7655 100644 --- a/arc/abc/error_handler.py +++ b/arc/abc/error_handler.py @@ -39,7 +39,7 @@ def set_error_handler( This function will be called when an exception is raised during the invocation of a command. - Examples + Example -------- ```py @client.include diff --git a/arc/abc/hookable.py b/arc/abc/hookable.py index 568f419..64c0c33 100644 --- a/arc/abc/hookable.py +++ b/arc/abc/hookable.py @@ -97,7 +97,7 @@ def with_hook(hook: HookT[ClientT]) -> t.Callable[[HookableT], HookableT]: and returns either a [`HookResult`][arc.abc.hookable.HookResult] or `None` can be used as a hook. - Examples + Example -------- ```py @client.include @@ -127,7 +127,7 @@ def with_post_hook(hook: PostHookT[ClientT]) -> t.Callable[[HookableT], Hookable Post-execution hooks **are** called even if the command callback raises an exception. You can see if the command callback failed by checking [`Context.has_command_failed`][arc.context.base.Context.has_command_failed]. - Examples + Example -------- ```py @client.include diff --git a/arc/abc/option.py b/arc/abc/option.py index d25ac1e..09689b5 100644 --- a/arc/abc/option.py +++ b/arc/abc/option.py @@ -33,7 +33,7 @@ Option = t.Annotated """Alias for typing.Annotated. -Examples +Example -------- ```py arc.Option[type, arc.TypeParams(...)] diff --git a/arc/abc/plugin.py b/arc/abc/plugin.py index 3c16bc0..1ee54da 100644 --- a/arc/abc/plugin.py +++ b/arc/abc/plugin.py @@ -295,7 +295,7 @@ def include_slash_group( !!! note Parameters left as `hikari.UNDEFINED` will be inherited from the parent plugin or client. - Examples + Example -------- ```py group = client.include_slash_group("Group", "A group of commands.") @@ -340,7 +340,7 @@ def inject_dependencies( Command callbacks are automatically injected with dependencies, thus this decorator is not needed for them. - Examples + Example -------- ```py class MyDependency: @@ -439,7 +439,7 @@ def walk_commands( # noqa: C901 CommandT[ClientT] The next command that matches the given criteria. - Examples + Example -------- ```py for cmd in plugin.walk_commands(hikari.CommandType.SLASH): diff --git a/arc/client.py b/arc/client.py index cd6736e..54e24dc 100644 --- a/arc/client.py +++ b/arc/client.py @@ -344,7 +344,7 @@ class GatewayClient(GatewayClientBase[hikari.GatewayBotAware]): If you already have an injector instance, you may pass it here. Otherwise, a new one will be created by default. - Examples + Example -------- ```py import hikari @@ -390,7 +390,7 @@ class RESTClient(RESTClientBase[hikari.RESTBotAware]): Otherwise, a new one will be created by default. - Examples + Example -------- ```py import hikari diff --git a/arc/command/message.py b/arc/command/message.py index 2b7d586..9383318 100644 --- a/arc/command/message.py +++ b/arc/command/message.py @@ -96,7 +96,7 @@ def message_command( name_localizations : t.Mapping[hikari.Locale, str] | None The localizations for this command's name. - Examples + Example -------- ```py @client.include diff --git a/arc/command/option/attachment.py b/arc/command/option/attachment.py index f5c7366..69e1713 100644 --- a/arc/command/option/attachment.py +++ b/arc/command/option/attachment.py @@ -22,9 +22,6 @@ class AttachmentParams(OptionParams[hikari.Attachment]): ---------- description : str The description of the option - - Other Parameters - ---------------- name : str The name of the option. If not provided, the name of the parameter will be used. name_localizations : Mapping[hikari.Locale, str] | None diff --git a/arc/command/option/bool.py b/arc/command/option/bool.py index c97ad7d..4382117 100644 --- a/arc/command/option/bool.py +++ b/arc/command/option/bool.py @@ -21,9 +21,6 @@ class BoolParams(OptionParams[bool]): ---------- description : str The description of the option - - Other Parameters - ---------------- name : str The name of the option. If not provided, the name of the parameter will be used. name_localizations : t.Optional[t.Mapping[str, str]] diff --git a/arc/command/option/channel.py b/arc/command/option/channel.py index ff18a70..c18c86b 100644 --- a/arc/command/option/channel.py +++ b/arc/command/option/channel.py @@ -28,9 +28,6 @@ class ChannelParams(OptionParams[hikari.PartialChannel]): ---------- description : str The description of the option - - Other Parameters - ---------------- name : str The name of the option. If not provided, the name of the parameter will be used. name_localizations : Mapping[hikari.Locale, str] diff --git a/arc/command/option/custom/color.py b/arc/command/option/custom/color.py index 48c942f..19fdac8 100644 --- a/arc/command/option/custom/color.py +++ b/arc/command/option/custom/color.py @@ -24,9 +24,6 @@ class ColorParams(OptionParams[hikari.Color]): ---------- description : str The description of the option - - Other Parameters - ---------------- name : str The name of the option. If not provided, the name of the parameter will be used. name_localizations : Mapping[hikari.Locale, str] | None diff --git a/arc/command/option/custom/member.py b/arc/command/option/custom/member.py index 2df6438..b945b7b 100644 --- a/arc/command/option/custom/member.py +++ b/arc/command/option/custom/member.py @@ -24,9 +24,6 @@ class MemberParams(OptionParams[hikari.InteractionMember]): ---------- description : str The description of the option - - Other Parameters - ---------------- name : str The name of the option. If not provided, the name of the parameter will be used. name_localizations : Mapping[hikari.Locale, str] | None diff --git a/arc/command/option/float.py b/arc/command/option/float.py index 96fa932..bc4ea9c 100644 --- a/arc/command/option/float.py +++ b/arc/command/option/float.py @@ -27,9 +27,6 @@ class FloatParams(OptionWithChoicesParams[float, ClientT]): ---------- description : str The description of the option - - Other Parameters - ---------------- name : str The name of the option. If not provided, the name of the parameter will be used. name_localizations : Mapping[hikari.Locale, str] | None diff --git a/arc/command/option/int.py b/arc/command/option/int.py index 99db509..009bd2b 100644 --- a/arc/command/option/int.py +++ b/arc/command/option/int.py @@ -27,9 +27,6 @@ class IntParams(OptionWithChoicesParams[int, ClientT]): ---------- description : str The description of the option - - Other Parameters - ---------------- name : str The name of the option. If not provided, the name of the parameter will be used. name_localizations : Mapping[hikari.Locale, str] | None diff --git a/arc/command/option/mentionable.py b/arc/command/option/mentionable.py index 876f3ce..1becc46 100644 --- a/arc/command/option/mentionable.py +++ b/arc/command/option/mentionable.py @@ -23,9 +23,6 @@ class MentionableParams(OptionParams[hikari.Role | hikari.User]): ---------- description : str The description of the option - - Other Parameters - ---------------- name : str The name of the option. If not provided, the name of the parameter will be used. name_localizations : Mapping[hikari.Locale, str] | None diff --git a/arc/command/option/role.py b/arc/command/option/role.py index cfb4953..80d11fd 100644 --- a/arc/command/option/role.py +++ b/arc/command/option/role.py @@ -22,9 +22,6 @@ class RoleParams(OptionParams[hikari.Role]): ---------- description : str The description of the option - - Other Parameters - ---------------- name : str The name of the option. If not provided, the name of the parameter will be used. name_localizations : t.Optional[t.Mapping[str, str]] diff --git a/arc/command/option/str.py b/arc/command/option/str.py index 588c7e6..c6df769 100644 --- a/arc/command/option/str.py +++ b/arc/command/option/str.py @@ -28,9 +28,6 @@ class StrParams(OptionWithChoicesParams[str, ClientT]): ---------- description : str The description of the option - - Other Parameters - ---------------- name : str The name of the option. If not provided, the name of the parameter will be used. name_localizations : Mapping[hikari.Locale, str] diff --git a/arc/command/option/user.py b/arc/command/option/user.py index 243d4c3..53a17b2 100644 --- a/arc/command/option/user.py +++ b/arc/command/option/user.py @@ -23,9 +23,6 @@ class UserParams(OptionParams[hikari.User]): ---------- description : str The description of the option - - Other Parameters - ---------------- name : str The name of the option. If not provided, the name of the parameter will be used. name_localizations : Mapping[hikari.Locale, str] | None diff --git a/arc/command/slash.py b/arc/command/slash.py index c0a4147..d85888a 100644 --- a/arc/command/slash.py +++ b/arc/command/slash.py @@ -777,7 +777,7 @@ def slash_command( !!! note Parameters left as `hikari.UNDEFINED` will be inherited from the parent plugin or client. - Examples + Example -------- ```py @client.include @@ -843,7 +843,7 @@ def slash_subcommand( !!! note Parameters left as `hikari.UNDEFINED` will be inherited from the parent group, plugin or client. - Examples + Example -------- ```py group = client.include_slash_group("group", "A group of slash commands.") diff --git a/arc/command/user.py b/arc/command/user.py index 267c61c..b2df6c8 100644 --- a/arc/command/user.py +++ b/arc/command/user.py @@ -99,7 +99,7 @@ def user_command( name_localizations : t.Mapping[hikari.Locale, str] | None The localizations for this command's name. - Examples + Example -------- ```py @client.include diff --git a/arc/context/base.py b/arc/context/base.py index d23ae44..55697ee 100644 --- a/arc/context/base.py +++ b/arc/context/base.py @@ -468,7 +468,7 @@ def get_option(self, name: str, opt_type: OptionType) -> t.Any | None: ValueT | None The value of the option, or None if it does not exist, or is not of the correct type. - Examples + Example -------- ```py value = ctx.get_option("name", arc.OptionType.STRING) diff --git a/arc/extension.py b/arc/extension.py index c3d9b74..a5fc361 100644 --- a/arc/extension.py +++ b/arc/extension.py @@ -20,7 +20,7 @@ def loader( ) -> t.Callable[[ClientT], None] | t.Callable[[t.Callable[[ClientT], None]], t.Callable[[ClientT], None]]: """Decorator to set the load callback for this module. - Examples + Example -------- ```py client.load_extension("my_extension") @@ -61,7 +61,7 @@ def unloader( ) -> t.Callable[[ClientT], None] | t.Callable[[t.Callable[[ClientT], None]], t.Callable[[ClientT], None]]: """Decorator to set the unload callback for this module. - Examples + Example -------- ```py client.unload_extension("my_extension") diff --git a/arc/plugin.py b/arc/plugin.py index 2c6b14e..5329ad2 100644 --- a/arc/plugin.py +++ b/arc/plugin.py @@ -42,7 +42,7 @@ class RESTPluginBase(PluginBase[RESTClientT]): is_nsfw : bool | hikari.UndefinedType Whether this plugin is only usable in NSFW channels - Examples + Example -------- ```py plugin = arc.RESTPlugin("MyPlugin") @@ -90,7 +90,7 @@ class GatewayPluginBase(PluginBase[GatewayClientT]): is_nsfw : bool | hikari.UndefinedType Whether this plugin is only usable in NSFW channels - Examples + Example -------- ```py plugin = arc.GatewayPlugin("MyPlugin") diff --git a/arc/utils/concurrency_limiter.py b/arc/utils/concurrency_limiter.py index 0b18161..62793fe 100644 --- a/arc/utils/concurrency_limiter.py +++ b/arc/utils/concurrency_limiter.py @@ -256,7 +256,7 @@ def global_concurrency(limit: int) -> CommandConcurrencyLimiter[t.Any]: CommandConcurrencyLimiter[t.Any] A concurrency limiter for use with a command. - Examples + Example -------- ```py @arc.with_concurrency_limit(arc.global_concurrency(1)) @@ -278,7 +278,7 @@ def guild_concurrency(limit: int) -> CommandConcurrencyLimiter[t.Any]: CommandConcurrencyLimiter[t.Any] A concurrency limiter for use with a command. - Examples + Example -------- ```py @arc.with_concurrency_limit(arc.guild_concurrency(1)) @@ -300,7 +300,7 @@ def channel_concurrency(limit: int) -> CommandConcurrencyLimiter[t.Any]: CommandConcurrencyLimiter[t.Any] A concurrency limiter for use with a command. - Examples + Example -------- ```py @arc.with_concurrency_limit(arc.channel_concurrency(1)) @@ -322,7 +322,7 @@ def user_concurrency(limit: int) -> CommandConcurrencyLimiter[t.Any]: CommandConcurrencyLimiter[t.Any] A concurrency limiter for use with a command. - Examples + Example -------- ```py @arc.with_concurrency_limit(arc.user_concurrency(1)) @@ -344,7 +344,7 @@ def member_concurrency(limit: int) -> CommandConcurrencyLimiter[t.Any]: CommandConcurrencyLimiter[t.Any] A concurrency limiter for use with a command. - Examples + Example -------- ```py @arc.with_concurrency_limit(arc.member_concurrency(1)) @@ -370,7 +370,7 @@ def custom_concurrency( CommandConcurrencyLimiter[t.Any] A concurrency limiter for use with a command. - Examples + Example -------- ```py # This is identical to 'arc.guild_concurrency(1)' diff --git a/arc/utils/hooks/basic.py b/arc/utils/hooks/basic.py index 1f1d33e..5651a83 100644 --- a/arc/utils/hooks/basic.py +++ b/arc/utils/hooks/basic.py @@ -20,7 +20,7 @@ def guild_only(ctx: Context[t.Any]) -> HookResult: """A pre-execution hook that aborts the execution of a command if it is invoked outside of a guild. - Examples + Example -------- ```py @arc.with_hook(arc.guild_only) @@ -39,7 +39,7 @@ def guild_only(ctx: Context[t.Any]) -> HookResult: def dm_only(ctx: Context[t.Any]) -> HookResult: """A pre-execution hook that aborts the execution of a command if it is invoked outside of a DM. - Examples + Example -------- ```py @arc.with_hook(arc.dm_only) @@ -58,7 +58,7 @@ def dm_only(ctx: Context[t.Any]) -> HookResult: def owner_only(ctx: Context[t.Any]) -> HookResult: """A pre-execution hook that aborts the execution of a command if it is invoked by a non-owner. - Examples + Example -------- ```py @arc.with_hook(arc.owner_only) @@ -105,7 +105,7 @@ def has_permissions(perms: hikari.Permissions) -> t.Callable[[Context[t.Any]], H InvokerMissingPermissionsError If the invoker is missing some of the specified permissions. - Examples + Example -------- ```py @arc.with_hook(arc.has_permissions(hikari.Permissions.MANAGE_CHANNELS | hikari.Permissions.MANAGE_GUILD)) @@ -149,7 +149,7 @@ def bot_has_permissions(perms: hikari.Permissions) -> t.Callable[[Context[t.Any] BotMissingPermissionsError If the bot is missing some of the specified permissions. - Examples + Example -------- ```py @arc.with_hook(arc.bot_has_permissions(hikari.Permissions.MANAGE_CHANNELS | hikari.Permissions.MANAGE_GUILD)) diff --git a/arc/utils/hooks/limiters.py b/arc/utils/hooks/limiters.py index 1a9d5d7..45db40b 100644 --- a/arc/utils/hooks/limiters.py +++ b/arc/utils/hooks/limiters.py @@ -82,7 +82,7 @@ def global_limiter(period: float, limit: int) -> LimiterHook[t.Any]: RateLimiterExhaustedError If the limiter is exhausted. - Examples + Example -------- ```py @arc.with_hook(arc.global_limiter(5.0, 1)) @@ -108,7 +108,7 @@ def guild_limiter(period: float, limit: int) -> LimiterHook[t.Any]: RateLimiterExhaustedError If the limiter is exhausted. - Examples + Example -------- ```py @arc.with_hook(arc.guild_limiter(5.0, 1)) @@ -134,7 +134,7 @@ def channel_limiter(period: float, limit: int) -> LimiterHook[t.Any]: RateLimiterExhaustedError If the limiter is exhausted. - Examples + Example -------- ```py @arc.with_hook(arc.channel_limiter(5.0, 1)) @@ -160,7 +160,7 @@ def user_limiter(period: float, limit: int) -> LimiterHook[t.Any]: RateLimiterExhaustedError If the limiter is exhausted. - Examples + Example -------- ```py @arc.with_hook(arc.user_limiter(5.0, 1)) @@ -187,7 +187,7 @@ def member_limiter(period: float, limit: int) -> LimiterHook[t.Any]: RateLimiterExhaustedError If the limiter is exhausted. - Examples + Example -------- ```py @arc.with_hook(arc.member_limiter(5.0, 1)) @@ -215,7 +215,7 @@ def custom_limiter(period: float, limit: int, get_key_with: t.Callable[[Context[ RateLimiterExhaustedError If the limiter is exhausted. - Examples + Example -------- ```py # This is identical to 'arc.guild_limiter(5.0, 1)' diff --git a/arc/utils/loops.py b/arc/utils/loops.py index 72792b4..858a980 100644 --- a/arc/utils/loops.py +++ b/arc/utils/loops.py @@ -152,7 +152,7 @@ class IntervalLoop(_LoopBase[P]): TypeError If the passed function is not a coroutine function. - Examples + Example -------- ```py loop = IntervalLoop(my_coro, seconds=5) @@ -213,7 +213,7 @@ def set_interval( days : float | None, optional The number of days to wait before running the coroutine again. - Examples + Example -------- ```py loop = IntervalLoop(my_coro, seconds=5) @@ -262,7 +262,7 @@ class CronLoop(_LoopBase[P]): TypeError If the passed function is not a coroutine function. - Examples + Example -------- ```py loop = CronLoop(my_coro, "*/5 * * * *") @@ -335,7 +335,7 @@ def interval_loop( TypeError If the decorated function is not a coroutine function. - Examples + Example -------- ```py import arc @@ -390,7 +390,7 @@ def cron_loop( TypeError If the decorated function is not a coroutine function. - Examples + Example -------- ```py import arc