CatenaConf
Introduction
CatenaConf is a lightweight Python library designed for managing and operating configurations. It extends the Python dictionary type to manage configurations using key-value pairs and provides flexible operation functionalities.
Features
- Lightweight: The code size is small and no third-party dependencies need to be installed (if you need to create a configuration from a Pydantic model or a yaml file, you need to install the corresponding dependencies).
- Dictionary based: Use Python dictionaries to create and manage configurations.
- Attribute access: Access and modify configuration values through attributes, which is convenient and intuitive.
- Flexible update mechanism: Provides flexible update function and supports merging dictionaries.
- Reference resolution: Supports referencing other configuration values in configuration values and being able to resolve these references.
Installation
Install using pip:
pip install catenaconf
Usage
Creating Configuration
Create from dictionary
Catenaconf.create(config)
Description: Create a KvConfig instance (a built-in type of the library) from a dictionary.
Parameters:
config (dict): A dictionary containing the configuration data.
Returns:
- Returns a
KvConfigobject created from the dictionary.
Usage:
from catenaconf import Catenaconf
config = {
"database": {
"host": "localhost",
"port": 3306
}
}
cfg = Catenaconf.create(config)
Load from file
Catenaconf.load(file)
Description: Load a KvConfig instance from a file. Supports JSON, YAML, and XML formats.
Parameters:
file (str | pathlib.Path): Path to the configuration file.
Returns:
- Returns a
KvConfigobject created from the loaded data.
Usage:
cfg = Catenaconf.load("config.json")
Create from Pydantic Model
Catenaconf.structured(model)
Description: Creates a KvConfig instance from a Pydantic model.
Parameters:
model (pydantic.BaseModel): A Pydantic model object to construct the configuration.
Returns:
- A
KvConfigobject containing the structured configuration.
Usage:
from pydantic import BaseModel
class MyModel(BaseModel):
field: str
cfg = Catenaconf.structured(MyModel(field="value"))
Accessing Configuration
After creating a configuration, you can access configuration values using attribute access:
from catenaconf import Catenaconf
config = {
"database": {
"host": "localhost",
"port": 3306
}
}
cfg = Catenaconf.create(config)
# Accessing via attribute
host = cfg.database.host
port = cfg.database.port
print(host) # Output: localhost
print(port) # Output: 3306
Selecting Configuration Values
Catenaconf.select(cfg, key, *, default="NOT FOUND", throw_on_resolution_failure=True, throw_on_missing=False)
Description: Selects a value from the configuration by key, with options for default values and error handling.
Parameters:
cfg (KvConfig): The configuration instance to select from.key (str): The key to locate within the configuration.default (Any, optional): The default value to return if the key is not found. Defaults to"NOT FOUND".throw_on_resolution_failure (bool, optional): Whether to raise an error if key resolution fails. Defaults toTrue.throw_on_missing (bool, optional): Whether to raise an error for missing keys. Defaults toFalse.
Returns:
- The selected value, or the default value if the key is not found.
Usage:
value = Catenaconf.select(cfg, "database.user", default=None, throw_on_resolution_failure=False)
Updating Configuration
Catenaconf.update(cfg, key, value=None, *, merge=True)
Description: Updates the value of a specified key in the configuration.
Parameters:
cfg (KvConfig): The configuration instance to update.key (str): The location of the value to be updated, specified as a dotted string.value (Any, optional): The new value to set.merge (bool, optional): Whether to merge dictionaries. Defaults toTrue.
Usage:
Catenaconf.update(cfg, "database.user", "root")
Catenaconf.update(cfg, "database", {"root": "root"})
Catenaconf.update(cfg, "database", {"root": "root"}, merge=True)
Notes:
-
If
merge=True, existing dictionaries are merged with the new value. -
If
merge=False, the new value replaces the existing one.
Merging Configurations
Catenaconf.merge(*configs)
Description: Merges multiple configurations into one.
Parameters:
*configs (KvConfig or dict): The configurations to merge, passed as positional arguments.
Returns:
- A merged
KvConfiginstance.
Usage:
config1 = {"database": {"host": "localhost"}}
config2 = {"database": {"port": 3306}}
merged_cfg = Catenaconf.merge(config1, config2)
References and Resolving References
Catenaconf.resolve(cfg)
Description: Resolve all references in the configuration. The reference is defined in the @{} format.
-
@{a.b.c}: Reference keys in configuration. whereais the top-level key of the configuration,bis the sub-key ofa, andcis the sub-key ofb. -
@{a.b.1}: Reference elements in the list. whereais the top-level key of the configuration,bis the sub-key ofa, and1is the index ofb. -
@{env:VAR_NAME}: Reference environment variables.
Parameter:
cfg (KvConfig): Contains the referenced configuration instance.
Usage:
config = {
"config": {
"database": {
"host": "localhost",
"port": 5432
},
"connection": "Host: @{config.database.host}, Port: @{config.database.port}"
},
"app":[
"11",
"22",
"33",
"@{env:MY_VARIABLE}"
],
"list":[
{"a": 1, "b": "@{app.1}"},
{"ref": "@{config.database.host}"}
]
}
cfg = Catenaconf.create(config)
Catenaconf.resolve(cfg)
Notes:
- Resolves references by replacing placeholders with their actual values.
Converting to Dictionary
Catenaconf.to_container(cfg, resolve=True)
Description: Converts a KvConfig instance into a standard dictionary.
Parameters:
cfg (KvConfig): The configuration instance to convert.resolve (bool, optional): Whether to resolve references in the dictionary. Defaults toTrue.
Returns:
- A standard dictionary containing the configuration data.
Usage:
dict_config = Catenaconf.to_container(cfg, resolve=True)
dict_config = Catenaconf.to_container(cfg, resolve=False)
Notes:
- When
resolve=True, all references in the configuration are resolved. - When
resolve=False, references remain unresolved.
Metadata
Release files for catenaconf 0.1.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| catenaconf-0.1.8.tar.gz | 17.4 kB | Without provenance | Details for catenaconf-0.1.8.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| catenaconf-0.1.8-py3-none-any.whl | Python 3 | none | any | Details for catenaconf-0.1.8-py3-none-any.whl |
Total release size: 35.9 kB
Release files / catenaconf-0.1.8.tar.gz
| Download URL | catenaconf-0.1.8.tar.gz |
|---|---|
| Size | 17.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
15cb33c663eee0c7e6509aa0554844595f3b1e967d3af8a6eb4eff240bf59dcc
|
|
BLAKE2b-256 checksum How to use checksums |
999330be9a84479cf8ea3dab1dd8427e090c3deed74ee90c7539ca71f462c0c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.1 CPython/3.10.14
|
Release files / catenaconf-0.1.8-py3-none-any.whl
| Download URL | catenaconf-0.1.8-py3-none-any.whl |
|---|---|
| Size | 18.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
edf3893c698dbbd5e9a4f8d5560fba984a63980bd9787212d751b393a9a7ddd3
|
|
BLAKE2b-256 checksum How to use checksums |
baaf72d0d520345c3b35e67025b937ef1dc3605b6f105990ea1bc8d353295e2d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.1 CPython/3.10.14
|
Security for catenaconf 0.1.8
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.