# Buildsheet autogenerated by ravenadm tool -- Do not edit.

NAMEBASE=		python-click-plugins
VERSION=		1.1.1
KEYWORDS=		python
VARIANTS=		v11 v12
SDESC[v11]=		Registers external CLI commands (3.11)
SDESC[v12]=		Registers external CLI commands (3.12)
HOMEPAGE=		https://github.com/click-contrib/click-plugins
CONTACT=		Python_Automaton[python@ironwolf.systems]

DOWNLOAD_GROUPS=	main
SITES[main]=		PYPIWHL/e9/da/824b92d9942f4e472702488857914bdd50f73021efea15b4cad9aca8ecef
DISTFILE[1]=		click_plugins-1.1.1-py2.py3-none-any.whl:main
DF_INDEX=		1
SPKGS[v11]=		single
SPKGS[v12]=		single

OPTIONS_AVAILABLE=	PY311 PY312
OPTIONS_STANDARD=	none
VOPTS[v11]=		PY311=ON PY312=OFF
VOPTS[v12]=		PY311=OFF PY312=ON

DISTNAME=		click_plugins-1.1.1.dist-info

GENERATED=		yes

[PY311].RUN_DEPENDS_ON=			python-click:single:v11
[PY311].USES_ON=			python:v11,wheel

[PY312].RUN_DEPENDS_ON=			python-click:single:v12
[PY312].USES_ON=			python:v12,wheel

[FILE:2803:descriptions/desc.single]
=============
click-plugins
=============

An extension module for [click] to register
external CLI commands via setuptools entry-points.

Why?
----

Lets say you develop a commandline interface and someone requests a new
feature
that is absolutely related to your project but would have negative
consequences
like additional dependencies, major refactoring, or maybe its just too
domain
specific to be supported directly.  Rather than developing a separate
standalone
utility you could offer up a [setuptools entry point]
that allows others to use your commandline utility as a home for their
related
sub-commands.  You get to choose where these sub-commands or sub-groups CAN
be
registered but the plugin developer gets to choose they ARE registered. 
You
could have all plugins register alongside the core commands, in a special
sub-group, across multiple sub-groups, or some combination.

Enabling Plugins
----------------

For a more detailed example see the [examples] section.

The only requirement is decorating ``click.group() with
click_plugins.with_plugins()``
which handles attaching external commands and groups.  In this case the
core CLI developer
registers CLI plugins from ``core_package.cli_plugins``.

.. code-block:: python

    from pkg_resources import iter_entry_points

    import click
    from click_plugins import with_plugins

    @with_plugins(iter_entry_points('core_package.cli_plugins'))
    @click.group()
    def cli():
        """Commandline interface for yourpackage."""

    @cli.command()
    def subcommand():
        """Subcommand that does something."""

Developing Plugins
------------------

Plugin developers need to register their sub-commands or sub-groups to an
entry-point in their ``setup.py`` that is loaded by the core package.

.. code-block:: python

    from setuptools import setup

    setup(
        name='yourscript',
        version='0.1',
        py_modules=['yourscript'],
        install_requires=[
            'click',
       ],
        entry_points='''
            [core_package.cli_plugins]
            cool_subcommand=yourscript.cli:cool_subcommand
            another_subcommand=yourscript.cli:another_subcommand
        ''',
    )

Broken and Incompatible Plugins
-------------------------------

Any sub-command or sub-group that cannot be loaded is caught and converted
to
a ``click_plugins.core.BrokenCommand()`` rather than just crashing the
entire
CLI.  The short-help is converted to a warning message like:

.. code-block:: console

    Warning: could not load plugin. See ``<CLI> <command/group> --help``.

and if the sub-command or group is executed the entire traceback is
printed.

Best Practices and Extra Credit
-------------------------------

Opening a CLI to plugins encourages other developers to independently
extend


[FILE:119:distinfo]
5d262006d3222f5057fd81e1623d4443e41dcda5dc815c06b442aa3c02889fc8         7497 click_plugins-1.1.1-py2.py3-none-any.whl