1 # Buildsheet autogenerated by ravenadm tool -- Do not edit.
3 NAMEBASE= python-click-plugins
7 SDESC[py310]= Registers external CLI commands (3.10)
8 SDESC[v11]= Registers external CLI commands (3.11)
9 HOMEPAGE= https://github.com/click-contrib/click-plugins
10 CONTACT= Python_Automaton[python@ironwolf.systems]
13 SITES[main]= PYPIWHL/e9/da/824b92d9942f4e472702488857914bdd50f73021efea15b4cad9aca8ecef
14 DISTFILE[1]= click_plugins-1.1.1-py2.py3-none-any.whl:main
19 OPTIONS_AVAILABLE= PY310 PY311
20 OPTIONS_STANDARD= none
21 VOPTS[py310]= PY310=ON PY311=OFF
22 VOPTS[v11]= PY310=OFF PY311=ON
24 DISTNAME= click_plugins-1.1.1.dist-info
28 [PY310].RUN_DEPENDS_ON= python-click:single:py310
29 [PY310].USES_ON= python:py310,wheel
31 [PY311].RUN_DEPENDS_ON= python-click:single:v11
32 [PY311].USES_ON= python:v11,wheel
34 [FILE:2803:descriptions/desc.single]
39 An extension module for [click] to register
40 external CLI commands via setuptools entry-points.
45 Lets say you develop a commandline interface and someone requests a new
47 that is absolutely related to your project but would have negative
49 like additional dependencies, major refactoring, or maybe its just too
51 specific to be supported directly. Rather than developing a separate
53 utility you could offer up a [setuptools entry point]
54 that allows others to use your commandline utility as a home for their
56 sub-commands. You get to choose where these sub-commands or sub-groups CAN
58 registered but the plugin developer gets to choose they ARE registered.
60 could have all plugins register alongside the core commands, in a special
61 sub-group, across multiple sub-groups, or some combination.
66 For a more detailed example see the [examples] section.
68 The only requirement is decorating ``click.group() with
69 click_plugins.with_plugins()``
70 which handles attaching external commands and groups. In this case the
72 registers CLI plugins from ``core_package.cli_plugins``.
74 .. code-block:: python
76 from pkg_resources import iter_entry_points
79 from click_plugins import with_plugins
81 @with_plugins(iter_entry_points('core_package.cli_plugins'))
84 """Commandline interface for yourpackage."""
88 """Subcommand that does something."""
93 Plugin developers need to register their sub-commands or sub-groups to an
94 entry-point in their ``setup.py`` that is loaded by the core package.
96 .. code-block:: python
98 from setuptools import setup
103 py_modules=['yourscript'],
108 [core_package.cli_plugins]
109 cool_subcommand=yourscript.cli:cool_subcommand
110 another_subcommand=yourscript.cli:another_subcommand
114 Broken and Incompatible Plugins
115 -------------------------------
117 Any sub-command or sub-group that cannot be loaded is caught and converted
119 a ``click_plugins.core.BrokenCommand()`` rather than just crashing the
121 CLI. The short-help is converted to a warning message like:
123 .. code-block:: console
125 Warning: could not load plugin. See ``<CLI> <command/group> --help``.
127 and if the sub-command or group is executed the entire traceback is
130 Best Practices and Extra Credit
131 -------------------------------
133 Opening a CLI to plugins encourages other developers to independently
138 5d262006d3222f5057fd81e1623d4443e41dcda5dc815c06b442aa3c02889fc8 7497 click_plugins-1.1.1-py2.py3-none-any.whl