Provided by: python3-cliapp_1.20180812.1-3build1_all 
NAME
cliapp - config file and option conventions for Python command line framework
DESCRIPTION
cliapp is a Python programming framework for writing command line applications for Unix-
like operating systems. This manual page describes the conventions for configuration
files and command line parsing provided by cliapp.
Configuration file variables and command line options are handled by cliapp under a
uniform abstraction: every setting is available both in configuration files and command
line options. There are a few settings, provided by the framework itself, which are only
available on the command line. For example, --help outputs a short help text, listing all
the available options, and --dump-config outputs a list of current configuration settings.
Command line parsing follows GNU conventions: short options start with a single dash, long
options with two dashes, and options may be used anywhere on the command line. The order
of options versus non-options does not matter. The exception is some of the options
provided by the framework, which are executed immediately when found, and may be prevent
the rest of the options from being parsed. (--dump-config is one of these, so use it at
the end of the command line only.) Use -- on the command line to signal the end of
options: no arguments after that are considered to be option.
Some settings may have aliases, which can be only a single character, and in that case
they're parsed as single-character option names.
Some applications have subcommands, which means that the first non-option argument is used
to tell the application what to do. This is similar to what many version control systems
do, for example CVS, svn, bzr, and git. Options are global, and are not specific to
subcommands. Thus, --foo means the same thing, regardless of what subcommand is being
used.
Configuration files
Configuration files use INI or YAML file syntax. Files named something.yaml are in YAML
syntax. Everything else are in INI syntax. An INI file might look like this:
[config]
foo = bar
[extra section]
yo = yoyo
The same file in YAML syntax would be:
config:
foo: bar
"extra section":
yo: yoyo
All the settings are in the [config] section. Other sections are allowed, but it is up to
the application to give meaning to them.
Multiple configuration files may be read. Settings from later ones override settings from
earlier ones. Options override settings from the configuration files.
String list settings in INI files
Some settings may be a list of values (each value being a string). For example, there
might be a setting for patterns to search for, and multiple patterns are allowed. On the
command line, that happens by using the option multiple times. In the configuration file,
all values are given on one logical line, separated by commas.
This is a non-standard extension to the INI file syntax.
To include an item that itself contains a comma, surround the item with double quotes.
There is no way to escape double quotes.
Example:
[config]
pattern = foo, bar, foobar, "hello, world"
Note than in versions of cliapp prior to 1.20150829, the command line option would also
break values with commas. This has since been fixed.
Configuration files in YAML use standard YAML syntax to express lists.
Expressing sizes in bytes
Some options take a value that gives the size as bytes. These take an optional unit
suffix. A plain integer is the size in bytes. The following units are supported:
suffix meaning factor
────────────────────────────────────────────
k, kb kilobyte 10**3 1000
m, mb megabyte 10**6 1000000
g, gb gigabyte 10**9 1000000000
t, tb terabyte 10**12 1000000000000
────────────────────────────────────────────
ki, kib kibibyte 2**10 1024
mi, mib mebibyte 2**20 1048576
gi, gib gibibyte 2**30 1073741824
ti, tib tebibyte 2**40 1099511627776
Suffixes may be upper or lower case, without change in meaning. Note that "b" and "B" are
identical, and both mean byte, not bit.
Boolean (true/false or on/off or yes/no) settings
When a setting can be either on or off, it's called a Boolean setting. Such settings are
turned off by default, and turned on if used on the command line. In a configuration
file, they need to be set to a value: if the value is one of yes, on, true, or the number
1, the setting is turned on. Any other value means it is turned off.
[config]
verbose = true
attack-kittens = no
This turns the verbose setting on, but does not launch attack kittens.
For every boolean setting, two command line options are added. If the setting is called
foo, the option --foo will turn the setting on, and --no-foo will turn it off. The
negation is only usable on the command line: its purpose is to allow the command line to
override a setting from the configuration file.
Logging and log files
Programs using cliapp automatically support several options for configuring the Python
logging module. See the --help output for options starting with log for details. Logging
can happen to a file or the system log. Log files can be rotated automatically based on
size.
The --trace option enables additional debug logging, which is usually only useful for
programmers. The option configures the tracing library for Python, by Lars Wirzenius,
which allows logging values of variables and other debug information in a way that is very
lightweight when the tracing is turned off. The option specifies for which source code
files to turn on tracing. The actual logging happens via the normal Python logging
facilities, at the debug level.
Python profiling support
You can run the application under the Python profiler (cProfile) by setting an environment
variable. The name of the variable is FOO_PROFILE, where FOO is the name of the program,
as set by the application code or determined by cliapp automatically. The value of the
environment variable is the name of the file to which the resulting profile is to be
written.
Manual page generation
cliapp can generate parts of a manual page: the SYNOPSIS and OPTIONS sections. It fills
these in automatically based on the subcommand and settings that a program supports. Use
the --generate-manpage=FILE option, which is added automatically by cliapp. The FILE is a
manual page marked up using the -man macros for troff(1). It should have empty SYNOPSIS
and OPTIONS sections, and cliapp will fill them in. The output it to the standard output.
For example:
foo --generate-manpage=foo.1.in > foo.1
You would keep the source code for the manual page in foo.1.in and have your Makefile
produce foo.1 as shown above.
Subcommands
cliapp provides a way for the application to have subcommands, in the style of git(1), for
example. If the application is called foo, then it can have subcommands such as foo
search, and foo print. The application gets to define the name and meaning of each
subcommand. However, all settings (options and configuration files) are global, and can
be used with all subcommands. It is up to each subcommand what settings it obeys.
If there are any subcommands, cliapp automatically adds the help subcommand. It allows
you to get the help text for a specific subommand: foo help print, for example.
FILES
cliapp reads a list of configuration files at startup, on behalf of the application. The
name of the application is included in the name. In the filenames below, the application
name is progname.
/etc/progname.conf
Global configuration file.
/etc/progname/*.conf
More global configuration files. These are read in ASCII sorted order.
~/.progname.conf
Per-user configuration file.
~/.config/progname/*.conf
More per-user configuration files. Again, ASCII sorted order.
In addition, the XDG Base Directory specification is followed, if the Python python-xdg
library is installed. In that case, environment variables can be set to set additional
location in which files are search for. The fixed names above are always search; the XDG
ones are search additionally.
CLIAPP(5)