Config¶

Build a Config from H2CORN_* environment variables.

Each option's environment variable name is its field name in upper case, prefixed with H2CORN_ (for example, H2CORN_BIND, H2CORN_WORKERS, H2CORN_PROXY_HEADERS). Variables that are not set fall through to defaults; unrecognized variables are ignored.

The convenience pair H2CORN_HOST / H2CORN_PORT is accepted only when H2CORN_BIND is unset.

Examples:

Pass an explicit mapping so the process environment is not involved:

>>> config = Config.from_env(
...     {'H2CORN_BIND': '127.0.0.1:9000', 'H2CORN_WORKERS': '2'}
... )
>>> (config.bind, config.workers)
(('127.0.0.1:9000',), 2)

Build a Config from a plain mapping (e.g. parsed JSON or TOML).

Keys must match either a field name on Config or the convenience keys host/port. Unknown keys raise ValueError. String values are coerced through the same parsing rules as the matching environment variable; non-string values are passed through and validated by __post_init__.

Examples:

String values use the same parsing rules as environment values:

>>> config = Config.from_mapping(
...     {'workers': '2', 'access_log': 'false'}
... )
>>> (config.workers, config.access_log)
(2, False)

Build a Config from a TOML file.

The file must be a flat table whose keys correspond to Config field names. Example:

bind = ["127.0.0.1:8000"]
workers = 4
proxy_headers = true
forwarded_allow_ips = ["127.0.0.1", "::1", "unix"]
forwarded_fields = ["for", "proto"]
http1 = false

Examples:

Load a flat TOML file without using process-wide configuration:

>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> with TemporaryDirectory() as directory:
...     path = Path(directory) / 'config.toml'
...     _ = path.write_text('workers = 2\n', encoding='utf-8')
...     config = Config.from_toml(path)
>>> config.workers
2