Package: plugcli
plugcliSimple click-based tools for plugin-based CLIs.plugcliis a small extension ofclick. It provides several
useful pieces of functionality, including:A plugin registration system, allowing user-created plugins to be registered
either by installing in a given namespace or by adding plugin files to a
specified directory.A CLI class that uses that plugin registration system to register new
subcommands, and which separates subcommands into sections for the--helpdocumentation.Tools to facilitate reuse of parameters between different subcommands,
helping ensure a consistent user interface. While much of this is already
enabled byclick, the tools inplugcliare particularly useful in cases
whereclick's callbacks may not be sufficient, such as when the order in
which parameters are parsed is important.Installingplugcliplugclican be installed through the standard mechanisms:pip install plugcli; orconda install -c conda-forge plugcli, or install from source
using setuptools (python setup.py install, etc.) Its only direct dependency
isclick.Plugin registrationThe plugin registration system is designed to handle plugins that can
essentially be treated as entries in a dispatch table. That is, these are
plugins that are designed to give optionally-used additional functionality.
Subcommands of the CLI are one example, andplugcliprovides specific tools
for this use case. Other examples might support for additional keywords when
processing a user input file, or support for other options in menus for
interactive user interfaces.The basic approach to writing plugins is to wrap user-defined functionality in
some subclass of theplugcli.Pluginclass, which may also encapsulate
additional metadata of use to the program. For example, theplugcli.CommandPluginclass also takes asectionlabel, to tell which help
section the plugin command should be listed in.A program defines where a user can put plugins by creating one or morePluginLoaders. The two concrete classes ofPluginLoaderareFilePluginLoader, which takes a directory and searches for any plugins in
Python files in that directory, and theNamespacePluginLoader, which takes a
string representing a Python namespace and searches for any plugins in
modules/subpackages found in that namespace.CLI ClassTheplugcli.CLIclass subclassesclick.CLI, adding support for loading
commands from theplugcliplugin structure, and sorting commands in--helpinto sections defined by the developer.Users must subclassplugcli.CLI. The subclass should set the class variableCOMMAND_SECTIONSto a list of the section names used in sorting plugins for
the help. The subclass should also implement theget_installed_pluginsmethod, which uses a selection ofPluginLoaders that determine the locations
where plugins will be found and registered.Reusable parametersThe goal ofplugcli's reusable parameters is to ensure consistency throughout
different subcommands by encapsulating names and behavior of parameters that
can be shared. This is done with theplugcli.Optionandplugcli.Argumentclasses, which take the same parameters as theclick.optionandclick.parameterdecorators, plus agetterkeyword-only argument that takes
an callable which converts the user input as processed byclickand returns
an object ready for use in the CLI's underlying library code. This takes a
user-definedcontextdict, which provides more flexibility than the standardclickcallbacks.You can create a standard click decorator for one of these parameters with the.parameter()method, allowing a single parameter instance to be reused in
multiple subcommands.clickarguments set in the initialization of theplugcliparameter can be overridden by keyword arguments passed to the.parametermethod, allowing some customizability in special cases (e.g., to
allow the parameter to be called a different number of times) while retaining
most of the consistency.Historyplugcliwas originally part of theOpenPathSampling
CLI. It was
refactored into a separate package as it become more evident that it filled a
small, but useful, niche, and could be reused in other projects.