CondConfigParser — Python library for parsing configuration files with conditionals
CondConfigParser is a Python library designed to help Python application developers to parse configuration files. Compared to well-known modules such as configparser and json, the main specificity of CondConfigParser is that it allows the end user to define conditions using boolean operators and specific sections in the configuration file that are only applied when the corresponding condition is fulfilled.
The configuration file format allows the end user to define variables of type boolean, string or list. These variables, in addition to external variables defined by the application, can be combined with Python-like syntax to define the conditions (called predicates) mentioned in the previous paragraph.
Lists in CondConfigParser may be nested at will. Variable definitions
may refer to previously-defined variables. Predicates can combine
==
, !=
and in
tests using as many logical or
, and
,
not
operators and parentheses as necessary. Such “logical
expressiveness” (and much more) could be obtained by reading
configuration files interpreted as Python code, however:
the syntax in such a case would not allow the almost-freeform options that are permitted by CondConfigParser (where the application chooses how to interpret the “options”);
when an application interprets user configuration files as Python code, it exposes its users to some risk in case a malicious user manages to sneak code of his choice into a configuration file of the victim (think about configuration file snippets copied from Internet forums…).
Regarding the second point in particular, CondConfigParser never uses
eval
or exec
to parse configuration files. It should thus be
safe to work with any configuration file, including files prepared by
malicious users.
Note
The following text is extracted from the release notes for version 1.0.5.
Home page¶
CondConfigParser’s home page is located at:
(it was on people.via.ecp.fr before April 30, 2016)
Requirements¶
This version of CondConfigParser requires Python 3.4 or later.
Installation from source also requires setuptools, but this should only
be a concern if you want to install without pip (if you have pip
,
you should already have setuptools
; and if not, installing pip
is likely to cause setuptools
to be installed at the same time).
Debian package¶
If you are a Debian user, you can install CondConfigParser using the
following lines in your /etc/apt/sources.list
:
deb http://frougon.net/debian-ffgo unstable main
deb-src http://frougon.net/debian-ffgo unstable main
The package is named python3-condconfigparser
. A package for Debian
stable is also available. If this is what you want, just replace
unstable with buster, or whatever is the codename of the current
Debian stable release, in the sources.list
lines given above.
The Release
files in this repository are signed with Florent
Rougon’s OpenPGP key . After downloading this key, be sure to verify
that this is the same key as served by Github over https (you’ll need to add a
trailing newline to the latter to ensure byte-for-byte equality). Once
you’ve verified that this is the right key, you can add it to your
apt
keyring using apt-key add /path/to/file
, as root. This
allows apt
to authenticate the packages. If you don’t do this, the
installation should still be possible but with warnings and, of course,
reduced security.
Quick installation instructions¶
This section describes installation from source. If you want to install from a Debian package instead, see above.
If you have a working pip setup, you should be able to install CondConfigParser with:
pip install CondConfigParser
(pip install condconfigparser
also works)
When doing so, make sure that your pip
executable runs with the
Python 3 installation you want to install CondConfigParser for.
For more detailed instructions, you can read the INSTALL.txt
file
from a release tarball. You may also want to consult the “Installing
Python Modules” chapter of the Python documentation and the pip
documentation.
Download¶
Typical installations with pip automatically download the latest release from PyPI. However, in some cases, you may want to download a wheel package, tarball or zip file yourself in order to install it later, possibly on a different machine. You may get such files from PyPI or from Florent Rougon’s home page (the former should normally be favored over the latter, as it is served over https).
Git repository¶
CondConfigParser is maintained in a Git repository that can be cloned with:
git clone https://github.com/frougon/CondConfigParser
Documentation¶
The CondConfigParser Manual is written in reStructuredText format for the Sphinx documentation generator. The HTML documentation for the latest version of CondConfigParser as rendered by Sphinx is available at:
The sources for the CondConfigParser Manual are located in the doc
top-level directory of the CondConfigParser distribution, but the
documentation build process pulls many parts from the source code,
mainly docstrings.
To generate the documentation yourself from CondConfigParser’s code and
the reStructuredText sources in the doc
directory, first make
sure you have Python 3.x, Sphinx and Make installed. Then, go
to the doc
directory and type, for instance:
make html
You will find the output in the _build/html
subdirectory of doc
.
Sphinx can build the documentation in many other formats. For
instance, if you have LaTeX installed, you can generate the
CondConfigParser Manual in PDF format with:
make latexpdf
You can run make
from the doc
directory to see a list of the
available formats. Run make clean
to clean up after the
documentation build process.
Note
The Makefile
uses a Python script (prepare-basic-pkg-info.py
)
to generate basic-pkg-info.rst
from the top-level README.rst
file. By default, this script is interpreted by the python3
executable. If you want to explicitely choose the interpreter to use,
you can set the PYTHON
Makefile variable like this:
make PYTHON=python3.4 html
Note that this only affects running of prepare-basic-pkg-info.py
;
the Python interpreter used by Sphinx in other places of the
Makefile
is determined by the sphinx-build executable that
should be part of your Sphinx installation.
For those who have installed Sphinx but not Make, it is still possible to build the documentation with two commands such as:
python3 prepare-basic-pkg-info.py ../README.rst basic-pkg-info.rst
sphinx-build -b html -d _build/doctrees . _build/html
These commands must be run from the doc
directory. Please refer to
sphinx-build for more details.
Running the automated test suite¶
If you want to run the automated test suite from an unpacked release tarball (or Git checkout), go to the root directory of that CondConfigParser distribution (the directory containing
README.rst
and thecondconfigparser
directory) and run:python3 -m unittest
(assuming of course that you want to run the tests with an executable called
python3
).You may want to add the
-v
option at the end of the command in order to run the test suite in verbose mode.On the other hand, if you have already installed CondConfigParser for a given Python installation and you want to test the installed package, go to the directory containing the installed package and run:
python3 -m unittest discover -t ..
With a POSIX-style shell, you can combine both operations with the following command (that does not change your current directory):
( cd base_dir/lib/python3.4/site-packages/condconfigparser && \ python3 -m unittest discover -t .. )
This command is given for a Python 3.4 installation:
rooted at
base_dir
(typically/usr
,/usr/local
,/opt/pythonX.Y
[on Unix-like systems] or a directory containing a Python venv or virtualenv)using the
python3
executable.
You may want to add the
-v
option after thediscover
argument in order to run the test suite in verbose mode.
A successful run of the test suite looks like this:
% python3 -m unittest
.......
----------------------------------------------------------------------
Ran 7 tests in 0.052s
OK
% echo $?
0
%
In the above output, each dot represents a successful test. The
echo $?
command shows the zero exit status, indicating success for
all tests. In case of a failure, the exit status is non-zero.
It is also possible to ask setuptools to run the test suite (by default in verbose mode, cf. the corresponding documentation). For instance:
python3 setup.py test