bucket_C8/python-click-plugins

   1 # Buildsheet autogenerated by ravenadm tool -- Do not edit.
   2
   3 NAMEBASE=               python-click-plugins
   4 VERSION=                1.1.1
   5 KEYWORDS=               python
   6 VARIANTS=               py310 py311
   7 SDESC[py310]=           Registers external CLI commands (3.10)
   8 SDESC[py311]=           Registers external CLI commands (3.11)
   9 HOMEPAGE=               https://github.com/click-contrib/click-plugins
  10 CONTACT=                Python_Automaton[python@ironwolf.systems]
  11
  12 DOWNLOAD_GROUPS=        main
  13 SITES[main]=            PYPIWHL/e9/da/824b92d9942f4e472702488857914bdd50f73021efea15b4cad9aca8ecef
  14 DISTFILE[1]=            click_plugins-1.1.1-py2.py3-none-any.whl:main
  15 DF_INDEX=               1
  16 SPKGS[py310]=           single
  17 SPKGS[py311]=           single
  18
  19 OPTIONS_AVAILABLE=      PY310 PY311
  20 OPTIONS_STANDARD=       none
  21 VOPTS[py310]=           PY310=ON PY311=OFF
  22 VOPTS[py311]=           PY310=OFF PY311=ON
  23
  24 DISTNAME=               click_plugins-1.1.1.dist-info
  25
  26 GENERATED=              yes
  27
  28 [PY310].RUN_DEPENDS_ON=                 python-click:single:py310
  29 [PY310].USES_ON=                        python:py310,wheel
  30
  31 [PY311].RUN_DEPENDS_ON=                 python-click:single:py311
  32 [PY311].USES_ON=                        python:py311,wheel
  33
  34 [FILE:2803:descriptions/desc.single]
  35 =============
  36 click-plugins
  37 =============
  38
  39 An extension module for [click] to register
  40 external CLI commands via setuptools entry-points.
  41
  42 Why?
  43 ----
  44
  45 Lets say you develop a commandline interface and someone requests a new
  46 feature
  47 that is absolutely related to your project but would have negative
  48 consequences
  49 like additional dependencies, major refactoring, or maybe its just too
  50 domain
  51 specific to be supported directly.  Rather than developing a separate
  52 standalone
  53 utility you could offer up a [setuptools entry point]
  54 that allows others to use your commandline utility as a home for their
  55 related
  56 sub-commands.  You get to choose where these sub-commands or sub-groups CAN
  57 be
  58 registered but the plugin developer gets to choose they ARE registered.
  59 You
  60 could have all plugins register alongside the core commands, in a special
  61 sub-group, across multiple sub-groups, or some combination.
  62
  63 Enabling Plugins
  64 ----------------
  65
  66 For a more detailed example see the [examples] section.
  67
  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
  71 core CLI developer
  72 registers CLI plugins from ``core_package.cli_plugins``.
  73
  74 .. code-block:: python
  75
  76     from pkg_resources import iter_entry_points
  77
  78     import click
  79     from click_plugins import with_plugins
  80
  81     @with_plugins(iter_entry_points('core_package.cli_plugins'))
  82     @click.group()
  83     def cli():
  84         """Commandline interface for yourpackage."""
  85
  86     @cli.command()
  87     def subcommand():
  88         """Subcommand that does something."""
  89
  90 Developing Plugins
  91 ------------------
  92
  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.
  95
  96 .. code-block:: python
  97
  98     from setuptools import setup
  99
 100     setup(
 101         name='yourscript',
 102         version='0.1',
 103         py_modules=['yourscript'],
 104         install_requires=[
 105             'click',
 106        ],
 107         entry_points='''
 108             [core_package.cli_plugins]
 109             cool_subcommand=yourscript.cli:cool_subcommand
 110             another_subcommand=yourscript.cli:another_subcommand
 111         ''',
 112     )
 113
 114 Broken and Incompatible Plugins
 115 -------------------------------
 116
 117 Any sub-command or sub-group that cannot be loaded is caught and converted
 118 to
 119 a ``click_plugins.core.BrokenCommand()`` rather than just crashing the
 120 entire
 121 CLI.  The short-help is converted to a warning message like:
 122
 123 .. code-block:: console
 124
 125     Warning: could not load plugin. See ``<CLI> <command/group> --help``.
 126
 127 and if the sub-command or group is executed the entire traceback is
 128 printed.
 129
 130 Best Practices and Extra Credit
 131 -------------------------------
 132
 133 Opening a CLI to plugins encourages other developers to independently
 134 extend
 135
 136
 137 [FILE:119:distinfo]
 138 5d262006d3222f5057fd81e1623d4443e41dcda5dc815c06b442aa3c02889fc8         7497 click_plugins-1.1.1-py2.py3-none-any.whl
 139