SuperConf

---

This project is in Beta.

SuperConf is a Python library for structured configuration: declare a model with typed fields and nested containers, then load values from dicts, files (YamlSource / JsonSource / TomlSource), environment (EnvSource), or layered Views.

Inspired by Cafram, forked from ClassyConf.

Features

• Type-aware fields (FieldBool, FieldInt, FieldString, FieldList, FieldDict, …)
• Nested models with FieldConf
• Dynamic dict/list containers (ConfigurationDict, ConfigurationList)
• Defaults, custom casting, and Meta options (extra_fields, default, children_class, …)
• Clear access rules: attribute / [] / call (obj("key"))
• File / env / dict sources and multi-source View precedence
• Merge policies (merge(), MergeStrategy)
• Path helpers (PathAnchor, FileAnchor)

Quickstart

Installation

pip install superconf

Or from source:

git clone https://github.com/mrjk/python-superconf.git
cd python-superconf
poetry install

Basic usage

from superconf import ConfigurationObj, FieldBool, FieldInt, FieldString, FieldList

class AppConfig(ConfigurationObj):
    debug = FieldBool(default=False, help="Enable debug mode")
    port = FieldInt(default=8080, help="Server port")
    app_name = FieldString(default="myapp", help="Application name")
    plugins = FieldList(default=[], help="Enabled plugins")

# Defaults
config = AppConfig()
assert config.debug is False
assert config.port == 8080

# Override from a dict (e.g. parsed YAML/JSON)
config = AppConfig(value={
    "debug": "yes",
    "port": "9000",
    "plugins": ["auth", "cache"],
})
assert config.debug is True
assert config.port == 9000
assert config.plugins == ["auth", "cache"]

# Dump as plain data
print(config.get_value())

Nested configuration

from superconf import ConfigurationObj, FieldConf, FieldInt, FieldString

class ServerConfig(ConfigurationObj):
    host = FieldString(default="localhost")
    port = FieldInt(default=8080)

class AppConfig(ConfigurationObj):
    name = FieldString(default="myapp")
    server = FieldConf(ServerConfig)

app = AppConfig(value={"server": {"port": 9000}})
assert app.server.host == "localhost"
assert app.server.port == 9000

Documentation

Section	Path
Guides (start here)	docs/content/guides/
How-to	docs/content/howto/
Implementation notes	docs/content/implementation/

Suggested reading order:

1. 101 — Simplest structure
2. 102 — Field types and unset values
3. 103 — Nested structures
4. 104 — Dynamic dict/list fields
5. 105 — Meta and casting
6. 106 — Merge policies

Overview

Requirements

• Python 3.9+
• Runtime dependencies: pyaml, sentinel

Access cheat sheet

Access	Leaf field	Container field
obj.key	value	container node
obj["key"]	value	value (dict/list)
obj("key") / obj.get_child("key")	node (Leaf)	node

FAQ

How do I load YAML or JSON?
Use YamlSource / JsonSource / TomlSource (see superconf.sources), or parse yourself (yaml.safe_load, from_yaml, …) and pass value=. See Load from files.

Are environment loaders built in?
Yes, as helpers: from_12factor(AppConfig, file="config.yml", cli={...}) (or Meta.env_prefix). Mapping is Gitea-style PREFIX__PATH. Precedence: cli → env → file → defaults (TWELVE_FACTOR_ORDER). See Environment variables. Lower-level: EnvSource + View.

Can I allow undeclared keys?
Yes, set Meta.extra_fields = True on a ConfigurationObj. Extra keys must be provided via value= / full set_value({...}), not by assigning a new attribute after init.

Known limitations

• FieldOption is not available
• TOML dump needs optional tomli-w; TOML load needs Python 3.11+ or tomli

Development

Full maintainer guide: docs/content/project/setup.md. Release / PyPI: docs/content/project/release.md.

Documentation site

task docs:serve    # http://127.0.0.1:8000
task docs:test     # mkdocs --strict
task docs:publish  # gh-pages deploy

Markdown lives under docs/content/; MkDocs config is docs/mkdocs.yml.

Setup

Always use the project-local .venv/ (see poetry.toml). Never install into system Python.

git clone https://github.com/mrjk/python-superconf.git
cd python-superconf
eval "$(mise activate bash)"   # or direnv + use mise
mise install
poetry env use "$(mise which python)"
poetry install --with dev

Python tools run via poetry run (PY in the Taskfile), so you usually do not need to source .venv/bin/activate.

Commands

Uses Taskfile:

Command	Purpose
task test	Report + examples + lint
task test_report	Pytest + coverage
task test_pytest	Pytest suite
task test_examples	Run example scripts
task test_lint	Lint checks (isort --check-only, black, pylint)
task fix_lint	Auto-format with black/isort
task publish_pypi	Publish to PyPI

Project information

License

GPLv3

Author

• mrjk mrjk.78@gmail.com

Support

1. Read the docs
2. Open an issue on GitHub

Related projects

• ClassyConf
• python-decouple
• dynaconf