diff --git a/HISTORY.rst b/HISTORY.rst index 08354def..886ad18f 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -2,6 +2,14 @@ History ======= +0.38.1 (2025-12-26) +------------------- + +**Documentation** + +- Streamlined and modernized front-page documentation +- Improved visibility and guidance for v1 opt-in usage + 0.38.0 (2025-12-26) ------------------- diff --git a/README.rst b/README.rst index 1f072d11..a98aa72f 100644 --- a/README.rst +++ b/README.rst @@ -45,132 +45,130 @@ MyClass(my_str='20', is_active_tuple=(True, False, True), list_of_int=[1, 2, 3]) .. note:: - The example above demonstrates automatic type coercion, key casing transforms, - and support for nested dataclass structures. - ``DataclassWizard`` also auto-applies ``@dataclass`` to subclasses. - See the docs for more examples and advanced usage. + The example above demonstrates automatic type coercion, key casing + transforms, and support for nested dataclasses. ``DataclassWizard`` + also auto-applies ``@dataclass`` to subclasses. + +.. important:: + + A new **v1 engine** is available as an opt-in, offering explicit + environment precedence, nested dataclass support, and improved performance. + See the `Field Guide to V1 Opt-in`_ for details. .. contents:: Contents :depth: 1 :local: :backlinks: none -``v1`` Opt-In ๐Ÿš€ ----------------- +Why Dataclass Wizard? +--------------------- + +Dataclass Wizard helps you turn Python dataclasses into robust, +high-performance serialization schemas with minimal effort. + +- ๐Ÿš€ Fast โ€” code-generated loaders and dumpers +- ๐Ÿชถ Lightweight โ€” pure Python, minimal dependencies +- ๐Ÿง  Typed โ€” powered by Python type hints +- ๐Ÿง™ Flexible โ€” JSON, YAML, TOML, and environment variables +- ๐Ÿงช Reliable โ€” battle-tested with extensive test coverage + +Quick Examples +-------------- -Early access to **V1** is available! To opt in, simply enable ``v1=True`` in the ``Meta`` settings: +.. rubric:: JSON De/Serialization .. code-block:: python3 from dataclasses import dataclass - from dataclass_wizard import JSONPyWizard - from dataclass_wizard.v1 import Alias + from dataclass_wizard import JSONWizard @dataclass - class A(JSONPyWizard): - class _(JSONPyWizard.Meta): - v1 = True + class Data(JSONWizard): + value: int - my_str: str - version_info: float = Alias(load='v-info') + data = Data.from_dict({"value": "123"}) + assert data.value == 123 + print(data.to_json()) - # Alternatively, for simple dataclasses that don't subclass `JSONPyWizard`: - # LoadMeta(v1=True).bind_to(A) +.. rubric:: Environment Variables - a = A.from_dict({'my_str': 'test', 'v-info': '1.0'}) - assert a.version_info == 1.0 - assert a.to_dict() == {'my_str': 'test', 'version_info': 1.0} +.. code-block:: python3 -For more information, see the `Field Guide to V1 Opt-in`_. + import os + from dataclass_wizard import EnvWizard -Performance Improvements -~~~~~~~~~~~~~~~~~~~~~~~~ + os.environ['DEBUG'] = 'true' -The upcoming **V1** release brings significant performance improvements in de/serialization. Personal benchmarks show that **V1** can make Dataclass Wizard -approximately **2x faster** than ``pydantic``! + class Config(EnvWizard): + debug: bool -While some features are still being refined and fully supported, **v1** positions Dataclass Wizard alongside other high-performance serialization libraries in Python. + cfg = Config() + assert cfg.debug is True -Why Use Dataclass Wizard? -------------------------- +.. rubric:: EnvWizard v1 (Opt-in) -Effortlessly handle complex data with one of the *fastest* and *lightweight* libraries available! Perfect for APIs, JSON wrangling, and more. +.. code-block:: python3 -- ๐Ÿš€ **Blazing Fast** โ€” One of the fastest libraries out there! -- ๐Ÿชถ **Lightweight** โ€” Pure Python, minimal dependencies -- ๐Ÿ‘ถ Easy Setup โ€” Intuitive, hassle-free -- โ˜๏ธ **Battle-Tested** โ€” Proven reliability with solid test coverage -- โš™๏ธ Highly Customizable โ€” Endless de/serialization options to fit your needs -- ๐ŸŽ‰ Built-in Support โ€” JSON, YAML, TOML, and environment/settings management -- ๐Ÿ“ฆ **Full Python Type Support** โ€” Powered by type hints with full support for native types and ``typing-extensions`` -- ๐Ÿ“ Auto-Generate Schemas โ€” JSON to Dataclass made easy + import os + from dataclass_wizard.v1 import EnvWizard, Env + + os.environ['DEBUG_MODE'] = 'true' -Key Features ------------- -- ๐Ÿ”„ Flexible (de)serialization โ€” Marshal dataclasses to/from JSON, TOML, YAML, or ``dict`` with ease. -- ๐ŸŒฟ Environment Magic โ€” Map env vars and ``.env`` files to strongly-typed class fields effortlessly. -- ๐Ÿง‘โ€๐Ÿ’ป Field Properties Made Simple โ€” Add properties with default values to your dataclasses. -- ๐Ÿง™โ€โ™‚๏ธ JSON-to-Dataclass Wizardry โ€” Auto-generate a dataclass schema from any JSON file or string instantly. + class Config(EnvWizard): + debug: bool = Env('DEBUG_MODE') + + + cfg = Config() + assert cfg.debug is True + +.. tip:: + EnvWizard v1 introduces explicit environment precedence and nested + dataclass support. See `Field Guide to V1 Opt-in`_ for full details. Installation ------------ -*Dataclass Wizard* is available on `PyPI`_. You can install it with ``pip``: +Install from `PyPI`_: .. code-block:: console - $ pip install dataclass-wizard + pip install dataclass-wizard -Also available on `conda`_ via `conda-forge`_. To install via ``conda``: +Or via `conda-forge`_: .. code-block:: console - $ conda install dataclass-wizard -c conda-forge + conda install -c conda-forge dataclass-wizard -This library supports **Python 3.9+**. Support for Python 3.6 โ€“ 3.8 was -available in earlier releases but is no longer maintained, as those -versions no longer receive security updates. +Dataclass Wizard supports **Python 3.9+**. -For convenience, the table below outlines the last compatible release -of *Dataclass Wizard* for unsupported Python versions (3.6 โ€“ 3.8): +.. note:: + Python 3.6โ€“3.8 users should install the last supported release, + ``dataclass-wizard==0.26.1``. + See `PyPI`_ for historical versions and the `Changelog`_ for details. -.. list-table:: - :header-rows: 1 - :widths: 15 35 15 - - * - Python Version - - Last Version of ``dataclass-wizard`` - - Python EOL - * - 3.8 - - 0.26.1_ - - 2024-10-07 - * - 3.7 - - 0.26.1_ - - 2023-06-27 - * - 3.6 - - 0.26.1_ - - 2021-12-23 - -.. _0.26.1: https://pypi.org/project/dataclass-wizard/0.26.1/ .. _PyPI: https://pypi.org/project/dataclass-wizard/ -.. _conda: https://anaconda.org/conda-forge/dataclass-wizard .. _conda-forge: https://conda-forge.org/ .. _Changelog: https://dcw.ritviknag.com/en/latest/history.html -See the package on `PyPI`_ and the `Changelog`_ in the docs for the latest version details. - Wizard Mixins โœจ ---------------- -In addition to ``JSONWizard``, these `Mixin`_ classes simplify common tasks and make your data handling *spellbindingly* efficient: +In addition to ``JSONWizard``, Dataclass Wizard provides a set of focused +Mixin_ classes to simplify common serialization tasks: + +- ๐Ÿช„ `EnvWizard`_ โ€” Load environment variables and ``.env`` files into typed schemas, + including support for secret directories. +- ๐ŸŽฉ `JSONPyWizard`_ โ€” A helper for ``JSONWizard`` that preserves keys as-is + (no case transformations). +- ๐Ÿ”ฎ `JSONListWizard`_ โ€” Extend ``JSONWizard`` to convert lists into container objects. +- ๐Ÿ’ผ `JSONFileWizard`_ โ€” Load and save dataclass instances from local JSON files. -- ๐Ÿช„ `EnvWizard`_ โ€” Load environment variables and `.env` files into typed schemas, even supporting secret files (keys as file names). -- ๐ŸŽฉ `JSONPyWizard`_ โ€” A helper for ``JSONWizard`` that preserves your keys as-is (no camelCase changes). -- ๐Ÿ”ฎ `JSONListWizard`_ โ€” Extend ``JSONWizard`` to convert lists into `Container`_ objects. -- ๐Ÿ’ผ `JSONFileWizard`_ โ€” Convert dataclass instances to/from local JSON files with ease. -- ๐ŸŒณ `TOMLWizard`_ โ€” Map your dataclasses to/from TOML format. -- ๐Ÿง™โ€โ™‚๏ธ `YAMLWizard`_ โ€” Convert between YAML and dataclass instances using ``PyYAML``. +Optional format support: + +- ๐ŸŒณ `TOMLWizard`_ โ€” Map dataclasses to and from TOML. +- ๐Ÿง™โ€โ™‚๏ธ `YAMLWizard`_ โ€” Convert between YAML and dataclasses using ``PyYAML``. Supported Types ๐Ÿง‘โ€๐Ÿ’ป --------------------- @@ -202,149 +200,6 @@ with the v1 code generation engine. See `Type Hooks`_ for details and examples. -Usage and Examples ------------------- - -.. rubric:: Seamless JSON De/Serialization with ``JSONWizard`` - -.. code-block:: python3 - - from __future__ import annotations # Optional in Python 3.10+ - - from dataclasses import dataclass, field - from enum import Enum - from datetime import date - - from dataclass_wizard import JSONWizard - - - @dataclass - class Data(JSONWizard): - # Use Meta to customize JSON de/serialization - class _(JSONWizard.Meta): - key_transform_with_dump = 'LISP' # Transform keys to LISP-case during dump - - a_sample_bool: bool - values: list[Inner] = field(default_factory=list) - - - @dataclass - class Inner: - # Nested data with optional enums and typed dictionaries - vehicle: Car | None - my_dates: dict[int, date] - - - class Car(Enum): - SEDAN = 'BMW Coupe' - SUV = 'Toyota 4Runner' - - - # Input JSON-like dictionary - my_dict = { - 'values': [{'vehicle': 'Toyota 4Runner', 'My-Dates': {'123': '2023-01-31'}}], - 'aSampleBool': 'TRUE' - } - - # Deserialize into strongly-typed dataclass instances - data = Data.from_dict(my_dict) - print((v := data.values[0]).vehicle) # Prints: - assert v.my_dates[123] == date(2023, 1, 31) # > True - - # Serialize back into pretty-printed JSON - print(data.to_json(indent=2)) - -.. rubric:: Map Environment Variables with ``EnvWizard`` - -Easily map environment variables to Python dataclasses: - -.. code-block:: python3 - - import os - from dataclass_wizard import EnvWizard - - os.environ.update({ - 'APP_NAME': 'My App', - 'MAX_CONNECTIONS': '10', - 'DEBUG_MODE': 'true' - }) - - class AppConfig(EnvWizard): - app_name: str - max_connections: int - debug_mode: bool - - config = AppConfig() - print(config.app_name) # My App - print(config.debug_mode) # True - -๐Ÿ“– See more `on EnvWizard`_ in the full documentation. - -.. rubric:: Dataclass Properties with ``property_wizard`` - -Add field properties to your dataclasses with default values using ``property_wizard``: - -.. code-block:: python3 - - from __future__ import annotations # This can be removed in Python 3.10+ - - from dataclasses import dataclass, field - from typing_extensions import Annotated - - from dataclass_wizard import property_wizard - - - @dataclass - class Vehicle(metaclass=property_wizard): - wheels: Annotated[int | str, field(default=4)] - # or, alternatively: - # _wheels: int | str = 4 - - @property - def wheels(self) -> int: - return self._wheels - - @wheels.setter - def wheels(self, value: int | str): - self._wheels = int(value) - - - v = Vehicle() - print(v.wheels) # 4 - v.wheels = '6' - print(v.wheels) # 6 - - assert v.wheels == 6, 'Setter correctly handles type conversion' - -๐Ÿ“– For a deeper dive, visit the documentation on `field properties`_. - -.. rubric:: Generate Dataclass Schemas with CLI - -Quickly generate Python dataclasses from JSON input using the ``wiz-cli`` tool: - -.. code-block:: console - - $ echo '{"myFloat": "1.23", "Items": [{"created": "2021-01-01"}]}' | wiz gs - output.py - -.. code-block:: python3 - - from dataclasses import dataclass - from datetime import date - from typing import List, Union - - from dataclass_wizard import JSONWizard - - @dataclass - class Data(JSONWizard): - my_float: Union[float, str] - items: List['Item'] - - @dataclass - class Item: - created: date - -๐Ÿ“– Check out the full CLI documentation at wiz-cli_. - JSON Marshalling ---------------- @@ -1647,3 +1502,4 @@ This package was created with Cookiecutter_ and the `rnag/cookiecutter-pypackage .. _V1 Alias: https://dcw.ritviknag.com/en/latest/common_use_cases/v1_alias.html .. _Type Hooks: https://dcw.ritviknag.com/en/latest/advanced_usage/type_hooks.html .. _`ipaddress.IPv4Address`: https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address +.. _V1 Env Magic: https://dcw.ritviknag.com/en/latest/env_magic_v1.html