Command line tool

PyFiguration ships with a convenient command line tool that can generate documentation for the configuration of a script, and that can inspect a give configuration for errors and potential mistakes.

Getting help

Run the following command to get the full usage instructions for the command line tool:

$ pyfiguration --help
usage: pyfiguration [-h] {inspect} ...

PyFiguration commandline tool

Use this commandline tool to inspect scripts and have a look at the
configuration options that the script provides. Furthermore you can
inspect configuration files directly.

optional arguments:
  -h, --help  show this help message and exit

Commands:
  {inspect}
    inspect   Inspect configurations and scripts



$ pyfiguration inspect --help
usage: pyfiguration inspect [-h] {config,script} ...

Inspect configuration files, scripts or modules to see which values are
allowed, or to check if a provided configuration file is valid for a specific
script.

optional arguments:
  -h, --help       show this help message and exit

Commands:
  The type object you would like to inspect

  {config,script}
    config         Inspect a configuration file to see if it is valid for a
                   given script
    script         Inspect a script to see what configuration options are
                   available



$ pyfiguration inspect script --help
usage: pyfiguration inspect script [-h] [-s SCRIPT]

Provide a file or script to inspect it with PyFiguration. This command will
load the script from file and inspect the PyFiguration decorators to find out
what the configuration options are. Then, it will display all the option as
the output of this command. SCRIPT is the filename of the script to inspect
with PyFiguraton

optional arguments:
  -h, --help            show this help message and exit
  -s SCRIPT, --script SCRIPT
                        The script against which to inspect the config



$ pyfiguration inspect config --help
usage: pyfiguration inspect config [-h] [-c [CONFIG [CONFIG ...]]] [-s SCRIPT]

This command will load the SCRIPT and look at the defintion. Then it will load
the CONFIG file and makes sure the CONFIG file is valid for the provided
SCRIPT. SCRIPT is the filename of the SCRIPT to inspect with PyFiguraton,
CONFIG file is the configuration file to inspect, against the SCRIPT.

optional arguments:
  -h, --help            show this help message and exit
  -c [CONFIG [CONFIG ...]], --config [CONFIG [CONFIG ...]]
                        The configuration file to inspect
  -s SCRIPT, --script SCRIPT
                        The script against which to inspect the config

Inspect a script/module

To inspect a script or module and find out what the allowed configurations are, the command line tool can be used. An example:

$ pyfiguration inspect script -s basic.py
The following options can be used in a configuration file for the module 'basic.py':
db:
  host:
    allowedDataType: str
    default: localhost
    description: Location of the database, e.g. localhost
    required: true
  port:
    allowedDataType: int
    default: 8000
    description: Port of the database to connect on
    maxValue: 9999
    minValue: 80
    required: true

In this example we’ve inspected a script called basic.py. The output shows (in YAML format) which fields can be specified in a configuration file, what type the value should have, and how this value is checked (e.g. minValue: 80 will check any configuration file to make sure the value for the field port is >= 80).

Inspect a configuration file

If you have a script, and a configuration file, you can check the configuration file to see if it’s valid for your script. Example:

$ pyfiguration inspect config -s script.py -c config.yaml

$ pyfiguration inspect config -s script.py -c config_with_warnings.yaml
--------
 Errors
--------
   ✗ Value '500.0' is not of the correct type. The allowed data type is: int
----------
 Warnings
----------
   ! Key 'server.not_needed_key' doesn't exist in the definition and is not used in the module.

In this example we run the inspector 2 times. The first time with a valid configuration file (so nothing is returned). The second time we have a configuration file with errors. Apparently we’ve specified a float where we should have specified an integer. Also, we’ve defined a key in our configuration that is not used by the script. This will not break the script, but because it might result in unexpected behaviour it’s raised as a warning.