Metadata-Version: 2.1
Name: dhm-module-example
Version: 0.0.1
Summary: Example that plugs into dhm_module_base
Home-page: https://github.com/Kortforsyningen/dhm-module-example
Author: Nicolai Mogensen
Author-email: nicolai@septima.dk
License: Licensed under the MIT license
Description: # 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: [![CircleCI](https://circleci.com/gh/Kortforsyningen/dhm-module-example.svg?style=svg)](https://circleci.com/gh/Kortforsyningen/dhm-module-example)
        
        ## 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.
        
Keywords: eksempel
Platform: UNKNOWN
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Scientific/Engineering :: GIS
Description-Content-Type: text/markdown
Provides-Extra: dev
