click-plugins · PyPI Skip to main content Switch to mobile version Warning Some features may not work without JavaScript. Please try enabling it if you encounter problems. Search PyPI Search Help Sponsors Log in Register Menu Help Sponsors Log in Register Search PyPI Search click-plugins 1.1.1 pip install click-plugins Copy PIP instructions Latest version Released: Apr 4, 2019 An extension module for click to enable registering CLI commands via setuptools entry-points. Navigation Project description Release history Download files Project links Homepage Statistics GitHub statistics: Stars: Forks: Open issues/PRs: View statistics for this project via Libraries.io, or by using our public dataset on Google BigQuery Meta License: BSD License (New BSD) Author: Kevin Wurster, Sean Gillies Tags click, plugin, setuptools, entry-point Maintainers geowurster Classifiers Development Status 5 - Production/Stable Intended Audience Developers License OSI Approved :: BSD License Programming Language Python Python :: 3 Topic Utilities Project description Project details Release history Download files Project description 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. 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. 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: Warning: could not load plugin. See `` --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 functionality independently but there is no guarantee these new features will be “on brand”. Plugin developers are almost certainly already using features in the core package the CLI belongs to so defining commonly used arguments and options in one place lets plugin developers reuse these flags to produce a more cohesive CLI. If the CLI is simple maybe just define them at the top of yourpackage/cli.py or for more complex packages something like yourpackage/cli/options.py. These common options need to be easy to find and be well documented so that plugin developers know what variable to give to their sub-command’s function and what object they can expect to receive. Don’t forget to document non-obvious callbacks. Keep in mind that plugin developers also have access to the parent group’s ctx.obj, which is very useful for passing things like verbosity levels or config values around to sub-commands. Here’s some code that sub-commands could re-use: from multiprocessing import cpu_count import click jobs_opt = click.option( '-j', '--jobs', metavar='CORES', type=click.IntRange(min=1, max=cpu_count()), default=1, show_default=True, help="Process data across N cores." ) Plugin developers can access this with: import click import parent_cli_package.cli.options @click.command() @parent_cli_package.cli.options.jobs_opt def subcommand(jobs): """I do something domain specific.""" Installation With pip: $ pip install click-plugins From source: $ git clone https://github.com/click-contrib/click-plugins.git $ cd click-plugins $ python setup.py install Developing $ git clone https://github.com/click-contrib/click-plugins.git $ cd click-plugins $ pip install -e .\[dev\] $ pytest tests --cov click_plugins --cov-report term-missing Changelog See CHANGES.txt Authors See AUTHORS.txt License See LICENSE.txt Project details Project links Homepage Statistics GitHub statistics: Stars: Forks: Open issues/PRs: View statistics for this project via Libraries.io, or by using our public dataset on Google BigQuery Meta License: BSD License (New BSD) Author: Kevin Wurster, Sean Gillies Tags click, plugin, setuptools, entry-point Maintainers geowurster Classifiers Development Status 5 - Production/Stable Intended Audience Developers License OSI Approved :: BSD License Programming Language Python Python :: 3 Topic Utilities Release history Release notifications | RSS feed This version 1.1.1 Apr 4, 2019 1.1 Apr 4, 2019 1.0.4 Sep 16, 2018 1.0.3 Jan 5, 2016 1.0.2 Sep 23, 2015 1.0.1 Aug 20, 2015 1.0 Jul 21, 2015 Download files Download the file for your platform. If you're not sure which to choose, learn more about installing packages. Files for click-plugins, version 1.1.1 Filename, size File type Python version Upload date Hashes Filename, size click_plugins-1.1.1-py2.py3-none-any.whl (7.5 kB) File type Wheel Python version py2.py3 Upload date Apr 4, 2019 Hashes View Filename, size click-plugins-1.1.1.tar.gz (8.2 kB) File type Source Python version None Upload date Apr 4, 2019 Hashes View Close Hashes for click_plugins-1.1.1-py2.py3-none-any.whl Hashes for click_plugins-1.1.1-py2.py3-none-any.whl Algorithm Hash digest SHA256 5d262006d3222f5057fd81e1623d4443e41dcda5dc815c06b442aa3c02889fc8 Copy MD5 943968f6aa1a14862f164c2080cb2fda Copy BLAKE2-256 e9da824b92d9942f4e472702488857914bdd50f73021efea15b4cad9aca8ecef Copy Close Close Hashes for click-plugins-1.1.1.tar.gz Hashes for click-plugins-1.1.1.tar.gz Algorithm Hash digest SHA256 46ab999744a9d831159c3411bb0c79346d94a444df9a3a3742e9ed63645f264b Copy MD5 969268b5b005b2b56115c66c55013252 Copy BLAKE2-256 5f1d45434f64ed749540af821fd7e42b8e4d23ac04b1eda7c26613288d6cd8a8 Copy Close Help Installing packages Uploading packages User guide FAQs About PyPI PyPI on Twitter Infrastructure dashboard Package index name retention Our sponsors Contributing to PyPI Bugs and feedback Contribute on GitHub Translate PyPI Development credits Using PyPI Code of conduct Report security issue Privacy policy Terms of use Status: all systems operational Developed and maintained by the Python community, for the Python community. Donate today! © 2021 Python Software Foundation Site map Switch to desktop version English español français 日本語 português (Brasil) українська Ελληνικά Deutsch 中文 (简体) русский עברית esperanto Supported by AWS Cloud computing Datadog Monitoring DigiCert EV certificate Facebook / Instagram PSF Sponsor Fastly CDN Google Object Storage and Download Analytics Pingdom Monitoring Salesforce PSF Sponsor Sentry Error logging StatusPage Status page