Skip to main content

configuror

Pypi version Coverage Status Documentation Status Ruff License Apache 2 Poetry

Your configuration management toolkit!

Why?

While using Flask, I realized that their Config class could be useful for any type of project. And the utility became more and more obvious to me when I looked at a project like Ansible. If you look the section where they define variable precedence, you will notice that there may be several locations for the configuration files, and these configuration files can be written in different formats (json, yaml..).

What if there was a simple tool that would aggregate information from different sources in the order you wanted? This is why the configuror project exists!

Installation

pip install configuror

configuror works starting from python 3.7. It has a few dependencies:

Documentation

The documentation is available at https://configuror.readthedocs.io/en/latest/.

Usage

The main class provided by configuror is Config. It is an extension of a regular dict object. There are two main ways to initialize it.

Using mapping files

from configuror import Config

mapping_files = {
    'ini': ['foo.ini', 'bar.ini'],
    'toml': ['foo.toml', 'bar.toml'],
    'python': ['/path/to/python/file']
}
config = Config(mapping_files=mapping_files, ignore_file_absence=True)

You can define a mapping of file_type: <files> where the file_type is the type of configuration file and <files> is the list of files from the lowest to the highest priority where values will be loaded.

Since dictionaries are sorted starting from python3.6, the order of the keys is important as it will become the order of importance of your files. For example in the example above, configuror will load values from files in the following order:

  • foo.ini
  • bar.ini
  • foo.toml
  • bar.toml
  • /path/to/python/file

For python files, only uppercase variables will be loaded.

You will notice the keyword argument ignore_file_absence in Config class initialization. If it is set to True, all files that does not exist will not raised FileNotFoundError. It comes in handy when you want to retrieve variables from files that may or may not potentially exist. By default this parameter is set to False.

File extension is not necessary when you use mapping files since the key is already telling which files we work with. This is not the case with the second way to initialize Config class.

Using a list of files

from configuror import Config

files = [
    'foo.yml',
    'bar.toml',
    'foobar.json',
    '/path/to/python/file'
    '.env'
]
config = Config(files=files)

In this second form of initialization, you pass a list of files you want to retrieve values from the lowest to the highest priority. File extension is mandatory here to help configuror to load the files properly.

To know file extensions supported by configuror, you can use the variable EXTENSIONS. it is a mapping file_type: <extensions> where file_type is a type of file supported like yaml and extensions is a list of recognized extensions for this type of file, e.g: [yml, yaml]

Today the file types supported are toml, yaml, dotenv, ini, python and json.

Other usages

Since Config object is a dict-like object, you can pass arbitrary keyword arguments to initialize default values.

from configuror import Config

config = Config(FOO=2, BAR='a')
print(config)  # will print {'FOO': 2, 'BAR': 'a'}

You can combine keyword arguments, mapping files and list of files at initialization. The order in which values will be initialized is the following:

  • values from keyword arguments
  • values from mapping files
  • values from list of files

You can also add values from files after initialization. There are several practical methods for this:

  • load_from_mapping_files(self, mapping_files: Dict[str, List[str]], ignore_file_absence: bool): It is in fact the method used under the hood when you initialized Config object by passing the parameter mapping_files.

  • load_from_files(self, files: List[str], ignore_file_absence: bool): It is the method used under the hood when you initialized Config objects by passing the parameter files.

  • load_from_object(self, obj: Union[Object, str]): obj can be an object or a path to a project module (with dotted notation). Only uppercase attributes of the corresponding object will be retrieved.

  • load_from_python_file(self, filename: str, ignore_file_absence: bool): Loads values from an arbitrary python file. It would be preferable if it were not a file related to your project (i.e a module). Only uppercase variables are considered.

  • load_from_json(self, filename: str, ignore_file_absence: bool): Loads values from a json file.

  • load_from_yaml(self, filename: str, ignore_file_absence: bool): Loads values from a yaml file.

  • load_from_toml(self, filenames: Union[str, List[str]], ignore_file_absence: bool): Loads values from a toml file or a list of toml files.

  • load_from_ini(self, filenames: Union[str, List], ignore_file_absence: bool, interpolation_method: str = 'basic'): Loads values from an ini file or a list of ini files. There are two interpolation methods that can be used: basic or extended like explained in the documentation.

  • load_from_dotenv(self, filename: str, ignore_file_absence: bool): Loads values from a dotenv file.

Bonus: You also have the update method of a dict to add/update values.

Metadata

Release files for configuror 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for configuror 0.3.0
File Size Uploaded Provenance Actions
configuror-0.3.0.tar.gz 13.9 kB Without provenance Details for configuror-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for configuror 0.3.0
File Interpreter ABI Platform Actions
configuror-0.3.0-py3-none-any.whl Python 3 none any Details for configuror-0.3.0-py3-none-any.whl

Total release size: 26.9 kB

Release files / configuror-0.3.0.tar.gz

Download URL configuror-0.3.0.tar.gz
Size 13.9 kB
Tags Source
SHA-256 checksum
How to use checksums
0c65a20d90bd2b0e9653251c3404b8354dbdf328c070acf4842393ce1ca4953f
BLAKE2b-256 checksum
How to use checksums
8b76c17f26b797a73e4cb241d7a233cf89656137ed770e621efefaae03173e9a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.7.1 CPython/3.8.18 Linux/6.2.0-1016-azure

Release files / configuror-0.3.0-py3-none-any.whl

Download URL configuror-0.3.0-py3-none-any.whl
Size 13.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
42bab4800fa5651947a358616504528329f2f2294e01ae63fbb5300729b5a205
BLAKE2b-256 checksum
How to use checksums
60b85d8a43babef450728892cb84505ae3738eea02180226eb848891d3ace7be
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.7.1 CPython/3.8.18 Linux/6.2.0-1016-azure

Security for configuror 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page