API documentation¶
The following API documentation was automatically generated from the source code of update-dotdee 6.0:
update_dotdee
¶
Generic modular configuration file management.
The update_dotdee
module provides two classes that implement alternative
strategies for using modular configuration files:
UpdateDotDee
implements the Python API of theupdate-dotdee
program which can be used to split a monolithic configuration file into a directory of files with configuration snippets. The monolithic configuration file is updated by concatenating the files with configuration snippets to enable support for programs that only handle a single configuration file.ConfigLoader
is a lightweight alternative forUpdateDotDee
that makes it easy for Python programs to load*.ini
configuration files from multiple locations including.d
directories. It doesn’t generate any files, it just finds and loads them.
-
class
update_dotdee.
UpdateDotDee
(**kw)[source]¶ The
UpdateDotDee
class implements the Python API of update-dotdee.To create an
UpdateDotDee
object you need to provide a value for thefilename
property. You can set the values of properties by passing keywords arguments to the initializer, for details refer to the documentation of thePropertyManager
superclass.Here’s an overview of the
UpdateDotDee
class:Superclass: PropertyManager
Public methods: execute_file()
,read_file()
,update_file()
andwrite_file()
Properties: checksum_file
,context
,directory
,filename
,force
,new_checksum
andold_checksum
When you initialize a
UpdateDotDee
object you are required to provide a value for thefilename
property. You can set the values of thechecksum_file
,context
,directory
,filename
andforce
properties by passing keyword arguments to the class initializer.-
checksum_file
[source]¶ The pathname of the file that stores the checksum of the generated file (a string).
Note
The
checksum_file
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
context
[source]¶ An execution context created by
executor.contexts
.Defaults to a
LocalContext
object.Note
The
context
property is acustom_property
. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
directory
[source]¶ The pathname of the directory with configuration snippets (a string).
Note
The
directory
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
filename
[source]¶ The pathname of the configuration file to generate (a string).
Note
The
filename
property is arequired_property
. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named filename (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.
-
force
[source]¶ True
to overwrite modified files,False
to abort (the default).Note
The
force
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
old_checksum
¶ Get the checksum stored in
checksum_file
(a string orNone
).
-
update_file
(force=None)[source]¶ Update the file with the contents of the files in the
.d
directory.Parameters: force – Override the value of force
(a boolean orNone
).Raises: RefuseToOverwrite
whenforce
isFalse
and the contents offilename
were modified.
-
read_file
(filename)[source]¶ Read a text file and provide feedback to the user.
Parameters: filename – The pathname of the file to read (a string). Returns: The contents of the file (a string).
-
-
class
update_dotdee.
ConfigLoader
(**kw)[source]¶ Wrapper for
configparser
that searches*.d
directories.The
ConfigLoader
class is a simple wrapper forconfigparser
that searches for*.ini
configuration files in system-wide and/or user-specific configuration directories:- In normal usage the caller is expected to set
program_name
and letConfigLoader
take care of details like searching for available configuration files. - Alternatively the caller can set
available_files
to bypass the usage ofprogram_name
,base_directories
andfilename_extension
to generatefilename_patterns
.
The
parser
andsection_names
properties and theget_options()
method provide access to the configuration.Here’s an overview of the
ConfigLoader
class:Superclass: PropertyManager
Public methods: get_main_pattern()
,get_modular_pattern()
,get_options()
,get_prefix()
andreport_issue()
Properties: available_files
,base_directories
,documentation
,filename_extension
,filename_patterns
,parser
,program_name
,section_names
andstrict
You can set the values of the
available_files
,base_directories
,filename_extension
,filename_patterns
,program_name
andstrict
properties by passing keyword arguments to the class initializer.-
available_files
[source]¶ The filenames of the available configuration files (a list of strings).
The value of
available_files
is computed the first time its needed by searching for available configuration files that matchfilename_patterns
usingglob()
. If you setavailable_files
this effectively disables searching for configuration files.Note
The
available_files
property is acustom_property
. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
base_directories
[source]¶ The directories that are searched for configuration files (a list of strings).
By default this list contains three entries in the following order:
Directory Description /etc
The directory for system wide configuration files on Unix like operating systems. ~
The profile directory of the current user (also available as the environment variable $HOME
).~/.config
Alternative directory for user specific configuration files (also known as $XDG_CONFIG_HOME). The order of these entries is significant because it defines the order in which configuration files are loaded by
parser
which controls how overrides work (when multiple files are loaded).In this order, user specific configuration files override system wide configuration files. The reasoning behind this is that the operator may not be in a position to change system wide configuration files, even though this is an important use case to support.
Note
The
base_directories
property is acustom_property
. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
documentation
[source]¶ Configuration documentation in reStructuredText syntax (a string).
The purpose of the
documentation
property is to provide documentation on the integration ofConfigLoader
into other projects without denormalizing the required knowledge via copy/paste.Note
The
documentation
property is acached_property
. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
filename_extension
[source]¶ The filename extension of configuration files (a string, defaults to
.ini
).Note
The
filename_extension
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
filename_patterns
[source]¶ Filename patterns to search for available configuration files (a list of strings).
The value of
filename_patterns
is computed the first time it is needed. Each of thebase_directories
generates two patterns:- A pattern generated by
get_main_pattern()
. - A pattern generated by
get_modular_pattern()
.
Here’s an example:
>>> from update_dotdee import ConfigLoader >>> loader = ConfigLoader(program_name='update-dotdee') >>> loader.filename_patterns ['/etc/update-dotdee.ini', '/etc/update-dotdee.d/*.ini', '~/.update-dotdee.ini', '~/.update-dotdee.d/*.ini', '~/.config/update-dotdee.ini', '~/.config/update-dotdee.d/*.ini']
Note
The
filename_patterns
property is acustom_property
. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.- A pattern generated by
-
parser
[source]¶ A
configparser.RawConfigParser
object withavailable_files
loaded.Note
The
parser
property is acustom_property
. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
program_name
[source]¶ The name of the application whose configuration we’re managing (a string).
The value of this property is used by
filename_patterns
to generate filenames of configuration files and directories.Note
The
program_name
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
section_names
[source]¶ The names of the available sections (a list of strings).
Note
The
section_names
property is acached_property
. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
strict
[source]¶ Whether to be strict or forgiving when something goes wrong (a boolean).
When
strict
isTrue
and something goes wrong an exception will be raised, whereas if it isFalse
(the default) a warning message will be logged but no exception is raised.Note
The
strict
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
get_main_pattern
(directory)[source]¶ Get the
glob()
pattern to find the main configuration file.Parameters: directory – The pathname of a base directory (a string). Returns: A filename pattern (a string). This method generates a pattern that matches a filename based on
program_name
with the suffixfilename_extension
in the given base directory. Here’s an example:>>> from update_dotdee import ConfigLoader >>> loader = ConfigLoader(program_name='update-dotdee') >>> [loader.get_main_pattern(d) for d in loader.base_directories] ['/etc/update-dotdee.ini', '~/.update-dotdee.ini', '~/.config/update-dotdee.ini']
-
get_modular_pattern
(directory)[source]¶ Get the
glob()
pattern to find modular configuration files.Parameters: directory – The pathname of a base directory (a string). Returns: A filename pattern (a string). This method generates a pattern that matches a directory whose name is based on
program_name
with the suffix.d
containing files matching the configuredfilename_extension
. Here’s an example:>>> from update_dotdee import ConfigLoader >>> loader = ConfigLoader(program_name='update-dotdee') >>> [loader.get_modular_pattern(d) for d in loader.base_directories] ['/etc/update-dotdee.d/*.ini', '~/.update-dotdee.d/*.ini', '~/.config/update-dotdee.d/*.ini']
-
get_options
(section_name)[source]¶ Get the options defined in a specific section.
Parameters: section_name – The name of the section (a string). Returns: A dict
with options.
- In normal usage the caller is expected to set
-
exception
update_dotdee.
RefuseToOverwrite
[source]¶ Raised when update-dotdee notices that a generated file was modified.
-
update_dotdee.
inject_documentation
(**options)[source]¶ Generate configuration documentation in reStructuredText syntax.
Parameters: options – Any keyword arguments are passed on to the ConfigLoader
initializer.This methods injects the generated documentation into the output generated by cog.
update_dotdee.cli
¶
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. |