cleanup docs

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)
 -------------------
 

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: <Car.SUV: 'Toyota 4Runner'>
-    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