environ-config

24.1.0 verified Fri May 01 auth: no python

A Python library for boilerplate-free configuration using environment variables. Current version 24.1.0 (released 2024-10-27) with type annotations, minimal setup, and a decorator-based approach. Maintenance release with tests/docs updates.

pip install environ-config

Common errors

error ModuleNotFoundError: No module named 'environ_config' ↓

cause The package name is 'environ-config' but the import module is 'environ'.

fix

Use 'import environ' instead.

error TypeError: __init_subclass__() missing 1 required positional argument: 'cls' ↓

cause Using @config on a class that is a subclass of something other than object, or misusing the decorator.

fix

Ensure the class decorated with @config does not inherit from another class unless it's also a config class.

error AttributeError: 'MyConfig' object has no attribute 'host' ↓

cause The environment variable is not set and there is no default value.

fix

Set the environment variable or provide a default in the field definition (e.g., host: str = 'localhost').

Warnings

gotcha Environment variables are read at class instantiation time, not import time. The values are fixed once the object is created; subsequent changes to env vars require a new instance. ↓

fix Create a fresh config object when you need updated values, or use a singleton pattern that re-reads on each access.

deprecated As of 23.1.0, type annotations are required for all fields. Omitting type hint will raise a TypeError. ↓

fix Always add type annotations to config fields, e.g., host: str.

Imports

environ-config
wrong
```
import environ_config
```
correct
```
import environ
```
The package name on PyPI is 'environ-config' but the import module is 'environ'. Using 'environ_config' will raise ModuleNotFoundError.
environ.config
wrong
```
import environ; environ.config()
```
correct
```
from environ import config
```
Common but the correct way is to import the config class directly. Both work, but direct import is idiomatic.

Quickstart

Define a configuration class with a decorator. Annotate fields; they are automatically populated from environment variables with the given prefix. Defaults are allowed.

import os
from environ import config

@config
class MyConfig:
    prefix = 'MYAPP'
    host: str
    port: int = 8080

cfg = MyConfig()
print(f'Host: {cfg.host}, Port: {cfg.port}')
os.environ['MYAPP_HOST'] = 'example.com'
os.environ['MYAPP_PORT'] = '9090'
cfg2 = MyConfig()
print(f'Host: {cfg2.host}, Port: {cfg2.port}')