dataclass-wizard

Bump version: 0.38.2 → 0.39.0

Bump version: 0.38.1 → 0.38.2

Bump version: 0.38.0 → 0.38.1

Bump version: 0.37.0 → 0.38.0

Bump version: 0.36.6 → 0.37.0

Bump version: 0.36.5 → 0.36.6

Bump version: 0.36.4 → 0.36.5

Bump version: 0.36.3 → 0.36.4

Packaging

• Migrated project configuration to pyproject.toml for modern, PEP 517-compliant builds using python -m build. Thanks to CoolCat467 in 213!

Typing

• Fixed a syntax error in typing stub files that could surface during static analysis with tools such as mypy. Thanks to CoolCat467 in 213!

Documentation

• Updated the documentation URL to https://dcw.ritviknag.com.

• Simplified the docs landing page by removing the redundant title header.

• Refined the front-page layout for improved clarity and mobile readability.

Notes

• This release includes documentation and presentation updates only.

• No functional or behavioral changes were introduced.

Documentation

• Added a project logo and refreshed the front-page documentation layout.

• Simplified and cleaned up the README and docs landing page for improved readability, especially on mobile.

Notes

• This release contains documentation and presentation updates only. No functional or behavioral changes were introduced.

Features and Improvements

• Introduce DataclassWizard as the preferred base class for the v1 API. This class auto-applies the @dataclass decorator to subclasses, reducing boilerplate and clarifying the recommended usage going forward.

• Add explicit v1 dump support via a new v1/dumpers.py implementation. This refactor improves separation of concerns and results in better serialization performance when v1 is enabled.

• Update default usage examples and documentation to reflect the new DataclassWizard API and explicit load_case / dump_case configuration.

• Fix annotation resolution for older Python versions by routing through get_resolved_annotations().

API Changes

• Rename v1_key_case to v1_case for clarity and consistency with related v1 configuration options.

Internal Changes

• Refactor v1 load/dump selection logic to route through the new v1 loader and dumper pipeline when enabled.

Features and Improvements

• Add compatability and support for Python 3.14. Thanks to rexzhang in 204!

Bugfixes

• Fix typing stub (.pyi) compatibility for older Python/tooling versions by removing Python 3.12-only type statement syntax and using TypeAlias/typing-compatible annotations instead (fixes 176).

Bugfixes

• Replace ZoneInfo("UTC") with datetime.timezone.utc to avoid import-time failures on platforms without an IANA time zone database (notably Windows), removing the implicit dependency on tzdata (fixes 180).

Bugfixes

• Roll back type ... syntax in .pyi files to maintain compatibility with older Python versions such as 3.9 (fixes 176)

Features and Improvements

• V1 Opt-In:

  • Add support for Patterned Date and Time:

    • Naive Date/Time/Datetime

    • Timezone-aware Time/Datetime

    • UTC Time/Datetime

  • Update Alias and AliasPath to support multiple aliases and nested path(s)

  • Update the KeyCase.AUTO setting (specified via v1_key_case='AUTO') to correctly handle multiple possible keys for the field (e.g., it doesn't latch onto the first encountered key but now tries all valid key case transformations at runtime). This now results in expected or desired behavior (fixes 175)

  • Float to Int Conversion Change: In V1 Opt-in (via Meta setting v1=True), floats or float strings with fractional parts (e.g., 123.4 or "123.4") are no longer silently converted to integers. Instead, they now raise an error. However, floats without fractional parts (e.g., 3.0 or "3.0") will continue to convert to integers as before.

  • Add documentation:

    • Patterned Date and Time

    • Aliases

  • Add tests for coverage

• Optimize logic for determining if an annotated type is a TypedDict

• Update requirements-bench.txt to correctly capture all Benchmark-related dependencies

Bugfixes

• Ensure the py.typed marker is included in the source distribution (fixes 173)

• Address a minor bug in object path parsing that did not correctly interpret quoted literal values within blocks such as braces []

Features and Improvements

• V1 Opt-in

  • Support for recursive types OOTB for the following Python types:

    • NamedTuple

    • TypedDict

    • Union

    • Literal

    • Nested dataclasses

    • Type aliases (introduced in Python 3.12+)

  • Full support for bytes and bytearray in the de/serialization process (fixes 140).

  • Performance improvements: Optimized Load functions for bool, NamedTuple, datetime, date, and time.

  • Added support for Type aliases (via type statement in Python 3.12+).

  • Improved logic in load_to_str to better check if it's within an Optional[...] type.

  • Enhanced handling of sub-types in de/serialization (TODO: add test cases).

  • Show deprecation warning for Meta setting debug_enabled (replaced by v1_debug).

• Updated benchmarks for improved accuracy.

Bugfixes

• Fixed issue where code generation failed to correctly account for indexes, especially when nested collection types like dict were used within a NamedTuple.

• make check now works out-of-the-box for validating README.rst and other RST files for PyPI deployment.

• 169: Explicitly added utf-8 encoding for setup.py to enable installation from source on Windows (shoutout to birkholz-cubert!).

• Introduce v1 opt-in, providing a more user-friendly experience with significant performance improvements for de-serialization 🎉

• Add models for v1, imported from dataclass_wizard.v1:

  • Alias

  • AliasPath

• Add enums for v1, imported from dataclass_wizard.v1.enums:

  • KeyCase

  • KeyAction

• Add Meta settings for v1:

  • v1 — Enable opt-in for the "experimental" major release v1 feature.

  • v1_debug — Replaces the deprecated debug_enabled Meta setting, which will be removed in v1.

  • v1_key_case — Specifies the letter case used for matching JSON keys when mapping them to dataclass fields.

  • v1_field_to_alias — Custom mapping of dataclass fields to their JSON aliases (keys) for de/serialization.

  • v1_on_unknown_key — Defines the action to take when an unknown JSON key is encountered during from_dict or from_json calls.

  • v1_unsafe_parse_dataclass_in_union — Unsafe option: Enables parsing of dataclasses in unions without requiring the presence of a tag_key.

• Require the typing-extensions library up to Python 3.11 (its main use in Python 3.11 is ReadOnly for TypedDict).

• Phase out the UnknownJSONKey exception class in favor of UnknownKeysError, since v1 now provides all missing keys in JSON (not just the first one!).

• Update benchmarks:

  • Add benchmark for CatchAll.

  • Move benchmark dependencies to requirements-bench.txt.

• Add new test cases.

Bugfixes

• Corrected logic in MappingParser that assumed all parsers were subclasses of AbstractParser (159).

  • Add test case to confirm intended functionality.

  • Bump dev dependencies to latest version.

Features and Improvements

• Add support for ABC Containers in typing and collections.abc:

  • Collection

  • Sequence

  • MutableSequence

Bugfixes

• Fixed a bug in ParseError handling.

• Resolved an issue in EnvWizard where passing an instance of a dataclass field type to the constructor caused problems.

• Corrected logic in parsers.py that assumed all parsers were subclasses of AbstractParser; parsers can now be functions as well.

Happy Thanksgiving 🦃, y'all! In this release, Dataclass Wizard introduces the long-awaited EnvWizard 😳🎉.

Features and Improvements

• EnvWizard:

  • Support for working with environment variables, secret files, and .env files.

• New Functions and Helpers:

  • EnvMeta: Helper function to set up the Meta Config for EnvWizard.

  • env_field: Alias for dataclasses.Field() to set a custom environment variable for a field.

  • Helper Functions:

    • as_bool, as_int, as_str optimized.

    • as_list, as_dict added.

• Meta Class Enhancements:

  • New meta classes such as AbstractEnvMeta.

  • New fields added to the Meta class:

    • env_var_to_field

    • field_to_env_var

    • debug_enabled

    • recursive

    • env_file

    • env_prefix

    • secrets_dir

    • key_lookup_with_load

    • key_transform_with_dump

    • skip_defaults

    • skip_if

    • skip_defaults_if

• Benchmark Updates:

  • Updated benchmarks to include new libraries.

  • Added the --all | -A option to benchmark tests for running longer tests against some libraries.

• Documentation:

  • General documentation updates.

Bugfixes

• Resolved inconsistent behavior with dataclasses in Union when Meta tag_key is also defined as a dataclass field (148).

Features and Improvements

• Conditional Field Skipping: Omit fields during JSON serialization based on user-defined conditions.

  • Introduced new Meta settings:

    • skip_if — Skips all fields matching a condition.

    • skip_defaults_if — Skips fields with default values matching a condition.

  • Added per-field controls using SkipIf() annotations.

  • Introduced the skip_if_field wrapper for maximum flexibility.

• New Helper Class: JSONPyWizard

  • A JSONWizard helper to disable camelCase transformation and keep keys as-is.

• Typing Improvements: Added more *.pyi files for enhanced type checking and IDE support.

• Documentation Updates:

  • Added details about upcoming changes in the next major release, v1.0.

Bugfixes

• Fixed compatibility between Global Meta Settings and recursive_classes (142).

Bugfixes

• Fixed issue with using Meta.auto_assign_tags and Meta.raise_on_unknown_json_key together (137).

• Fixed JSONWizard.debug to prevent overwriting existing class meta.

• Resolved issue where both auto_assign_tags and CatchAll resulted in the tag key being incorrectly saved in CatchAll.

• Fixed issue when CatchAll field was specified with a default value but serialized with skip_defaults=False.

• Improved performance in UnionParser: ensured that get_parser is called only once per annotated type.

• Added test case(s) to confirm intended behavior.

Bugfixes

• Include *.pyi files in source distribution (packaging).

Features and Improvements

• Nested JSON Mapping (60): Map nested JSON keys to dataclass fields using helper functions KeyPath or json_field.

• Catch-All Keys (57): Save unknown JSON keys with ease.

• Cleaner Codebase: Remove comments and type annotations for Python files with .pyi counterparts.

• Enhanced Debugging: debug_enabled now supports bool | int | str, allowing flexible logging levels.

• Documentation Updates: Improved and expanded docs!

Features and Improvements

• Added TOMLWizard.

• Introduced new (pre-process) serializer hooks:

  • _pre_from_dict

  • _pre_dict

• Added debug parameter to JSONWizard.__init_subclass__.

• Added *.pyi stub files for better Type Hinting and Autocompletion in IDEs (e.g., PyCharm):

  • abstractions.pyi

  • serial_json.pyi

• Introduced utility class FunctionBuilder to help build and dynamically exec a function.

• Documentation/tests on the new and updated features.

Changes

• The returned parser for a dataclass is now the original load/dump function itself (which takes a single argument) rather than a Parser instance.

• Minor optimization and quality-of-life improvement: dynamically exec dataclass load and dump functions.

• Improved performance: if a class defines a from_dict method - equivalent to fromdict - and a to_dict method - equivalent to asdict - replace them with dynamically generated load/dump functions.

• Deprecated the pre-process hook DumpMixin.__pre_as_dict__.

Features and Improvements

• This minor release drops support for Python 3.6, 3.7, and 3.8, all of which have reached End of Life (EOL). Check out the Python End of Life Cycle here. Key changes resulting from this update include:

  • Resolved pyup errors, previously flagged as "insecure" due to outdated package versions that lacked support for Python 3.8 or earlier.

  • Update all requirements to latest versions.

  • Cleaned up various TODO comments scattered throughout the codebase, as many were specific to older Python versions.

  • Simplified and improved codebase for easier maintenance.

  • Remove everything except the py.typed file (see comment).

• Added test case to satisfy 89.

• Added support for cyclic or "recursive" dataclasses, as first mentioned in 62 (special thanks to dlenski for finalizing this in 138!).

Bugfixes

• 62: Cyclic or "recursive" dataclasses no longer raises a RecursionError.

• Typing locals should now correctly key off the correct Python version, see the commit that addressed this.

• Add py.typed marker, which finalizes 51. Credits to stdedos in 136.

• This will be the latest (minor) release with support for Python 3.6, 3.7, and 3.8 -- all of which have reached end-of-life!

Features and Improvements

• Add compatability and support for Python 3.13. Thanks to benjjs in 129!

Bugfixes

• Fix: LiteralParser.__contains__ method compares value of item with Literal arguments. Contributed by mikeweltevrede in 111.

Features and Improvements

• Add support for pathlib.Path. Thanks to assafge in 79.

• Resolve mypy typing issues. Thanks to AdiNar in 64.

Features and Improvements

• 125: add support for typing.Required, NotRequired

Bugfixes

• Fixed by 125: Annotating TypedDict field with one of Required or NotRequired wrappers introduced in Python 3.11, no longer raises a TypeError -- credits to claui.

• 94: Allows the ability to define keys in JSON/dataclass that do not undergo transformation -- credits to cquick01.

  • LetterCase.NONE - Performs no conversion on strings.

    • ex: MY_FIELD_NAME -> MY_FIELD_NAME

Features and Improvements

• Add full support for Python 3.11 and 3.12 (Credits to alexanderilyin on 101)

• Project-specific development changes

  • Update CI to run tests on PY 3.11 and 3.12

  • Update wheel version

  • Update setup.py to add a dev extra which installs dev-related dependencies

  • Move test dependencies into requirements-test.txt

  • Add sphinx_issues dependency to easily add link in docs to an user/issue/PR on GitHub

  • Update project_urls on PyPI to add extra links, such as "Changelog" and "Issue Tracker"

Bugfixes

• Fix: Loading a Variadic Tuple fails for length 0 (Credits to intentionally-left-nil on 105)

• Stop-gap fix for time-string patterns that contain - or +, as Python 3.11+ can interpret this as timezone data.

Features and Improvements

• Minor performance improvement when dumping custom sub-types or unhandled types, such that we cache the dump hook for the type so that subsequent lookups are faster overall.

Features and Improvements

• Update MissingFields to provide a more user-friendly error message, in cases where a missing dataclass field is not snake-cased, but could - with the right key transform - map to a key in the JSON object. For example, a JSON key of myField and a field named MyField.

Bugfixes

• Fixed a bug in the load (or de-serialization) process with from_dict, where a MissingFields was raised in cases where a dataclass field is not snake-cased, but is otherwise identical to a key in the JSON object. For example, a JSON key and field both named viewMode. The JSON data in such cases should now be correctly de-serialized to a dataclass instance as expected.

Features and Improvements

• Ensure that the debug_enabled flag now applies recursively to all nested dataclasses, which is more helpful for debugging purposes.

• Add new attribute json_object -- which contains the original JSON object -- to ParseError objects, and include it in the object representation.

Bugfixes

• Fixed an issue with the debug_enabled flag enabled, where some load hooks were not properly decorated when debug mode was enabled; errors were not properly formatted in these cases. To elaborate, this only affected load hooks decorated with a @_single_arg_alias. In particular, this affected the load hooks for a few annotated types, such as float and enum.

Features and Improvements

• Adds few extra Wizard Mixin classes that might prove incredibly convenient to use.

  • JSONListWizard - Extends JSONWizard to return Container -- instead of list -- objects where possible.

  • JSONFileWizard - Makes it easier to convert dataclass instances from/to JSON files on a local drive.

  • YAMLWizard - Provides support to convert dataclass instances to/from YAML, using the default PyYAML parser.

• Add a new Container model class, a list sub-type which acts as a convenience wrapper around a collection of dataclass instances.

• The dataclass-wizard library now supports parsing of YAML data. It adds the PyYAML as an optional dependency, which is loaded when it's used for the initial time. This extra dependency can be installed via:

  $ pip install dataclass-wizard[yaml]

• Update the parsing logic in as_timedelta for timedelta annotated types so we now explicitly check the types. If the value is numeric, or if it's a string in a numeric value like "1.2", we can parse it directly and so avoid calling the pytimeparse module.

• Update and refactor docs, doc layout, and the readme.

• Move benchmark tests to the benchmarks/ directory.

• Support custom patterns for dates and times, which are parsed (de-serialized) using datetime.strptime. This allows two approaches to be used, which have complete support in Python 3.7+ currently:

  • Using the DatePattern, TimePattern, and DateTimePattern type annotations, representing patterned date, time, and datetime objects respectively.

  • Use Annotated to annotate the field as list[time] for example, and pass in Pattern as an extra.

Features and Improvements

• Add the option to customize the name of the tag key that will be used to (de)serialize fields that contain dataclasses within Union types. A new attribute tag_key in the Meta config determines the key in the JSON object that will be used for this purpose, which defaults to __tag__ if not specified.

• Add the ability to auto-generate tags for a class - using the name of the class - if a value for tag is not specified in the Meta config for a dataclass that appears within a Union declaration. A new flag auto_assign_tags in the Meta config can be enabled to allow auto-assigning the class name as a tag.

Breaking Changes

• The LoadMeta and DumpMeta helper functions no longer accept a class type as the first argument; the correct usage now is to invoke the bind_to method on the Meta config returned. That is, given a dataclass A, replace the following syntax:

  LoadMeta(A, **kwargs)

  with a more explicit binding:

  LoadMeta(**kwargs).bind_to(A)

• The asdict helper function no longer accepts a Meta config as an argument. This is to encourage the usage of LoadMeta and DumpMeta, as mentioned above. The main impetus for this change is performance, since the Meta config for a class only needs to be set up once using this approach.

• Updated the project status from Beta to Production/Stable, to signify that any further breaking changes will result in bumping the major version.

Features and Improvements

• Add the bind_to method to the base Meta class, BaseJSONWizardMeta.

• Meta config specified for a main dataclass (i.e. the class passed in to from_dict and to_dict) now applies recursively to any nested dataclasses by default. The Meta config from the main class will be merged with the Meta config for each nested class. Note that this behavior can be disabled however, with the recursive parameter passed in to the Meta config.

• Rename BaseMeta to AbstractMeta, as the name should be overall more clearer, since it's actually an abstract class.

• property_wizard: Update the metaclass to support `new-style annotations`_, also via a __future__ import declared at a the top of a module; this allows `PEP 585`_ and `PEP 604`_ style annotations to be used in Python 3.7 and higher.

• Support new-style annotations in Python 3.7+, via a __future__ import declared at a the top of a module; this allows PEP 585 and PEP 604 style annotations to be used in Python 3.7 and higher.

• wiz CLI: Add the -x / --experimental flag, which instead uses new-style annotations in the generated Python code.

• Update the docs and readme with examples and usage of future annotations in Python 3.7+.

• Minor code refactor and cleanup to support ForwardRef in Python 3.6 a little better.

• Add full support for Python 3.10

• Add support for serializing datetime.timedelta

  • Requires an extra for de-serialization, can be installed via pip install dataclass-wizard[timedelta].

Features and Improvements

• Add new internal helper function eval_forward_ref_if_needed

Bugfixes

• Support forward references in type arguments to Union, as well as when iterating over the list of dataclasses.fields for each data class.

• Add a new method list_to_json to the JSONWizard Mixin class, which can be used to convert a list of dataclass instances to a JSON string representation.

• Minor code refactoring to introduce small typing-related changes.

• Update docs.

• Add the ability to skip fields with default values in the serialization process. A new attribute skip_defaults in the inner Meta class determines whether to skip / omit fields with default values, based on the default or default_factory argument to dataclasses.field.

• Add the ability to omit fields in the serialization process.

  • A new argument dump added to the json_key and json_field helper functions determines whether to exclude the field in the JSON or dictionary result.

  • The asdict helper function has similarly been updated to accept a exclude argument, containing a list of one or more dataclass field names to exclude from the serialization process.

Bugfixes

• Dataclass fields that are excluded from the constructor method - i.e. ones defined like field(init=False...) - should now be similarly handled in the de-serialization process.