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

NAMEBASE=		python-click-plugins
VERSION=		1.1.1.2
KEYWORDS=		python
VARIANTS=		v13 v14
SDESC[v13]=		Registers external CLI commands (3.13)
SDESC[v14]=		Registers external CLI commands (3.14)
HOMEPAGE=		https://github.com/click-contrib/click-plugins
CONTACT=		Python_Automaton[python@ironwolf.systems]

DOWNLOAD_GROUPS=	main
SITES[main]=		PYPIWHL/3d/9a/2abecb28ae875e39c8cad711eb1186d8d14eab564705325e77e4e6ab9ae5
DISTFILE[1]=		click_plugins-1.1.1.2-py2.py3-none-any.whl:main
DIST_SUBDIR=		python-src
DF_INDEX=		1
SPKGS[v13]=		single
SPKGS[v14]=		single

OPTIONS_AVAILABLE=	PY313 PY314
OPTIONS_STANDARD=	none
VOPTS[v13]=		PY313=ON PY314=OFF
VOPTS[v14]=		PY313=OFF PY314=ON

DISTNAME=		click_plugins-1.1.1.2.dist-info

GENERATED=		yes

[PY313].RUN_DEPENDS_ON=			python-click:single:v13
[PY313].USES_ON=			python:v13,wheel

[PY314].RUN_DEPENDS_ON=			python-click:single:v14
[PY314].USES_ON=			python:v14,wheel

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

This PyPI package is no longer actively maintained, but the underlying
library can be vendored. See [homepage]
for more information.

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


[FILE:132:distinfo]
008d65743833ffc1f5417bf0e78e8d2c23aab04d9745ba817bd3e71b0feb6aa6        11051 python-src/click_plugins-1.1.1.2-py2.py3-none-any.whl