Skip to main content

Generic modular configuration file manager

Project description

https://travis-ci.org/xolox/python-update-dotdee.svg?branch=master https://coveralls.io/repos/xolox/python-update-dotdee/badge.svg?branch=master

The update-dotdee program makes it easy to manage configuration files with modular contents in the style of Debian and dotdee. The program takes the pathname of a configuration file and updates that file based on the contents of the files in the directory with the same name as the file but ending in .d. It’s currently tested on cPython 2.7, 3.5+ and PyPy (2.7).

Installation

The update-dotdee package is available on PyPI which means installation should be as simple as:

$ pip install update-dotdee

There’s actually a multitude of ways to install Python packages (e.g. the per user site-packages directory, virtual environments or just installing system wide) and I have no intention of getting into that discussion here, so if this intimidates you then read up on your options before returning to these instructions ;-).

Usage

There are two ways to use the update-dotdee package: As the command line program update-dotdee and as a Python API. For details about the Python API please refer to the API documentation available on Read the Docs. The command line interface is described below.

Usage: update-dotdee FILENAME

Generate a (configuration) file based on the contents of the files in the directory with the same name as FILENAME but ending in ‘.d’.

If FILENAME exists but the corresponding directory does not exist yet, the directory is created and FILENAME is moved into the directory so that its existing contents are preserved.

Supported options:

Option

Description

-f, --force

Update FILENAME even if it contains local modifications, instead of aborting with an error message.

-u, --use-sudo

Enable the use of “sudo” to update configuration files that are not readable and/or writable for the current user (or the user logged in to a remote system over SSH).

-r, --remote-host=SSH_ALIAS

Operate on a remote system instead of the local system. The SSH_ALIAS argument gives the SSH alias of the remote host.

-v, --verbose

Increase logging verbosity (can be repeated).

-q, --quiet

Decrease logging verbosity (can be repeated).

-h, --help

Show this message and exit.

Example

The /etc/hosts file is a simple example of a configuration file that can be managed using update-dotdee. Individual files in the /etc/hosts.d directory contain snippets that are added to the configuration file on each run. For example:

peter@macbook> sudo update-dotdee /etc/hosts
2013-07-06 19:32:03 macbook INFO Reading file: /etc/hosts.d/1-local
2013-07-06 19:32:03 macbook INFO Reading file: /etc/hosts.d/2-work
2013-07-06 19:32:03 macbook INFO Reading file: /etc/hosts.d/3-ipv6
2013-07-06 20:59:24 macbook INFO Checking for local changes to /etc/hosts
2013-07-06 19:32:03 macbook INFO Writing file: /etc/hosts

How it works

Some notes about how update-dotdee works:

  • If the given file exists but the corresponding directory does not exist yet, the directory is created and the file is moved into the directory (and renamed to local) so that its existing contents are preserved.

  • If the generated file has been modified since the last run, update-dotdee will refuse to overwrite its contents (unless you use the -f or --force option).

  • The files in the .d directory are concatenated in the natural sorting order of the filenames (as implemented by the naturalsort package).

  • Executable files in the .d directory are executed and their standard output is incorporated into the generated contents (since version 4.0).

Use cases

Here are some example use cases for update-dotdee:

SSH client configuration

The update-dotdee program was created in 2013 to provide modular SSH client configurations. It was used to generate the ~/.ssh/config file from the contents of the files in the ~/.ssh/config.d directory. This functionality was needed because I developed an SSH client configuration generator based on a database of server metadata and I was looking for a way to update the user’s ~/.ssh/config without trashing the existing (carefully handcrafted) contents.

System wide configuration files

Linux system configuration files like /etc/crypttab, /etc/fstab and /etc/hosts lack modularity and manipulating them using command line tools like awk and sed can be fragile and/or become unwieldy :-). However if you can get your configuration sources (for example Ansible playbooks, Debian packages and manual configuration) to agree on the use of update-dotdee then you have an elegant, robust and predictable alternative.

Read only alternative

Sometimes the use of update-dotdee or a similar mechanism is the only way to get multiple configuration sources to cooperate, but it is a bit of a heavyweight solution. For the Python packages that I’ve published I wanted a more lightweight alternative that simply searches for and loads *.ini configuration files. This is why ConfigLoader was added in release 5.0.

Contact

The latest version of update-dotdee is available on PyPI and GitHub. The documentation is hosted on Read the Docs and includes a changelog. For bug reports please create an issue on GitHub. If you have questions, suggestions, etc. feel free to send me an e-mail at peter@peterodding.com.

License

This software is licensed under the MIT license.

© 2020 Peter Odding.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

update-dotdee-6.0.tar.gz (19.6 kB view details)

Uploaded Source

Built Distribution

update_dotdee-6.0-py2.py3-none-any.whl (14.7 kB view details)

Uploaded Python 2Python 3

File details

Details for the file update-dotdee-6.0.tar.gz.

File metadata

  • Download URL: update-dotdee-6.0.tar.gz
  • Upload date:
  • Size: 19.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.1.3 requests-toolbelt/0.9.1 tqdm/4.46.0 CPython/3.6.9

File hashes

Hashes for update-dotdee-6.0.tar.gz
Algorithm Hash digest
SHA256 5897da85cc2115dc894aa27c986274b2930c4b56068cd44634fb543eafb88b41
MD5 7ce5b5d151e150e6b629e03d8890ae0b
BLAKE2b-256 6dd0c41d5eb544c5091b797d881b3c6f77220eb3d1498ce37713c1efa1c5cb8d

See more details on using hashes here.

File details

Details for the file update_dotdee-6.0-py2.py3-none-any.whl.

File metadata

  • Download URL: update_dotdee-6.0-py2.py3-none-any.whl
  • Upload date:
  • Size: 14.7 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.1.3 requests-toolbelt/0.9.1 tqdm/4.46.0 CPython/3.6.9

File hashes

Hashes for update_dotdee-6.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 0e18e14ba9fdc21213b093ce75c58613391d2ff7985aa5a9f0051bc9186f125e
MD5 ce014e9144b78d53b0e0c345b5701c30
BLAKE2b-256 2ab4a656d869b1c5c350ef503bc9c51a8fad0090f563853cf8a7d64e933b64fe

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page