EnvWizard v1 — Quickstart (Opt‐In)

EnvWizard v1 is a typed configuration loader for Python dataclasses with:

• explicit environment precedence
• nested dataclass support
• first-class dotenv and secrets integration
• powerful field-level aliasing

As of dataclass-wizard v0.38, v1 is opt-in only and does not affect existing users unless explicitly enabled.

Installation

pip install 'dataclass-wizard>=0.38,<1'

Optional extras:

pip install dataclass-wizard[dotenv]   # .env support
pip install dataclass-wizard[tz]       # Windows timezone data

Quickstart

This example demonstrates the core v1 features: Env, Alias(env=...), type coercion, and defaults.

import os
from dataclass_wizard.v1 import EnvWizard, Env, Alias

os.environ.update({
    'APP_NAME': 'Hogwarts',
    'DEBUG': 'true',
})

class Apprentice(EnvWizard):
    school: str = Env('APP_NAME')
    debug: bool
    knows_magic: bool = Alias(
        env='KNOWS_WINGARDIUM_LEVIOSA',
        default=False,
    )

a = Apprentice()

assert a.school == 'Hogwarts'
assert a.debug is True
assert a.knows_magic is False

What just happened?

• Env('APP_NAME') binds a field to a specific env var
• Alias(env=...) accepts alternate env names
• Values are parsed from strings into typed fields
• Defaults prevent hard failures when env vars are missing

No decorators. No boilerplate. Just dataclasses.

Where values come from (important)

EnvWizard v1 resolves values using explicit precedence:

Secrets → Environment → Dotenv

This order is configurable, testable, and predictable.

If a required value cannot be resolved, EnvWizard raises a MissingVars error with actionable diagnostics.

Example:

class Apprentice(EnvWizard):
    knows_magic: bool

Apprentice()

Error:

MissingVars:
Apprentice has 1 required field missing:
  - knows_magic → KNOWS_MAGIC

Dotenv support

Create a .env file:

KNOWS_MAGIC=true

Enable dotenv loading:

class Apprentice(EnvWizard):
    class _(EnvWizard.Meta):
        env_file = True

    knows_magic: bool

Or, using the helper:

from dataclass_wizard import EnvMeta

EnvMeta(env_file=True).bind_to(Apprentice)

Later dotenv files override earlier ones.

Secrets directories (Docker / Kubernetes)

EnvWizard v1 supports secret directories, where:

• filenames = keys
• file contents = values

class Secrets(EnvWizard):
    class _(EnvWizard.Meta):
        secrets_dir = '/run/secrets'

    api_key: str

This integrates naturally with containerized deployments.

Advanced usage (optional)

Injecting env values programmatically

You may pass values directly via __env__:

a = Apprentice(__env__={
    'mapping': {'KNOWS_WINGARDIUM_LEVIOSA': True}
})

For better IDE type hints, use env_config:

from dataclass_wizard.v1 import env_config

a = Apprentice(
    __env__=env_config(
        mapping={'KNOWS_WINGARDIUM_LEVIOSA': True}
    )
)

This is useful for tests and dynamic configuration.

Alias paths (teaser)

EnvWizard v1 also supports alias paths for hierarchical mappings:

from dataclass_wizard.v1 import AliasPath

class Config(EnvWizard):
    database_url: str = AliasPath('DATABASE', 'URL')

See the reference docs for full details.

Beyond the Quickstart — v1 highlights

EnvWizard v1 adds:

• Explicit, configurable environment precedence

• Nested EnvWizard dataclasses

• Load-only vs dump-only aliasing:

  • v1_field_to_env_load
  • v1_field_to_alias_dump

• Field helpers: Env(...), Alias(env=...), AliasPath(...)

• v1_pre_decoder for JSON / delimited env values

• Cached secrets & dotenv paths

• Full support for kw_only=True

• __post_init__() support in generated __init__

Next steps

• 📘 Reference docs (RTD): https://dcw.ritviknag.com/
• 🧭 Migration guide: v0 → v1
• 🧪 Test coverage: v1 EnvWizard has 90%+ coverage
• 💬 Feedback welcome via GitHub Issues & Discussions