GitLocker: The Coding Marketplace

Description:

dhmmoduleexample 0.0.1

DHM Example Module
Basic module meant as a plugin for dhm_module_base. It shows basic functionality on how to "plug" in commands into the main CLI.
Plugin for https://github.com/Kortforsyningen/dhm-module-base
The CLI module is based on Click https://click.palletsprojects.com/en/7.x/
Module is packaged by PyPi: https://pypi.org/project/dhm-module-example/
Build status Linux:
Installation
Conda Environment
git clone https://github.com/Kortforsyningen/dhm-module-example
cd dhm-module-example
conda env create -n dhm_module_example -f environment.yml
conda activate dhm_module_example
pip install .

The plugin can also be installed in developer or "editable" mode.
git clone https://github.com/Kortforsyningen/dhm-module-example
cd dhm-module-base
conda env create -n dhm_module_example -f environment-dev.yml
conda activate dhm_module_example
pip install -e .

Usage
This plugin has dhm_module_base https://github.com/Kortforsyningen/dhm-module-base as a dependency, and does not work without it.
This plugin "plugs" into dhm_module_base using a click group and a set of entrypoints in setup.py
Adding commands is done by adding an entrypoint to setup.py under the [dhm_module_base.plugins] section. Each command has to be added here for it to be exposed on the CLI.
ENTRY_POINTS = """
[dhm_module_base.plugins]
inout=dhm_module_example.core:inout
pipe=dhm_module_example.core:pipe
configuration=dhm_module_example.core:configuration

"""

Calling the base plugin will now reveal these three commands:
Usage: dhm_module_base [OPTIONS] COMMAND [ARGS]...

dhm_module_base command line interface.

Options:
--version Show the version and exit.
-v, --verbosity [CRITICAL|ERROR|WARNING|INFO|DEBUG]
Set verbosity level
-c, --config FILENAME Configuration file
--help Show this message and exit.

Commands:
configuration Example command configuration.
inout Example command inout.
pipe Example of a custom options handler being used along with
a...

If a command is not able to be imported it is considered broken, and will display a small error on the CLI. If we deliberately break a command (we can mispell to command in the entrypoing) we get the following error:
Usage: dhm_module_base [OPTIONS] COMMAND [ARGS]...

dhm_module_base command line interface.

Options:
--version Show the version and exit.
-v, --verbosity [CRITICAL|ERROR|WARNING|INFO|DEBUG]
Set verbosity level
-c, --config FILENAME Configuration file
--help Show this message and exit.

Commands:
configuration † Warning: could not load plugin. See `dhm_module_base
configuration --help`.

inout Example command inout.
pipe Example of a custom options handler being used along with
a...

To debug, we check dhm_module_base configuration --help and get the following output:
ImportError: module 'dhm_module_example.core' has no attribute 'configurationsssss'

This error is fabricated for the purpose of this example. Usually commands will return errors if package requirements are not met, commands are not linked properly in setup.py etc.
Registering a new command
Registering a new command is done by decorating a python function with the @click.command() decorator, telling click that the function is a CLI command. Descriptions are harvested by the functions docstring, so make sure it's descriptive of what the command does. Arguments and options are added by using the @click.argument() and @click.option() decorators. For more information see:
https://click.palletsprojects.com/en/7.x/quickstart/#basic-concepts-creating-a-command
Accessing the configuration object
Click commands can access the current context ctx by decorating commands with @click.pass_context and setting the first argument to ctx. The base module puts the configuration object on ctx.obj["config"], so if a command is decorated with @click.pass_context this context can be fetched. See https://click.palletsprojects.com/en/7.x/commands/#nested-handling-and-contexts.
The base module can be supplied with an .ini file using the -c | --config option. A command could look like dhm_module_base -c "config.ini" inout - "out.txt" which will call the inout plugin command with a base configuration in config.ini. If inout is decorated with pass_context, configuration specific options like database connections or paths can be retrieved.