| Name | configapi JSON |
| Version |
0.0.7
JSON |
| download |
| home_page | None |
| Summary | A dict-style API for TOML-based config files. |
| upload_time | 2025-01-20 01:30:59 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License |
| keywords |
configs
toml
dict
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Config API
## Installation
> pip install configapi
## Basic Usage
Create a dictionary-like object that merges multiple TOML files.
``` {.python}
>>> from configapi import Config
>>> import somepackage.config
>>> configs = Config(sources={
... 'default': (somepackage.config, 'defaults.toml'), # Read from package resource.
... 'user': Path.home() / 'user-config.toml', # Read from textfile.
... })
>>> configs.load()
```
There are 3 kind of sources supported:
- Files: Specified as a path to a TOML file (pathlib.Path or str).
- Package file: Specified as a tuple with a package and a path to a file in the package.
- In-memory: Specified as a dictionary.
The configs object provides a dictionary-like interface to the
merged configuration, and to each source separately.
If multiple sources provide the same key, the value from the source
added last to the config container is used.
``` {.python}
>>> configs['project.authors']
['me']
>>> configs.default['project.authors']
['Bob', 'Alice']
>>> configs.source('project.authors')
'user'
```
Iterate over all entries. Optionally, the source can be included.
``` {.python}
>>> for (key, value, source) in configs.items(source=True):
... print(f'{key}: {value} (from {source})')
project.authors: ['me'] (from user)
project.name: Example Project (from default)
```
Modifications must be done on the separate source dictionaries
(also called scopes). The changes are not saved automatically.
``` {.python}
>>> configs.user['project.name'] = 'My Project'
>>> configs.user.save()
>>> del configs.default['project.name']
>>> value, source, scope = configs.get('project.name', source=True, scope=True)
>>> print(f'{value} (from {source})')
My Project (from user)
>>> assert scope is configs.user
```
## Advanced Usage
The config files may be versioned, and upgrade patches applied automatically.
Specify the current version, or let it be inferred from the patches.
``` {.python}
>>> configs = Config(target_version='1.5.0')
```
Sources may be specified more explicitly for finer control.
The autosave feature ensures that changes applied by patches.
during loading are immediately saved back to the source.
``` {.python}
>>> local = FileConfigSource(Path.cwd() / 'local-config.toml', read_only=False)
>>> configs.add_source('local', local, autosave_updates=True)
>>> @configs.patch('0.2.1')
>>> def patch_0_2_1(cfg):
... if 'project.author' in cfg:
... cfg['project.authors'] = [cfg['project.author']]
... del cfg['project.author']
... return cfg
>>> configs.local.load()
```
If needed, individual sources may be (re-)loaded separately.
Raw data
{
"_id": null,
"home_page": null,
"name": "configapi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Patrick Schaffner <patrick.schaffner@protonmail.ch>",
"keywords": "configs, toml, dict",
"author": null,
"author_email": "Patrick Schaffner <patrick.schaffner@protonmail.ch>",
"download_url": "https://files.pythonhosted.org/packages/f3/8c/f9844b828d2e17cdcd7a96fd33afd1b9f88901a91c7e9e940a793f399859/configapi-0.0.7.tar.gz",
"platform": null,
"description": "# Config API\n\n## Installation\n\n> pip install configapi\n\n## Basic Usage\n\nCreate a dictionary-like object that merges multiple TOML files.\n``` {.python}\n>>> from configapi import Config\n>>> import somepackage.config\n\n>>> configs = Config(sources={\n... 'default': (somepackage.config, 'defaults.toml'), # Read from package resource.\n... 'user': Path.home() / 'user-config.toml', # Read from textfile.\n... })\n>>> configs.load()\n```\nThere are 3 kind of sources supported:\n- Files: Specified as a path to a TOML file (pathlib.Path or str).\n- Package file: Specified as a tuple with a package and a path to a file in the package.\n- In-memory: Specified as a dictionary.\n\nThe configs object provides a dictionary-like interface to the\nmerged configuration, and to each source separately.\nIf multiple sources provide the same key, the value from the source\nadded last to the config container is used.\n``` {.python}\n>>> configs['project.authors']\n['me']\n>>> configs.default['project.authors']\n['Bob', 'Alice']\n>>> configs.source('project.authors')\n'user'\n```\n\nIterate over all entries. Optionally, the source can be included.\n``` {.python}\n>>> for (key, value, source) in configs.items(source=True):\n... print(f'{key}: {value} (from {source})')\nproject.authors: ['me'] (from user)\nproject.name: Example Project (from default)\n\n```\n\nModifications must be done on the separate source dictionaries\n(also called scopes). The changes are not saved automatically.\n``` {.python}\n>>> configs.user['project.name'] = 'My Project'\n>>> configs.user.save()\n>>> del configs.default['project.name']\n>>> value, source, scope = configs.get('project.name', source=True, scope=True)\n>>> print(f'{value} (from {source})')\nMy Project (from user)\n>>> assert scope is configs.user\n```\n\n## Advanced Usage\n\nThe config files may be versioned, and upgrade patches applied automatically.\nSpecify the current version, or let it be inferred from the patches.\n``` {.python}\n>>> configs = Config(target_version='1.5.0')\n```\n\nSources may be specified more explicitly for finer control.\nThe autosave feature ensures that changes applied by patches.\nduring loading are immediately saved back to the source.\n``` {.python}\n>>> local = FileConfigSource(Path.cwd() / 'local-config.toml', read_only=False)\n>>> configs.add_source('local', local, autosave_updates=True)\n\n>>> @configs.patch('0.2.1')\n>>> def patch_0_2_1(cfg):\n... if 'project.author' in cfg:\n... cfg['project.authors'] = [cfg['project.author']]\n... del cfg['project.author']\n... return cfg\n\n>>> configs.local.load()\n```\nIf needed, individual sources may be (re-)loaded separately.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A dict-style API for TOML-based config files.",
"version": "0.0.7",
"project_urls": {
"Source": "https://github.com/PatrickSchaffner/ConfigAPI"
},
"split_keywords": [
"configs",
" toml",
" dict"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "450f529939f672787ecc262909ce41570fa6e63791cb8c39b80e2ff89a0cbd01",
"md5": "a74d3c152947e49a5da2ac5e56ceb011",
"sha256": "6754c290f2c505bc50a5782bc49194521c79b3c0c3e36927d2ce21da7a9ce4fe"
},
"downloads": -1,
"filename": "configapi-0.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a74d3c152947e49a5da2ac5e56ceb011",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7554,
"upload_time": "2025-01-20T01:30:57",
"upload_time_iso_8601": "2025-01-20T01:30:57.149975Z",
"url": "https://files.pythonhosted.org/packages/45/0f/529939f672787ecc262909ce41570fa6e63791cb8c39b80e2ff89a0cbd01/configapi-0.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f38cf9844b828d2e17cdcd7a96fd33afd1b9f88901a91c7e9e940a793f399859",
"md5": "6d551001ed8bfd8fae19981323729587",
"sha256": "c1fbb7811ca715e73b735027570fb44168e21d90386e253a8a578b00cd992319"
},
"downloads": -1,
"filename": "configapi-0.0.7.tar.gz",
"has_sig": false,
"md5_digest": "6d551001ed8bfd8fae19981323729587",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11488,
"upload_time": "2025-01-20T01:30:59",
"upload_time_iso_8601": "2025-01-20T01:30:59.017258Z",
"url": "https://files.pythonhosted.org/packages/f3/8c/f9844b828d2e17cdcd7a96fd33afd1b9f88901a91c7e9e940a793f399859/configapi-0.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-20 01:30:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PatrickSchaffner",
"github_project": "ConfigAPI",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "configapi"
}
