# Overview
Confspec is a configuration loading library for Python that supports smart environment variable interpolation at runtime.
It provides a simple way to load configuration from common formats like `YAML`, `JSON`, and `TOML`, while being easy
to add support for any additional formats. Out-of-the-box, confspec also supports parsing application configuration
into Pydantic models, or Msgspec Structs.
The environment variable interpolation syntax allows you to keep your defaults in the configuration file, while
still being able to override them from a deployment environment.
Confspec also supports environment-based configuration overrides, allowing you to maintain separate configuration
files for different environments (akin to spring's application.properties) without duplicating your entire
configuration.
## Installation
Confspec is available on PyPI and can be installed using your package manager of choice.
```bash
pip install confspec
```
```bash
uv add confspec
```
## Usage
`config.toml`
```toml
[server]
port = "${PORT:8080}"
debug = "${DEBUG:false}"
[database]
url = "postgres://${DB_URL:postgres:postgres@localhost:5432}/postgres"
[logging]
level = "${LOG_LEVEL~:INFO}"
handlers = "${LOG_HANDLERS[,]:console,file}"
[features]
enabled = "${FEATURE_FLAGS[,]:auth,metrics,caching}"
```
The above configuration file can easily be loaded, with any environment substitution happening automatically.
```python
>>> import confspec
>>> confspec.load("config.toml")
{
"server": {
"port": "8080",
"debug": "false"
},
"database": {
"url": "postgres://postgres:postgres@localhost:5432/postgres"
},
"logging": {
"level": "INFO",
"handlers": ["console", "file"]
},
"features": {
"enabled": ["auth", "metrics", "caching"]
}
}
```
Or if you wanted it to be loaded into a msgspec Struct object. Note that msgspec will coerce some fields
into the requested types automatically, unless you pass `strict=True`.
```python
>>> import confspec
>>> import msgspec
>>> class Server(msgspec.Struct):
... port: int
... debug: bool
>>> class Database(msgspec.Struct):
... url: str
>>> class Logging(msgspec.Struct):
... level: str
... handlers: list[str]
>>> class Features(msgspec.Struct):
... enabled: list[str]
>>> class Config(msgspec.Struct):
... server: Server
... database: Database
... logging: Logging
... features: Features
>>> confspec.load("config.toml", cls=Config)
Config(
server=Server(port=8080, debug=False),
database=Database(url='postgres://postgres:postgres@localhost:5432/postgres'),
logging=Logging(level='INFO', handlers=['console', 'file']),
features=Features(enabled=['auth', 'metrics', 'caching'])
)
```
## Interpolation Syntax
- `${VAR}`
- replaced with the value of the `VAR` environment variable
- if `VAR` is unset during interpolation, a `KeyError` will be raised
- `${VAR:default}`
- replaced with the value of the `VAR` environment variable
- if `VAR` is unset during interpolation, the default value will be used instead
- `${VAR[,]}`
- performs list expansion on the value of the `VAR` environment variable, splitting on the delimiter (in this case `,`)
- the delimiter can be any combination of one or more characters, excluding `]` and `}`
- this operator cannot be applied to patterns within a longer string
- `${VAR~}`
- strips whitespace from the value of the `VAR` environment variable (or the default if one is specified)
- if combined with list expansion, each individual element will have its whitespace stripped
- `${VAR?}`
- replaced with the value of the `VAR` environment variable
- if `VAR` is unset during interpolation, it will be replaced with Python's `None` instead
- this operator cannot be applied to patterns within a longer string
Most of these interpolation rules can be combined, except for a default value and the "None as default" flag.
For example:
- `${VAR[,]~:default}` - valid
- `${VAR[,]~?}` - valid
- `${VAR[,]~?:default}` - invalid
> [!NOTE]
> The order that the flags are written is important, as the interpolation syntax is parsed using regex. You should
> always specify the flags in the same order as the valid expressions shown above.
## Environment-specific Configurations
When an environment is specified, Confspec automatically looks for an additional file matching the base
configuration name with the environment suffix and merges it with the base configuration.
For example:
```bash
config.yaml
config.prod.yaml
config.dev.yaml
```
You can activate an additional environment in two ways:
```python
import confspec
# Explicitly pass the environment
config = confspec.load("config.yaml", env="prod")
# Or use the CONFSPEC_ENV environment variable
# export CONFSPEC_ENV=prod
config = confspec.load("config.yaml")
```
In both cases, config.prod.yaml will be loaded and merged with config.yaml, allowing you to override specific values
for that environment while keeping shared defaults in one place. Any values specified in the environment-specific
config file will override those specified within the root configuration file.
Environment variable interpolations are performed after the configurations have been merged.
## Issues
If you find any bugs, issues, or unexpected behaviour while using the library, you should open an issue with
details of the problem and how to reproduce if possible. Please also open an issue for any new features
you would like to see added.
## Contributing
Pull requests are welcome. For major changes, please open an issue/discussion first to discuss what you
would like to change.
Please try to ensure that documentation is updated if you add any features accessible through the public API.
If you use this library and like it, feel free to sign up to GitHub and star the project, it is greatly appreciated
and lets me know that I'm going in the right direction!
## Links
- **License:** [MIT](https://choosealicense.com/licenses/mit/)
- **Repository:** [GitHub](https://github.com/tandemdude/confspec)
Raw data
{
"_id": null,
"home_page": null,
"name": "confspec",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.15,>=3.11.0",
"maintainer_email": null,
"keywords": "configuration, config, settings, environment, env, yaml, toml, json, schema, config-file, environment-variables, structured-config, config-loader, environment-substitution",
"author": null,
"author_email": "tandemdude <tandemdude1@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d9/62/d3a900cff5b9eefa4f1716e45c6358302713ce263eff637455fba97a8378/confspec-0.0.5.tar.gz",
"platform": null,
"description": "# Overview\nConfspec is a configuration loading library for Python that supports smart environment variable interpolation at runtime.\n\nIt provides a simple way to load configuration from common formats like `YAML`, `JSON`, and `TOML`, while being easy\nto add support for any additional formats. Out-of-the-box, confspec also supports parsing application configuration\ninto Pydantic models, or Msgspec Structs.\n\nThe environment variable interpolation syntax allows you to keep your defaults in the configuration file, while\nstill being able to override them from a deployment environment.\n\nConfspec also supports environment-based configuration overrides, allowing you to maintain separate configuration\nfiles for different environments (akin to spring's application.properties) without duplicating your entire\nconfiguration.\n\n## Installation\nConfspec is available on PyPI and can be installed using your package manager of choice.\n\n```bash\npip install confspec\n```\n```bash\nuv add confspec\n```\n\n## Usage\n`config.toml`\n```toml\n[server]\nport = \"${PORT:8080}\"\ndebug = \"${DEBUG:false}\"\n\n[database]\nurl = \"postgres://${DB_URL:postgres:postgres@localhost:5432}/postgres\"\n\n[logging]\nlevel = \"${LOG_LEVEL~:INFO}\"\nhandlers = \"${LOG_HANDLERS[,]:console,file}\"\n\n[features]\nenabled = \"${FEATURE_FLAGS[,]:auth,metrics,caching}\"\n```\n\nThe above configuration file can easily be loaded, with any environment substitution happening automatically.\n```python\n>>> import confspec\n>>> confspec.load(\"config.toml\")\n{\n \"server\": {\n \"port\": \"8080\",\n \"debug\": \"false\"\n },\n \"database\": {\n \"url\": \"postgres://postgres:postgres@localhost:5432/postgres\"\n },\n \"logging\": {\n \"level\": \"INFO\",\n \"handlers\": [\"console\", \"file\"]\n },\n \"features\": {\n \"enabled\": [\"auth\", \"metrics\", \"caching\"]\n }\n}\n```\n\nOr if you wanted it to be loaded into a msgspec Struct object. Note that msgspec will coerce some fields\ninto the requested types automatically, unless you pass `strict=True`.\n```python\n>>> import confspec\n>>> import msgspec\n\n>>> class Server(msgspec.Struct):\n... port: int\n... debug: bool\n\n>>> class Database(msgspec.Struct):\n... url: str\n\n>>> class Logging(msgspec.Struct):\n... level: str\n... handlers: list[str]\n\n>>> class Features(msgspec.Struct):\n... enabled: list[str]\n\n>>> class Config(msgspec.Struct):\n... server: Server\n... database: Database\n... logging: Logging\n... features: Features\n\n>>> confspec.load(\"config.toml\", cls=Config)\nConfig(\n server=Server(port=8080, debug=False),\n database=Database(url='postgres://postgres:postgres@localhost:5432/postgres'),\n logging=Logging(level='INFO', handlers=['console', 'file']),\n features=Features(enabled=['auth', 'metrics', 'caching'])\n)\n```\n\n## Interpolation Syntax\n\n- `${VAR}`\n - replaced with the value of the `VAR` environment variable\n - if `VAR` is unset during interpolation, a `KeyError` will be raised\n- `${VAR:default}`\n - replaced with the value of the `VAR` environment variable\n - if `VAR` is unset during interpolation, the default value will be used instead\n- `${VAR[,]}`\n - performs list expansion on the value of the `VAR` environment variable, splitting on the delimiter (in this case `,`)\n - the delimiter can be any combination of one or more characters, excluding `]` and `}`\n - this operator cannot be applied to patterns within a longer string\n- `${VAR~}`\n - strips whitespace from the value of the `VAR` environment variable (or the default if one is specified)\n - if combined with list expansion, each individual element will have its whitespace stripped\n- `${VAR?}`\n - replaced with the value of the `VAR` environment variable\n - if `VAR` is unset during interpolation, it will be replaced with Python's `None` instead\n - this operator cannot be applied to patterns within a longer string\n\nMost of these interpolation rules can be combined, except for a default value and the \"None as default\" flag.\n\nFor example:\n\n- `${VAR[,]~:default}` - valid\n- `${VAR[,]~?}` - valid\n- `${VAR[,]~?:default}` - invalid\n\n> [!NOTE]\n> The order that the flags are written is important, as the interpolation syntax is parsed using regex. You should\n> always specify the flags in the same order as the valid expressions shown above.\n\n## Environment-specific Configurations\n\nWhen an environment is specified, Confspec automatically looks for an additional file matching the base\nconfiguration name with the environment suffix and merges it with the base configuration.\n\nFor example:\n```bash\nconfig.yaml\nconfig.prod.yaml\nconfig.dev.yaml\n```\n\nYou can activate an additional environment in two ways:\n```python\nimport confspec\n\n# Explicitly pass the environment\nconfig = confspec.load(\"config.yaml\", env=\"prod\")\n\n# Or use the CONFSPEC_ENV environment variable\n# export CONFSPEC_ENV=prod\nconfig = confspec.load(\"config.yaml\")\n```\n\nIn both cases, config.prod.yaml will be loaded and merged with config.yaml, allowing you to override specific values\nfor that environment while keeping shared defaults in one place. Any values specified in the environment-specific\nconfig file will override those specified within the root configuration file.\n\nEnvironment variable interpolations are performed after the configurations have been merged.\n\n## Issues\nIf you find any bugs, issues, or unexpected behaviour while using the library, you should open an issue with\ndetails of the problem and how to reproduce if possible. Please also open an issue for any new features\nyou would like to see added.\n\n## Contributing\nPull requests are welcome. For major changes, please open an issue/discussion first to discuss what you\nwould like to change.\n\nPlease try to ensure that documentation is updated if you add any features accessible through the public API.\n\nIf you use this library and like it, feel free to sign up to GitHub and star the project, it is greatly appreciated\nand lets me know that I'm going in the right direction!\n\n## Links\n- **License:** [MIT](https://choosealicense.com/licenses/mit/)\n- **Repository:** [GitHub](https://github.com/tandemdude/confspec)\n",
"bugtrack_url": null,
"license": null,
"summary": "Parse YAML, JSON, and TOML into Python objects with smart environment variable interpolation.",
"version": "0.0.5",
"project_urls": {
"Homepage": "https://github.com/tandemdude/confspec",
"Repository": "https://github.com/tandemdude/confspec"
},
"split_keywords": [
"configuration",
" config",
" settings",
" environment",
" env",
" yaml",
" toml",
" json",
" schema",
" config-file",
" environment-variables",
" structured-config",
" config-loader",
" environment-substitution"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "19fbb622edac3422f448975f2eb4915ef8d87eba2cc501d18c825713eeca4495",
"md5": "e4adcda7f9093fad43c3af6495de349a",
"sha256": "042dcbc368173163d2c1bbb2a9f58ba4d17c98fd0c6e8e97e6a7972faf8ef57f"
},
"downloads": -1,
"filename": "confspec-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4adcda7f9093fad43c3af6495de349a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.15,>=3.11.0",
"size": 17213,
"upload_time": "2025-10-20T14:39:51",
"upload_time_iso_8601": "2025-10-20T14:39:51.042154Z",
"url": "https://files.pythonhosted.org/packages/19/fb/b622edac3422f448975f2eb4915ef8d87eba2cc501d18c825713eeca4495/confspec-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d962d3a900cff5b9eefa4f1716e45c6358302713ce263eff637455fba97a8378",
"md5": "fd8773967d0f063dae9a148a7ee66913",
"sha256": "49faf2f1fd64b63da74790f62b4348fd658340d9ec227c4c95e808ebeb48b036"
},
"downloads": -1,
"filename": "confspec-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "fd8773967d0f063dae9a148a7ee66913",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.15,>=3.11.0",
"size": 66530,
"upload_time": "2025-10-20T14:39:52",
"upload_time_iso_8601": "2025-10-20T14:39:52.420189Z",
"url": "https://files.pythonhosted.org/packages/d9/62/d3a900cff5b9eefa4f1716e45c6358302713ce263eff637455fba97a8378/confspec-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 14:39:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tandemdude",
"github_project": "confspec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "confspec"
}
JSON
