v0.38: Introducing EnvWizard (v1) (#235)

* add `v1/env.py`

* update env.py

* minor updates

* minor updates

* minor updates

* minor updates

* minor updates

* planned for #206

* add Env Precedence and Secrets Dir + Dotenv Support for `v1` of `EnvWizard`

* minor changes

* cache secrets and dotenv

* add helper methods

* Add `v1_field_to_env_load` and support `Alias(env=...)` for `EnvWizard`

* Add `Env(...)` to support setting env vars for fields in `EnvWizard` subclasses

* minor fix

* Add `v1_pre_decoder` so `EnvWizard` can decode JSON or comma-separated strings into `dict`/`list`

* Add tests and bugfix

* add E2E tests
* bugfix and functional updates

* Add tests and bugfix

* add EnvWizard E2E tests
* bugfix and functional updates

* Add tests

* should fix #206

* v1: Decode `date` and `datetime` as UTC by default (via `fromtimestamp`)

* update tests

* update tests

* update tests

* EnvWizard: update tests and support bytes/bytearray/dataclass (when already same type)

* update tests

* update logging

* fix for Windows: provide `tz` extra to install `tzdata` for `ZoneInfo`

* v1: Fix loader/dumper codegen and subclass inheritance issues

* Support `kw_only` dataclass fields in loaders
* Fix dumper codegen when dataclass defines no fields
* Fix incorrect caching of `to_dict` on subclasses
* Ensure EnvWizard passes `kw_only=True` to dataclass
* Fix FunctionBuilder globals not being merged
* Accept bytes/bytearray inputs unchanged in loaders
* Pin default `from_dict` and `to_dict` on subclasses
  (prevents lazy codegen inheritance poisoning; fixes #209)
* Refresh dataclass metadata when new annotations are present

* clean up imports

* minor changes

* v1: Rename env.py to _env.py
* v1: Add tests for better coverage
* v1: Support `__post_init__()` in `EnvWizard.__init__()` codegen

* minor changes

* v1: Support `AliasPath()` in `EnvWizard.__init__()` codegen

* fix for Python 3.9

* add type checks on CI as per #234

* fix tests on Python 3.9

* add type checks on CI as per #234

* rename to underscored

* add docs

* minor changes

* update HISTORY.rst

* optimize imports

* optimize imports

Author: rnag

.github/workflows/dev.yml

@@ -19,7 +19,7 @@ concurrency:
 
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
-  # This workflow contains a single job called "build"
+  # This workflow contains two jobs called "test" and "typecheck"
   test:
     # The type of runner that the job will run on
     timeout-minutes: 30
@@ -54,3 +54,31 @@ jobs:
 
       - name: list files
         run: ls -l .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install typecheck deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install mypy
+
+      - name: Syntax check
+        run: |
+          python -m compileall -q dataclass_wizard
+
+      - name: mypy
+        run: |
+          mypy dataclass_wizard
+        continue-on-error: true

.pre-commit-config.yaml

@@ -6,3 +6,8 @@ repos:
         name: rstcheck (README.rst)
         args: ["--report-level=warning"]
         files: ^README\.rst$
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-ast
+        files: \.py$

HISTORY.rst

@@ -2,6 +2,60 @@
 History
 =======
 
+0.38.0 (2025-12-26)
+-------------------
+
+EnvWizard v1 (opt-in)
+~~~~~~~~~~~~~~~~~~~~~
+
+EnvWizard v1 introduces a new, explicit environment-loading engine with
+predictable behavior and expanded feature support. v1 is **opt-in only**
+and does not affect existing users unless enabled.
+
+Highlights:
+
+- Explicit environment precedence (env / dotenv / secrets)
+- First-class nested dataclass support for env loading
+- Separate alias models for load vs dump
+- Improved error diagnostics and debug logging
+- Full support for dotenv files and secrets directories
+
+New v1 features:
+
+- Environment precedence is now configurable and explicit
+- Support for nested ``EnvWizard`` dataclasses
+- New aliasing model:
+  - ``v1_field_to_env_load`` (load-only)
+  - ``v1_field_to_alias_dump`` (dump-only)
+- Added ``Env(...)`` and ``Alias(env=...)`` helpers for field-level env configuration
+- Added ``v1_pre_decoder`` to decode JSON or delimited strings into ``dict`` / ``list``
+- Cached secrets and dotenv paths for improved performance
+- v1 supports ``__post_init__()`` in generated ``EnvWizard.__init__``
+
+Helpers and APIs:
+
+- Added ``env_config`` for optional ``TypedDict``-style typing of ``__env__``
+- ``EnvWizard.dict()`` (v0) is now ``EnvWizard.raw_dict()`` in v1
+- Optimized helpers: ``as_bool``, ``as_int``, ``as_str``
+- Added helpers: ``as_list``, ``as_dict``
+
+Internal Changes and Fixes
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Fixed invalid ``.pyi`` output in ``register_type`` (thanks to :user:`GRcharles`, :pr:`234`)
+- Added syntax checks to pre-commit and type checks to CI (:pr:`234`)
+- Fixed lazy codegen inheritance poisoning (:issue:`209`)
+- v1: Decode ``date`` / ``datetime`` as UTC by default (:issue:`206`)
+- Improved Windows timezone handling via ``tz`` extra (``tzdata`` / ``ZoneInfo``)
+- Improved caching behavior for ``Union`` loaders
+- Fixed multiple codegen and caching edge cases:
+  - ``to_dict`` caching on subclasses
+  - empty dataclass dumpers
+  - ``kw_only`` field handling
+  - FunctionBuilder globals merging
+- Added extensive v1 test coverage (90%+)
+- No breaking changes without explicit v1 opt-in
+
 0.37.0 (2025-12-20)
 -------------------
 

dataclass_wizard/__init__.py

@@ -116,29 +116,31 @@
     'IS_NOT',
     'IS_TRUTHY',
     'IS_FALSY',
+    # Logging
+    'LOG',
 ]
 
 import logging
 
 from .bases_meta import LoadMeta, DumpMeta, EnvMeta, register_type
-from .constants import PACKAGE_NAME
 from .dumpers import DumpMixin, setup_default_dumper
-from .loaders import LoadMixin, setup_default_loader
+from .environ.wizard import EnvWizard
 from .loader_selection import asdict, fromlist, fromdict
+from .loaders import LoadMixin, setup_default_loader
+from .log import LOG
 from .models import (env_field, json_field, json_key, path_field, skip_if_field,
                      KeyPath, Container,
                      Pattern, DatePattern, TimePattern, DateTimePattern,
                      CatchAll, SkipIf, SkipIfNone,
                      EQ, NE, LT, LE, GT, GE, IS, IS_NOT, IS_TRUTHY, IS_FALSY)
-from .environ.wizard import EnvWizard
 from .property_wizard import property_wizard
 from .serial_json import DataclassWizard, JSONWizard, JSONPyWizard, JSONSerializable
 from .wizard_mixins import JSONListWizard, JSONFileWizard, TOMLWizard, YAMLWizard
 
 
 # Set up logging to ``/dev/null`` like a library is supposed to.
 # http://docs.python.org/3.3/howto/logging.html#configuring-logging-for-a-library
-logging.getLogger(PACKAGE_NAME).addHandler(logging.NullHandler())
+LOG.addHandler(logging.NullHandler())
 
 # Setup the default type hooks to use when converting `str` (json) or a Python
 # `dict` object to a `dataclass` instance.

dataclass_wizard/abstractions.py

@@ -1,21 +1,26 @@
 """
 Contains implementations for Abstract Base Classes
 """
+from __future__ import annotations
 import json
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, InitVar, Field
-from typing import Type, TypeVar, Dict, Generic
+from typing import Type, TypeVar, Dict, Generic, TYPE_CHECKING
 
 from .models import Extras
-from .v1.models import Extras as V1Extras, TypeInfo
+
 from .type_def import T, TT
 
 
 # Create a generic variable that can be 'AbstractJSONWizard', or any subclass.
 W = TypeVar('W', bound='AbstractJSONWizard')
 
 
+if TYPE_CHECKING:
+    from .v1.models import Extras as V1Extras, TypeInfo
+
+
 class AbstractEnvWizard(ABC):
     """
     Abstract class that defines the methods a sub-class must implement at a
@@ -271,6 +276,13 @@ def transform_json_field(string: str) -> str:
         (which will ideally be snake-cased).
         """
 
+    @staticmethod
+    @abstractmethod
+    def is_none(tp: TypeInfo, extras: V1Extras) -> str:
+        """
+        Generate the condition to determine if a value is None.
+        """
+
     @staticmethod
     @abstractmethod
     def default_load_to(tp: TypeInfo, extras: V1Extras) -> str:

dataclass_wizard/abstractions.pyi

@@ -442,6 +442,13 @@ class AbstractLoaderGenerator(ABC):
         (which will ideally be snake-cased).
         """
 
+    @staticmethod
+    @abstractmethod
+    def is_none(tp: TypeInfo, extras: V1Extras) -> str:
+        """
+        Generate the condition to determine if a value is None.
+        """
+
     @staticmethod
     @abstractmethod
     def default_load_to(tp: TypeInfo, extras: V1Extras) -> str: