1CLIAPP(5) File Formats Manual CLIAPP(5)
2
6 cliapp - config file and option conventions for Python command line
7 framework
8
10 cliapp is a Python programming framework for writing command line
11 applications for Unix-like operating systems. This manual page
12 describes the conventions for configuration files and command line
13 parsing provided by cliapp.
14 Configuration file variables and command line options are handled by
16 cliapp under a uniform abstraction: every setting is available both in
17 configuration files and command line options. There are a few set‐
18 tings, provided by the framework itself, which are only available on
19 the command line. For example, --help outputs a short help text, list‐
20 ing all the available options, and --dump-config outputs a list of cur‐
21 rent configuration settings.
22 Command line parsing follows GNU conventions: short options start with
24 a single dash, long options with two dashes, and options may be used
25 anywhere on the command line. The order of options versus non-options
26 does not matter. The exception is some of the options provided by the
27 framework, which are executed immediately when found, and may be pre‐
28 vent the rest of the options from being parsed. (--dump-config is one
29 of these, so use it at the end of the command line only.) Use -- on
30 the command line to signal the end of options: no arguments after that
31 are considered to be option.
32 Some settings may have aliases, which can be only a single character,
34 and in that case they're parsed as single-character option names.
35 Some applications have subcommands, which means that the first non-
37 option argument is used to tell the application what to do. This is
38 similar to what many version control systems do, for example CVS, svn,
39 bzr, and git. Options are global, and are not specific to subcommands.
40 Thus, --foo means the same thing, regardless of what subcommand is
41 being used.
42 Configuration files
44 Configuration files use INI or YAML file syntax. Files named some‐
45 thing.yaml are in YAML syntax. Everything else are in INI syntax. An
46 INI file might look like this:
47 [config]
49 foo = bar
50 [extra section]
52 yo = yoyo
53 The same file in YAML syntax would be:
55 config:
57 foo: bar
58 "extra section":
59 yo: yoyo
60 All the settings are in the [config] section. Other sections are
62 allowed, but it is up to the application to give meaning to them.
63 Multiple configuration files may be read. Settings from later ones
65 override settings from earlier ones. Options override settings from
66 the configuration files.
67 String list settings in INI files
69 Some settings may be a list of values (each value being a string). For
70 example, there might be a setting for patterns to search for, and mul‐
71 tiple patterns are allowed. On the command line, that happens by using
72 the option multiple times. In the configuration file, all values are
73 given on one logical line, separated by commas.
74 This is a non-standard extension to the INI file syntax.
76 To include an item that itself contains a comma, surround the item with
78 double quotes. There is no way to escape double quotes.
79 Example:
81 [config]
83 pattern = foo, bar, foobar, "hello, world"
84 Note than in versions of cliapp prior to 1.20150829, the command line
86 option would also break values with commas. This has since been fixed.
87 Configuration files in YAML use standard YAML syntax to express lists.
89 Expressing sizes in bytes
91 Some options take a value that gives the size as bytes. These take an
92 optional unit suffix. A plain integer is the size in bytes. The fol‐
93 lowing units are supported:
94 suffix meaning factor
96 ────────────────────────────────────────────
97 k, kb kilobyte 10**3 1000
98 m, mb megabyte 10**6 1000000
99 g, gb gigabyte 10**9 1000000000
100 t, tb terabyte 10**12 1000000000000
101 ────────────────────────────────────────────
102 ki, kib kibibyte 2**10 1024
103 mi, mib mebibyte 2**20 1048576
104 gi, gib gibibyte 2**30 1073741824
105 ti, tib tebibyte 2**40 1099511627776
106 Suffixes may be upper or lower case, without change in meaning. Note
108 that "b" and "B" are identical, and both mean byte, not bit.
109 Boolean (true/false or on/off or yes/no) settings
111 When a setting can be either on or off, it's called a Boolean setting.
112 Such settings are turned off by default, and turned on if used on the
113 command line. In a configuration file, they need to be set to a value:
114 if the value is one of yes, on, true, or the number 1, the setting is
115 turned on. Any other value means it is turned off.
116 [config]
118 verbose = true
119 attack-kittens = no
120 This turns the verbose setting on, but does not launch attack kittens.
122 For every boolean setting, two command line options are added. If the
124 setting is called foo, the option --foo will turn the setting on, and
125 --no-foo will turn it off. The negation is only usable on the command
126 line: its purpose is to allow the command line to override a setting
127 from the configuration file.
128 Logging and log files
130 Programs using cliapp automatically support several options for config‐
131 uring the Python logging module. See the --help output for options
132 starting with log for details. Logging can happen to a file or the
133 system log. Log files can be rotated automatically based on size.
134 The --trace option enables additional debug logging, which is usually
136 only useful for programmers. The option configures the tracing library
137 for Python, by Lars Wirzenius, which allows logging values of variables
138 and other debug information in a way that is very lightweight when the
139 tracing is turned off. The option specifies for which source code
140 files to turn on tracing. The actual logging happens via the normal
141 Python logging facilities, at the debug level.
142 Python profiling support
144 You can run the application under the Python profiler (cProfile) by
145 setting an environment variable. The name of the variable is FOO_PRO‐
146 FILE, where FOO is the name of the program, as set by the application
147 code or determined by cliapp automatically. The value of the environ‐
148 ment variable is the name of the file to which the resulting profile is
149 to be written.
150 Manual page generation
152 cliapp can generate parts of a manual page: the SYNOPSIS and OPTIONS
153 sections. It fills these in automatically based on the subcommand and
154 settings that a program supports. Use the --generate-manpage=FILE
155 option, which is added automatically by cliapp. The FILE is a manual
156 page marked up using the -man macros for troff(1). It should have
157 empty SYNOPSIS and OPTIONS sections, and cliapp will fill them in. The
158 output it to the standard output.
159 For example:
161 foo --generate-manpage=foo.1.in > foo.1
163 You would keep the source code for the manual page in foo.1.in and have
165 your Makefile produce foo.1 as shown above.
166 Subcommands
168 cliapp provides a way for the application to have subcommands, in the
169 style of git(1), for example. If the application is called foo, then
170 it can have subcommands such as foo search, and foo print. The appli‐
171 cation gets to define the name and meaning of each subcommand. How‐
172 ever, all settings (options and configuration files) are global, and
173 can be used with all subcommands. It is up to each subcommand what
174 settings it obeys.
175 If there are any subcommands, cliapp automatically adds the help sub‐
177 command. It allows you to get the help text for a specific subommand:
178 foo help print, for example.
179
181 cliapp reads a list of configuration files at startup, on behalf of the
182 application. The name of the application is included in the name. In
183 the filenames below, the application name is progname.
184 /etc/progname.conf
186 Global configuration file.
187 /etc/progname/*.conf
189 More global configuration files. These are read in ASCII sorted
190 order.
191 ~/.progname.conf
193 Per-user configuration file.
194 ~/.config/progname/*.conf
196 More per-user configuration files. Again, ASCII sorted order.
197 In addition, the XDG Base Directory specification is followed, if the
199 Python python-xdg library is installed. In that case, environment
200 variables can be set to set additional location in which files are
201 search for. The fixed names above are always search; the XDG ones are
202 search additionally.
203 CLIAPP(5)