Configuration¶
As indicated before, configuration is a dictionnary. It recursively defines the
commands configuration. The configuration of a command is a mix of keywords
between the argparse
module and this module. Keywords for defining a command
are:
- prog (argparse)
- usage (argparse)
- description (argparse)
- epilog (argparse)
- formatter_class (argparse)
- argument_default (argparse)
- conflict_handler (argparse)
- add_help (argparse)
- anchors (clg)
- options (clg)
- args (clg)
- groups (clg)
- exclusive_groups (clg)
- execute (clg)
- subparsers (clg)
prog¶
argparse link: http://docs.python.org/dev/library/argparse.html#prog
Set the name of the program.
usage¶
argparse link: http://docs.python.org/dev/library/argparse.html#usage
Set the usage of the command.
description¶
argparse link: http://docs.python.org/dev/library/argparse.html#description
Add a description of the command in the help.
epilog¶
argparse link: http://docs.python.org/dev/library/argparse.html#epilog
Add a comment at the end of the help.
formatter_class¶
argparse link: http://docs.python.org/dev/library/argparse.html#formatter-class
Class indicating how the help is formatted.
argument_default¶
argparse link: http://docs.python.org/dev/library/argparse.html#argument-default
The global default value for arguments (default: None).
conflict_handler¶
argparse link: http://docs.python.org/dev/library/argparse.html#conflict-handler
Indicate how to handle conflict between options.
add_help¶
argparse link: http://docs.python.org/dev/library/argparse.html#add-help
Indicate whether a default -h
/--help
option is added to the command-line,
allowing to print help.
anchors¶
This section has been created for YAML files. You can defined any structure in here (like common options between commands) and use it anywhere through YAML anchors.
options¶
This section defines the options of the current command. It is a dictionnary
whose keys are the name of the option (long format beginning with two dashes)
and values a hash with the configuration of the option. In argparse
module,
dest keyword defines the keys in the resulted Namespace. It is not possible
to overload this parameter as the name of the option in the configuration is
used as destination.
Keywords:
- action (argparse)
- nargs (argparse)
- const (argparse)
- default (argparse)
- choices (argparse)
- required (argparse)
- help (argparse)
- metavar (argparse)
- type (argparse)
- short (clg)
- need (clg)
- conflict (clg)
- match (clg)
Note
Options with underscores and spaces in the configuration are replaced
by dashes in the command (but not in the resulted Namespace). For example,
an option my_opt
in the configuration will be rendered as --my-opt
in
the command.
It is possible to use builtins in some options (default, const, ...).
For this, a special syntax is used. The builtin can be defined in uppercase,
prefixing and sufixing by double underscores: __BUILTIN__
. For example:
options:
sum:
action: store_const
const: __SUM__
default: __MAX__
help: "sum the integers (default: find the max)"
- In the same way, there are two additionnal “builtins”:
__DEFAULT__
: in the value of the help option, this keyword is replaced by the default value of the option.__FILE__
: this “builtin” is replaced by the path of the main program (sys.path[0]). This allow to define file relatively to the main program (ex: __FILE__/conf/someconf.yml, __FILE__/logs/).
short¶
This section must contain a single letter defining the short name (beginning with a single dash) of the current option.
help¶
argparse link: http://docs.python.org/dev/library/argparse.html#help
Description of the option.
required¶
argparse link: http://docs.python.org/dev/library/argparse.html#required
Boolean indicating whether the option is necessary.
type¶
argparse link: http://docs.python.org/dev/library/argparse.html#type
This option indicate the type of the option. As this is necessarily a builtin,
this is not necessary to use the __BULTIN__
syntax.
It is possible to add custom types. For this, you must define a function
that check the given value for the option and add this function to
clg.TYPES
. For example, to add a custom Date
type based on french date
format (DD/MM/YYYY) and returning a datetime
object:
Python program:
import clg
import yaml
def Date(value):
from datetime import datetime
try:
return datetime.strptime(value, '%d/%m/%Y')
except Exception as err:
raise clg.argparse.ArgumentTypeError(err)
clg.TYPES['Date'] = Date
command = clg.CommandLine(yaml.load(open('cmd.yml'))
args = command.parse()
YAML configuration:
...
options:
date:
short: d
type: Date
help: Date.
...
default¶
argparse link: http://docs.python.org/dev/library/argparse.html#default
Set a default value for the option.
choices¶
argparse link: http://docs.python.org/dev/library/argparse.html#choices
This is a list indicating the possible values for the option.
action¶
argparse link: http://docs.python.org/dev/library/argparse.html#action
This indicate what to do with the value.
nargs¶
argparse link: http://docs.python.org/dev/library/argparse.html#nargs
This allow to define the number of values of an option (by default, an option look for only one argument).
const¶
argparse link: http://docs.python.org/dev/library/argparse.html#const
Value in the Namespace if the option is not set in the command-line (None by default).
Note
If nargs is defined for the option, the default value will be an empty list.
metavar¶
argparse link: http://docs.python.org/dev/library/argparse.html#metavar
Representation in the help of the value of an option.
need¶
This is a list of options needed with the current option.
conflict¶
This is a list of options that must not be used with the current option.
match¶
This is a regular expression that the option’s value must match.
args¶
This section define arguments of the current command. It is identical as the options section at the exception of the short keyword which is not available.
groups¶
This section is a list of groups. Each group (https://docs.python.org/dev/library/argparse.html#argument-groups) can have theses keywords:
- title (argparse)
- description (argparse)
- options (clg)
title¶
Customize help with a title.
description¶
Customize help with a description
exclusive groups¶
This section is a list of exclusive groups. Each exclusive group (https://docs.python.org/dev/library/argparse.html#mutual-exclusion) can have theses keywords:
- required (argparse)
- options (clg)
required¶
Boolean indicating if at least one of the arguments is required.
execute¶
This section indicate what must be done after the command is parsed. It allow to import a file or a module and launch a function in it. This function only take one argument which is the Namespace containing arguments.
- Keywords:
- module
- file
- function
Note
module and file keywords can’t be used simultaneously.
file¶
This is a string indicating the path of a python file.
module¶
This is a string indicating the module to load (ex: package.subpackage.module).
This recursively load all intermediary packages until the module. As the
directory of the main program is automatically in sys.path
, that allow to
import modules relatively to the main program.
For example, the directory structure of your program could be like this:
.
├── prog.py => Main program intializing clg
├── conf/cmd.yml => Command-line configuration
└── commands/ => commands package directory
├── __init__.py
└── list => commands.list subpackage directory
├── __init__.py
└── users.py => users module in commands.list subpackage
And the configuration syntax is:
subparsers:
list:
subparsers:
users:
execute:
module: commands.list.users
This will execute the main
function if the file commands/list/users.py.
function¶
This is the function in the loaded file or module that will be executed
(default: main
).
subparsers¶
argparse link: https://docs.python.org/dev/library/argparse.html#argparse.ArgumentParser.add_subparsers
This allow to add subcommands to the current command.
- Keywords:
- help (argparse)
- title (argparse)
- description (argparse)
- prog (argparse)
- help (argparse)
- metavar (argparse)
- parsers (clg)
Note
It is possible to directly set parsers configurations (the content of parsers subsection) in this section. The module check for the presence of parsers section and, if not present, consider this is subcommands configurations.
When using subparsers and for being able to retrieves configuration of
the used (sub)command, dest argument of add_subparsers
method is used.
It add in the resulted Namespace an entry whose key is the value of dest
and the value the used subparser. The key is generated from the keyword
argument (default: command) of the CommandLine object, incremented at each
level of the arborescence. From the previous example the
resulted Namespace is:
# python prog.py list users
Namespace(command0='list', command1='users')
title¶
Customize the help with a title.
description¶
Customize the help with a description
help¶
Additional help message.
prog¶
Customize usage in help.
help¶
Help for sub-parser group in help output.
metavar¶
String presenting available sub-commands in help
parsers¶
This is a hash whose keys are the name of subcommands and values the configuration of the command.