hikari-arc 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

arc/__init__.py

@@ -11,9 +11,9 @@ https://arc.hypergonial.com
 from alluka import Client as Injector
 from alluka import inject
 
-from arc import abc, command
+from arc import abc, command, utils
 
-from .abc import HookResult, Option, with_hook, with_post_hook
+from .abc import HookResult, Option, OptionType, with_hook, with_post_hook
 from .client import (
     Client,
     GatewayClient,
@@ -51,7 +51,9 @@ from .errors import (
     ArcError,
     AutocompleteError,
     CommandInvokeError,
+    CommandPublishFailedError,
     DMOnlyError,
+    GuildCommandPublishFailedError,
     GuildOnlyError,
     InvokerMissingPermissionsError,
     NotOwnerError,
@@ -121,6 +123,7 @@ __all__ = (
     "RESTClientBase",
     "GatewayClient",
     "RESTClient",
+    "OptionType",
     "ArcError",
     "AutocompleteError",
     "UnderCooldownError",
@@ -129,6 +132,8 @@ __all__ = (
     "NotOwnerError",
     "DMOnlyError",
     "CommandInvokeError",
+    "GuildCommandPublishFailedError",
+    "CommandPublishFailedError",
     "PluginBase",
     "RESTPluginBase",
     "GatewayPluginBase",
@@ -149,6 +154,7 @@ __all__ = (
     "CommandLocaleRequest",
     "OptionLocaleRequest",
     "abc",
+    "utils",
     "command",
     "with_hook",
     "with_post_hook",

arc/abc/__init__.py

@@ -2,7 +2,15 @@ from .client import Client
 from .command import CallableCommandBase, CallableCommandProto, CommandBase, CommandProto
 from .error_handler import HasErrorHandler
 from .hookable import Hookable, HookResult, with_hook, with_post_hook
-from .option import CommandOptionBase, Option, OptionBase, OptionParams, OptionWithChoices, OptionWithChoicesParams
+from .option import (
+    CommandOptionBase,
+    Option,
+    OptionBase,
+    OptionParams,
+    OptionType,
+    OptionWithChoices,
+    OptionWithChoicesParams,
+)
 from .plugin import PluginBase
 
 __all__ = (
@@ -13,6 +21,7 @@ __all__ = (
     "CallableCommandBase",
     "Option",
     "OptionBase",
+    "OptionType",
     "CommandOptionBase",
     "OptionParams",
     "OptionWithChoices",

arc/abc/client.py

@@ -18,7 +18,7 @@ import hikari
 from arc.abc.command import _CommandSettings
 from arc.abc.plugin import PluginBase
 from arc.command.message import MessageCommand
-from arc.command.slash import SlashCommand, SlashGroup
+from arc.command.slash import SlashCommand, SlashGroup, SlashSubCommand, SlashSubGroup
 from arc.command.user import UserCommand
 from arc.context import AutodeferMode, Context
 from arc.errors import ExtensionLoadError, ExtensionUnloadError
@@ -156,6 +156,20 @@ class Client(t.Generic[AppT], abc.ABC):
         will return interaction response builders to be sent back to Discord, otherwise they will return None.
         """
 
+    @property
+    def _commands(self) -> t.Mapping[hikari.CommandType, t.Mapping[str, CommandBase[te.Self, t.Any]]]:
+        """All top-level commands added to this client, categorized by command type.
+
+        !!! note
+            This does not include subcommands & subgroups due to implementation details, therefore
+            you should use [`Client.walk_commands()`][arc.abc.client.Client.walk_commands] instead.
+        """
+        return {
+            hikari.CommandType.SLASH: self._slash_commands,
+            hikari.CommandType.MESSAGE: self._message_commands,
+            hikari.CommandType.USER: self._user_commands,
+        }
+
     @property
     def app(self) -> AppT:
         """The application this client is for."""
@@ -181,30 +195,6 @@ class Client(t.Generic[AppT], abc.ABC):
         """The guilds that slash commands will be registered in by default."""
         return self._default_enabled_guilds
 
-    @property
-    def commands(self) -> t.Mapping[hikari.CommandType, t.Mapping[str, CommandBase[te.Self, t.Any]]]:
-        """All commands added to this client, categorized by command type."""
-        return {
-            hikari.CommandType.SLASH: self.slash_commands,
-            hikari.CommandType.MESSAGE: self._message_commands,
-            hikari.CommandType.USER: self._user_commands,
-        }
-
-    @property
-    def slash_commands(self) -> t.Mapping[str, SlashCommandLike[te.Self]]:
-        """The slash commands added to this client. This only includes top-level commands and groups."""
-        return self._slash_commands
-
-    @property
-    def message_commands(self) -> t.Mapping[str, MessageCommand[te.Self]]:
-        """The message commands added to this client."""
-        return self._message_commands
-
-    @property
-    def user_commands(self) -> t.Mapping[str, UserCommand[te.Self]]:
-        """The user commands added to this client."""
-        return self._user_commands
-
     @property
     def plugins(self) -> t.Mapping[str, PluginBase[te.Self]]:
         """The plugins added to this client."""
@@ -318,11 +308,11 @@ class Client(t.Generic[AppT], abc.ABC):
 
         match interaction.command_type:
             case hikari.CommandType.SLASH:
-                command = self.slash_commands.get(interaction.command_name)
+                command = self._slash_commands.get(interaction.command_name)
             case hikari.CommandType.MESSAGE:
-                command = self.message_commands.get(interaction.command_name)
+                command = self._message_commands.get(interaction.command_name)
             case hikari.CommandType.USER:
-                command = self.user_commands.get(interaction.command_name)
+                command = self._user_commands.get(interaction.command_name)
             case _:
                 pass
 
@@ -372,7 +362,7 @@ class Client(t.Generic[AppT], abc.ABC):
         hikari.api.InteractionAutocompleteBuilder | None
             The autocomplete builder to send back to Discord, if using a REST client.
         """
-        command = self.slash_commands.get(interaction.command_name)
+        command = self._slash_commands.get(interaction.command_name)
 
         if command is None:
             logger.warning(f"Received autocomplete interaction for unknown command '{interaction.command_name}'.")
@@ -380,6 +370,98 @@ class Client(t.Generic[AppT], abc.ABC):
 
         return await command._on_autocomplete(interaction)
 
+    @t.overload
+    def walk_commands(
+        self, command_type: t.Literal[hikari.CommandType.USER], *, callable_only: bool = False
+    ) -> t.Iterator[UserCommand[te.Self]]:
+        ...
+
+    @t.overload
+    def walk_commands(
+        self, command_type: t.Literal[hikari.CommandType.MESSAGE], *, callable_only: bool = False
+    ) -> t.Iterator[MessageCommand[te.Self]]:
+        ...
+
+    @t.overload
+    def walk_commands(
+        self, command_type: t.Literal[hikari.CommandType.SLASH], *, callable_only: t.Literal[False] = False
+    ) -> t.Iterator[SlashCommand[te.Self] | SlashSubCommand[te.Self] | SlashGroup[te.Self] | SlashSubGroup[te.Self]]:
+        ...
+
+    @t.overload
+    def walk_commands(
+        self, command_type: t.Literal[hikari.CommandType.SLASH], *, callable_only: t.Literal[True] = True
+    ) -> t.Iterator[SlashCommand[te.Self] | SlashSubCommand[te.Self]]:
+        ...
+
+    def walk_commands(  # noqa: C901
+        self, command_type: hikari.CommandType, *, callable_only: bool = False
+    ) -> t.Iterator[t.Any]:
+        """Iterate over all commands of a certain type added to this plugin.
+
+        Parameters
+        ----------
+        command_type : hikari.CommandType
+            The type of commands to return.
+        callable_only : bool
+            Whether to only return commands that are directly callable.
+            If True, command groups and subgroups will be skipped.
+            This is only applicable to slash commands.
+
+        Yields
+        ------
+        CommandT[te.Self]
+            The next command that matches the given criteria.
+
+        Usage
+        -----
+        ```py
+        for cmd in plugin.walk_commands(hikari.CommandType.SLASH):
+            print(cmd.name)
+        ```
+
+        !!! tip
+            To iterate over all types of commands, you may use [`itertools.chain()`][itertools.chain]:
+
+            ```py
+            import itertools
+
+            for cmd in itertools.chain(
+                plugin.walk_commands(hikari.CommandType.SLASH),
+                plugin.walk_commands(hikari.CommandType.MESSAGE),
+                plugin.walk_commands(hikari.CommandType.USER),
+            ):
+                print(cmd.name)
+            ```
+        """
+        if hikari.CommandType.SLASH is command_type:
+            for command in self._slash_commands.values():
+                if isinstance(command, SlashCommand):
+                    yield command
+                    continue
+
+                if not callable_only:
+                    yield command
+
+                for sub in command.children.values():
+                    if isinstance(sub, SlashSubCommand):
+                        yield sub
+                        continue
+
+                    if not callable_only:
+                        yield sub
+
+                    for subsub in sub.children.values():
+                        yield subsub
+
+        elif hikari.CommandType.MESSAGE is command_type:
+            for command in self._message_commands.values():
+                yield command
+
+        elif hikari.CommandType.USER is command_type:
+            for command in self._user_commands.values():
+                yield command
+
     @t.overload
     def include(self) -> t.Callable[[CommandBase[te.Self, BuilderT]], CommandBase[te.Self, BuilderT]]:
         ...
@@ -423,7 +505,7 @@ class Client(t.Generic[AppT], abc.ABC):
                     f"\nYou should use '{type(self).__name__}.add_plugin()' to add the entire plugin to the client."
                 )
 
-            if existing := self.commands[command.command_type].get(command.name):
+            if existing := self._commands[command.command_type].get(command.name):
                 logger.warning(
                     f"Shadowing already registered command '{command.name}'. Did you define multiple commands with the same name?"
                 )
@@ -663,6 +745,10 @@ class Client(t.Generic[AppT], abc.ABC):
             await ctx.respond(f"❌ Something went wrong: {exception}")
         ```
 
+        !!! warning
+            Errors that cannot be handled by the error handler should be re-raised.
+            Otherwise tracebacks will not be printed to stderr.
+
         Or, as a function:
 
         ```py

arc/abc/command.py

@@ -13,6 +13,7 @@ from arc.abc.hookable import Hookable, HookResult
 from arc.abc.limiter import LimiterProto
 from arc.abc.option import OptionBase
 from arc.context import AutodeferMode
+from arc.errors import CommandPublishFailedError
 from arc.internal.types import (
     BuilderT,
     ClientT,
@@ -49,6 +50,15 @@ class CommandProto(t.Protocol):
     def qualified_name(self) -> t.Sequence[str]:
         """The fully qualified name of this command."""
 
+    @property
+    @abc.abstractmethod
+    def display_name(self) -> str:
+        """The display name of this command. This is what is shown in the Discord client.
+
+        !!! note
+            Slash commands can also be mentioned, see [SlashCommand.make_mention][arc.command.SlashCommand.make_mention].
+        """
+
 
 class CallableCommandProto(CommandProto, t.Protocol[ClientT]):
     """A protocol for any command-like object that can be called directly.
@@ -74,6 +84,15 @@ class CallableCommandProto(CommandProto, t.Protocol[ClientT]):
     def qualified_name(self) -> t.Sequence[str]:
         """The fully qualified name of this command."""
 
+    @property
+    @abc.abstractmethod
+    def display_name(self) -> str:
+        """The display name of this command. This is what is shown in the Discord client.
+
+        !!! note
+            Slash commands can also be mentioned, see [SlashCommand.make_mention][arc.command.SlashCommand.make_mention].
+        """
+
     @property
     @abc.abstractmethod
     def hooks(self) -> t.MutableSequence[HookT[ClientT]]:
@@ -260,7 +279,7 @@ class CommandBase(HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT
         """The client that is handling this command."""
         if self._client is None:
             raise RuntimeError(
-                f"Command '{self.qualified_name}' was not included in a client, '{type(self).__name__}.client' cannot be accessed until it is included in a client."
+                f"Command '{self.display_name}' was not included in a client, '{type(self).__name__}.client' cannot be accessed until it is included in a client."
             )
         return self._client
 
@@ -292,6 +311,20 @@ class CommandBase(HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT
         settings = self._resolve_settings()
         return settings.is_nsfw if settings.is_nsfw is not hikari.UNDEFINED else False
 
+    @property
+    def instances(self) -> t.Mapping[hikari.Snowflake | None, hikari.PartialCommand]:
+        """A mapping of guild IDs to command instances. None corresponds to the global instance, if any."""
+        return self._instances
+
+    @property
+    def display_name(self) -> str:
+        """The display name of this command. This is what is shown in the Discord client.
+
+        !!! note
+            Slash commands can also be mentioned, see [SlashCommand.make_mention][arc.command.SlashCommand.make_mention].
+        """
+        return self.name
+
     def _register_instance(
         self, instance: hikari.PartialCommand, guild: hikari.SnowflakeishOr[hikari.PartialGuild] | None = None
     ) -> None:
@@ -352,13 +385,15 @@ class CommandBase(HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT
             raise RuntimeError("Cannot publish command without a client.")
 
         kwargs = self._to_dict()
-
-        if self.command_type is hikari.CommandType.SLASH:
-            created = await self.client.app.rest.create_slash_command(self.client.application, **kwargs)
-        else:
-            created = await self.client.app.rest.create_context_menu_command(
-                self.client.application, type=self.command_type, **kwargs
-            )
+        try:
+            if self.command_type is hikari.CommandType.SLASH:
+                created = await self.client.app.rest.create_slash_command(self.client.application, **kwargs)
+            else:
+                created = await self.client.app.rest.create_context_menu_command(
+                    self.client.application, type=self.command_type, **kwargs
+                )
+        except Exception as e:
+            raise CommandPublishFailedError(self, f"Failed to publish command '{self.display_name}'") from e
 
         self._instances[hikari.Snowflake(guild) if guild else None] = created
 
@@ -427,8 +462,8 @@ class CommandBase(HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT
 
     def _client_remove_hook(self, client: ClientT) -> None:
         """Called when the client requests the command be removed from it."""
-        self._client = None
         self.client._remove_command(self)
+        self._client = None
 
     def _plugin_include_hook(self, plugin: PluginBase[ClientT]) -> None:
         """Called when the plugin requests the command be added to it."""
@@ -517,7 +552,7 @@ class CallableCommandBase(CommandBase[ClientT, BuilderT], CallableCommandProto[C
     callback: CommandCallbackT[ClientT]
     """The callback to invoke when this command is called."""
 
-    _invoke_task: asyncio.Task[t.Any] | None = attr.field(init=False, default=None)
+    _invoke_task: asyncio.Task[t.Any] | None = attr.field(init=False, default=None, repr=False)
 
     def reset_all_limiters(self, context: Context[ClientT]) -> None:
         """Reset all limiters for this command.
@@ -563,6 +598,15 @@ class SubCommandBase(OptionBase[ClientT], HasErrorHandler[ClientT], Hookable[Cli
     _parent: ParentT | None = attr.field(default=None, init=False, alias="parent")
     """The parent of this subcommand or subgroup."""
 
+    @property
+    @abc.abstractmethod
+    def display_name(self) -> str:
+        """The display name of this command. This is what is shown in the Discord client.
+
+        !!! note
+            Slash commands can also be mentioned, see [SlashCommand.make_mention][arc.command.SlashCommand.make_mention].
+        """
+
     @property
     def error_handler(self) -> ErrorHandlerCallbackT[ClientT] | None:
         """The error handler for this object."""

arc/abc/error_handler.py

@@ -45,12 +45,20 @@ class HasErrorHandler(abc.ABC, t.Generic[ClientT]):
         @client.include
         @arc.slash_command("foo", "Foo command description")
         async def foo(ctx: arc.GatewayContext) -> None:
-            raise Exception("foo")
+            raise RuntimeError("foo")
 
         @foo.set_error_handler
         async def foo_error_handler(ctx: arc.GatewayContext, exc: Exception) -> None:
-            await ctx.respond("foo failed")
+            if isinstance(exc, RuntimeError):
+                await ctx.respond("foo failed")
+                return
+
+            raise exc
         ```
+
+        !!! warning
+            Errors that cannot be handled by the error handler should be re-raised.
+            Otherwise they will not propagate to the next error handler.
         """
 
         def decorator(func: ErrorHandlerCallbackT[ClientT]) -> ErrorHandlerCallbackT[ClientT]:

arc/abc/limiter.py

@@ -12,12 +12,15 @@ if t.TYPE_CHECKING:
 
 @t.runtime_checkable
 class LimiterProto(t.Protocol, t.Generic[ClientT]):
-    """A protocol that all ratelimiters should implement.
+    """A protocol that all limiter hooks should implement.
     A limiter is simply a special type of hook with added methods.
 
     If you're looking to integrate your own ratelimiter implementation,
     you should make sure to implement all methods defined here.
-    An easy (but not necessary) way to do this is to simply inherit from this class.
+
+    !!! tip
+        An easy (but not necessary) way to ensure you've implemented all methods
+        is to inherit from this protocol.
     """
 
     @abc.abstractmethod
@@ -32,20 +35,6 @@ class LimiterProto(t.Protocol, t.Generic[ClientT]):
             The context to evaluate the ratelimit under.
         """
 
-    @abc.abstractmethod
-    async def acquire(self, ctx: Context[ClientT], *, wait: bool = True) -> None:
-        """Acquire the limiter with the given context.
-        Implementations should raise an exception if the limiter is ratelimited
-        and wait is False.
-
-        Parameters
-        ----------
-        ctx : Context
-            The context to evaluate the ratelimit under.
-        wait : bool
-            Whether or not to block until the limiter is available.
-        """
-
     @abc.abstractmethod
     def reset(self, ctx: Context[ClientT]) -> None:
         """Reset the limiter for the given context.

arc/abc/option.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import abc
+import enum
 import typing as t
 from typing import Any
 
@@ -16,7 +17,15 @@ if t.TYPE_CHECKING:
     from arc.abc.client import Client
     from arc.abc.command import CommandProto
 
-__all__ = ("Option", "OptionParams", "OptionWithChoices", "OptionWithChoicesParams", "OptionBase", "CommandOptionBase")
+__all__ = (
+    "Option",
+    "OptionParams",
+    "OptionWithChoices",
+    "OptionWithChoicesParams",
+    "OptionBase",
+    "CommandOptionBase",
+    "OptionType",
+)
 
 T = t.TypeVar("T")
 
@@ -37,6 +46,65 @@ arc.Option[int, arc.IntParams(...)]
 """
 
 
+class OptionType(enum.IntEnum):
+    """The type of a command option.
+
+    This is practically identical to `hikari.OptionType` at the moment.
+    It may however be used in the future to define custom option types.
+    """
+
+    SUB_COMMAND = 1
+    """Denotes a command option where the value will be a sub command."""
+
+    SUB_COMMAND_GROUP = 2
+    """Denotes a command option where the value will be a sub command group."""
+
+    STRING = 3
+    """Denotes a command option where the value will be a string."""
+
+    INTEGER = 4
+    """Denotes a command option where the value will be a int.
+
+    This is range limited between -2^53 and 2^53.
+    """
+
+    BOOLEAN = 5
+    """Denotes a command option where the value will be a bool."""
+
+    USER = 6
+    """Denotes a command option where the value will be resolved to a user."""
+
+    CHANNEL = 7
+    """Denotes a command option where the value will be resolved to a channel."""
+
+    ROLE = 8
+    """Denotes a command option where the value will be resolved to a role."""
+
+    MENTIONABLE = 9
+    """Denotes a command option where the value will be a snowflake ID."""
+
+    FLOAT = 10
+    """Denotes a command option where the value will be a float.
+
+    This is range limited between -2^53 and 2^53.
+    """
+
+    ATTACHMENT = 11
+    """Denotes a command option where the value will be an attachment."""
+
+    @classmethod
+    def from_hikari(cls, option_type: hikari.OptionType) -> OptionType:
+        """Convert a hikari.OptionType to an OptionType."""
+        return cls(option_type.value)
+
+    def to_hikari(self) -> hikari.OptionType:
+        """Convert an OptionType to a hikari.OptionType."""
+        # TODO: Map custom option types to their respective hikari.OptionType
+        return hikari.OptionType(self.value)
+
+    # TODO: When adding custom convertible option types, add them with an offset of 1000 or so
+
+
 class OptionParams(t.Generic[T]):
     """The base class for all option parameters objects.
 
@@ -153,13 +221,13 @@ class OptionBase(abc.ABC, t.Generic[T]):
 
     @property
     @abc.abstractmethod
-    def option_type(self) -> hikari.OptionType:
+    def option_type(self) -> OptionType:
         """The type of the option. Used to register the command."""
 
     def _to_dict(self) -> dict[str, t.Any]:
         """Convert the option to a dictionary of kwargs that can be passed to hikari.CommandOption."""
         return {
-            "type": self.option_type,
+            "type": self.option_type.to_hikari(),
             "name": self.name,
             "description": self.description,
             "autocomplete": False,

arc/abc/plugin.py

@@ -12,6 +12,7 @@ from arc.abc.command import _CommandSettings
 from arc.abc.error_handler import HasErrorHandler
 from arc.abc.hookable import Hookable
 from arc.command import MessageCommand, SlashCommand, SlashGroup, UserCommand
+from arc.command.slash import SlashSubCommand, SlashSubGroup
 from arc.context import AutodeferMode, Context
 from arc.internal.types import BuilderT, ClientT, ErrorHandlerCallbackT, HookT, PostHookT, SlashCommandLike
 
@@ -368,6 +369,97 @@ class PluginBase(HasErrorHandler[ClientT], Hookable[ClientT]):
 
         return decorator
 
+    @t.overload
+    def walk_commands(
+        self, command_type: t.Literal[hikari.CommandType.USER], *, callable_only: bool = False
+    ) -> t.Iterator[UserCommand[ClientT]]:
+        ...
+
+    @t.overload
+    def walk_commands(
+        self, command_type: t.Literal[hikari.CommandType.MESSAGE], *, callable_only: bool = False
+    ) -> t.Iterator[MessageCommand[ClientT]]:
+        ...
+
+    @t.overload
+    def walk_commands(
+        self, command_type: t.Literal[hikari.CommandType.SLASH], *, callable_only: t.Literal[False]
+    ) -> t.Iterator[SlashCommand[ClientT] | SlashSubCommand[ClientT] | SlashGroup[ClientT] | SlashSubGroup[ClientT]]:
+        ...
+
+    @t.overload
+    def walk_commands(
+        self, command_type: t.Literal[hikari.CommandType.SLASH], *, callable_only: t.Literal[True]
+    ) -> t.Iterator[SlashCommand[ClientT] | SlashSubCommand[ClientT]]:
+        ...
+
+    def walk_commands(  # noqa: C901
+        self, command_type: hikari.CommandType, *, callable_only: bool = False
+    ) -> t.Iterator[t.Any]:
+        """Iterate over all commands of a certain type added to this plugin.
+
+        Parameters
+        ----------
+        command_type : hikari.CommandType
+            The type of commands to return.
+        callable_only : bool
+            Whether to only return commands that are directly callable.
+            If True, command groups and subgroups will be skipped.
+
+        Yields
+        ------
+        CommandT[ClientT]
+            The next command that matches the given criteria.
+
+        Usage
+        -----
+        ```py
+        for cmd in plugin.walk_commands(hikari.CommandType.SLASH):
+            print(cmd.name)
+        ```
+
+        !!! tip
+            To iterate over all types of commands, you may use [`itertools.chain()`][itertools.chain]:
+
+            ```py
+            import itertools
+
+            for cmd in itertools.chain(
+                plugin.walk_commands(hikari.CommandType.SLASH),
+                plugin.walk_commands(hikari.CommandType.MESSAGE),
+                plugin.walk_commands(hikari.CommandType.USER),
+            ):
+                print(cmd.name)
+            ```
+        """
+        if hikari.CommandType.SLASH is command_type:
+            for command in self._slash_commands.values():
+                if isinstance(command, SlashCommand):
+                    yield command
+                    continue
+
+                if not callable_only:
+                    yield command
+
+                for sub in command.children.values():
+                    if isinstance(sub, SlashSubCommand):
+                        yield sub
+                        continue
+
+                    if not callable_only:
+                        yield sub
+
+                    for subsub in sub.children.values():
+                        yield subsub
+
+        elif hikari.CommandType.MESSAGE is command_type:
+            for command in self._message_commands.values():
+                yield command
+
+        elif hikari.CommandType.USER is command_type:
+            for command in self._user_commands.values():
+                yield command
+
 
 # MIT License
 #