# Env Magic (v1)

The Environment Wizard (`EnvWizard`) is a dataclass mixin for loading typed configuration from:

- environment variables

- `.env` files

- secret directories

It performs string-to-type coercion, validates input, and in v1 supports nested dataclasses.

Important

EnvWizard v1 is opt-in. If you do not enable it, v0 behavior applies.

Hint

This page documents v1 concepts: explicit precedence, v1 aliasing, and nested dataclass support.

## Why v1?

In v0, environment lookup relied on implicit heuristics and cascading fallbacks. That made behavior harder to reason about and customize safely.

v1 introduces:

- explicit environment precedence

- clearer aliasing rules (load vs dump)

- first-class nested dataclass support

## Installation

Install the base package:

    pip install dataclass-wizard

Optional extras:

    pip install dataclass-wizard[dotenv]
    pip install dataclass-wizard[tz]

## Opting into v1

Enable v1 via the inner `Meta` class:

    from dataclass_wizard.v1 import EnvWizard

    class Config(EnvWizard):
        class _(EnvWizard.Meta):
            v1 = True

        token: str

Or using `EnvMeta`:

    from dataclass_wizard import EnvMeta
    from dataclass_wizard.v1 import EnvWizard

    class Config(EnvWizard):
        token: str

    EnvMeta(v1=True).bind_to(Config)

## Quick Start

    import os
    from dataclass_wizard.v1 import EnvWizard

    os.environ.update({
        "APP_NAME": "Env Wizard",
        "MAX_CONNECTIONS": "10",
        "DEBUG": "true",
    })

    class AppConfig(EnvWizard):
        app_name: str
        max_connections: int
        debug: bool

    cfg = AppConfig()

    assert cfg.app_name == "Env Wizard"
    assert cfg.max_connections == 10
    assert cfg.debug is True

## Environment Precedence

v1 resolves values from multiple sources using an explicit precedence order.

Default precedence:

    Secrets → Environment → Dotenv

Later sources override earlier sources.

Customize precedence:

    from dataclass_wizard.v1 import EnvWizard
    from dataclass_wizard.v1.enums import EnvPrecedence

    class Config(EnvWizard):
        class _(EnvWizard.Meta):
            v1 = True
            v1_env_precedence = EnvPrecedence.SECRETS_DOTENV_ENV

        token: str

## Dotenv Support

Enable `.env` loading via `Meta.env_file`:

    class Config(EnvWizard):
        class _(EnvWizard.Meta):
            v1 = True
            env_file = True

        api_key: str

Custom paths are supported:

    from pathlib import Path

    class Config(EnvWizard):
        class _(EnvWizard.Meta):
            v1 = True
            env_file = Path(".env.prod")

        db_host: str

If multiple files are provided, later files take precedence.

## Secrets Directories

Secrets directories treat filenames as keys and file contents as values.

    class Config(EnvWizard):
        class _(EnvWizard.Meta):
            v1 = True
            secrets_dir = "/run/secrets"

        db_password: str

## Field Aliases (v1)

Load-only aliases (recommended):

    class Config(EnvWizard):
        class _(EnvWizard.Meta):
            v1 = True
            v1_field_to_env_load = {
                "db_url": ["DATABASE_URL", "DB_URL"],
            }

        db_url: str

Dump-only aliases:

    class _(EnvWizard.Meta):
        v1_field_to_alias_dump = {
            "db_url": "databaseUrl",
        }

Hint

Loading and dumping are intentionally separate concerns in v1.

## Prefixes

Static prefix:

    class Config(EnvWizard):
        class _(EnvWizard.Meta):
            v1 = True
            env_prefix = "APP_"

        name: str

Dynamic override at runtime:

    Config(_env_prefix="CUSTOM_")

## Nested Dataclasses (v1)

v1 supports nested dataclasses out of the box.

    class DB(EnvWizard):
        host: str
        port: int

    class Config(EnvWizard):
        class _(EnvWizard.Meta):
            v1 = True

        db: DB

Environment variables:

    DB_HOST=localhost
    DB_PORT=5432

## Error Handling

Common errors include:

- `MissingVars`: required value not found

- `ParseError`: type conversion failed

- `UnknownKeyError`: unknown key (if enabled)

Enable debug output:

    class _(EnvWizard.Meta):
        v1_debug = True