Advanced Usecases
=================

There are a few deep areas of argus-cli that allows for extra extensibility
such as adding an extra package with commands.

In this section we'll take a look at advanced usecases like this.


Registering packages as argus-cli modules
-----------------------------------------

By using `setuptools entrypoints <https://setuptools.readthedocs.io/en/
latest/setuptools.html#dynamic-discovery-of-services-and-plugins>`_, extra
packages can be installed to extend the toolbelt with all commands from an
external package.

At startup, the program will look for the entrypoint :code:`argus_cli.plugins`.
This entrypoint can either be set up in :code:`setup.py`, if you're using
setuptools, or :code:`pyproject.toml` if you're using poetry.

Setup with Poetry
^^^^^^^^^^^^^^^^^

In poetry, the `plugins section <https://python-poetry.org/docs/pyproject/#plugins>`
is where all entrypoints live. For your module to automatically attach to
argus-cli, add the following to your config:

.. code-block:: toml

    [tool.poetry.plugins."argus_cli.plugins"]
    module_identifier = "module_name"

The identifier can have an arbitrary name, as long as it does not conflict with
any other packages. It's recommended to just give it the same name as your package.

So if you have a module called :code:`funky_commands`, the config would look
like this:

.. code-block:: toml

    [tool.poetry.plugins."argus_cli.plugins"]
    funky_commands = "funky_commands"


Setup with setuptools
^^^^^^^^^^^^^^^^^^^^^

With setuptools, you can either add the config to :code:`setup.py` or
:code:`setup.ini`. Both use the same argument; `entrypoints <https://
setuptools.readthedocs.io/en/latest/
setuptools.html#dynamic-discovery-of-services-and-plugins>`_.

.. code-block:: ini

    [options.entry_points]
    argus_cli.plugins = module_identifier = module_name

The identifier can have an arbitrary name, as long as it does not conflict with
any other packages. It's recommended to just give it the same name as your package.

If you have a module called :code:`funky_commands`, the config would look
like this:

.. code-block:: ini

    [options.entry_points]
    argus_cli.plugins = funky_commands = funky_commands

If you rather want to specify the entrypoint in :code:`setup.py`, then the
setup looks like this:

.. code-block:: python

    setup(
        # [...] Your other setup parameters
        entry_points={
            "argus_cli.plugins": "funky_commands = funky_commands"
        }
    )