lzconfig — Zero-Boilerplate Configuration

lz: Too lazy to type lazy

中文文档

Import and go. No init, no loader calls, no boilerplate.

import lzconfig

# Attribute-style access
print(lzconfig.database.host)           # → "localhost"
print(lzconfig.database.credentials.user)  # → "admin"

# Dict-style access
print(lzconfig['database']['host'])     # → "localhost"

# Mixed access
print(lzconfig.database['port'])        # → 5432

# Safe access with defaults
print(lzconfig.get('debug', False))     # → True

How It Works

At import time, lzconfig discovers your config file, parses it, interpolates environment variables, and replaces itself in sys.modules with the loaded configuration object. From then on, lzconfig is your config.

Config File Resolution

1. If LZCONFIG_FILE is set (and non-empty), that file is used. Relative paths are resolved against the current working directory.

2. Otherwise, the current directory is scanned for the first match:

   Priority	Filename
   1	lzconfig.yaml
   2	lzconfig.yml
   3	lzconfig.json
   4	lzconfig.toml
   5	lzconfig.ini
   6	lzconfig.cfg
   7	lzconfig.env
   8	lzconfig.xml

3. If nothing is found, ConfigNotFoundError is raised at import time.

Supported Formats

Core formats (JSON, INI, XML) work with zero dependencies. Install extras as needed:

pip install lzconfig[yaml,toml,dotenv]   # specific extras
pip install lzconfig[all]                # everything

Environment Variable Interpolation

$VAR and ${VAR} references in config values are expanded at load time using os.path.expandvars:

# lzconfig.yaml
database:
  host: $DB_HOST
  password: ${DB_PASSWORD}

Undefined variables are left as literal text — no error is raised.

Access Patterns

Key / Method Collision

If a config key happens to have the same name as a ConfigObject method (e.g., get, items, keys):

• Attribute access (lzconfig.items) returns the method.
• Dict access (lzconfig['items']) always returns the config value.

This is a deliberate trade-off. When in doubt, use [] — it always works.

Error Handling

All exceptions inherit from ConfigError and can be imported directly:

from lzconfig import ConfigError, ConfigNotFoundError, ConfigKeyError

License

MIT