diff --git a/README.rst b/README.rst index 863b200..93cc135 100644 --- a/README.rst +++ b/README.rst @@ -2,37 +2,30 @@ Dataclass Wizard ================ -Full documentation is available at `Read The Docs`_. (`Installation`_) - -.. image:: https://img.shields.io/pypi/v/dataclass-wizard.svg - :target: https://pypi.org/project/dataclass-wizard - -.. image:: https://img.shields.io/conda/vn/conda-forge/dataclass-wizard.svg - :target: https://anaconda.org/conda-forge/dataclass-wizard - -.. image:: https://img.shields.io/pypi/pyversions/dataclass-wizard.svg - :target: https://pypi.org/project/dataclass-wizard +๐Ÿ“š Full documentation available on `Read the Docs`_. (`Installation`_) .. image:: https://github.com/rnag/dataclass-wizard/actions/workflows/dev.yml/badge.svg - :target: https://github.com/rnag/dataclass-wizard/actions/workflows/dev.yml - -.. image:: https://readthedocs.org/projects/dataclass-wizard/badge/?version=latest - :target: https://dataclass-wizard.readthedocs.io/en/latest/?version=latest - :alt: Documentation Status + :target: https://github.com/rnag/dataclass-wizard/actions/workflows/dev.yml + :alt: CI Status +.. image:: https://img.shields.io/pypi/pyversions/dataclass-wizard.svg + :target: https://pypi.org/project/dataclass-wizard + :alt: Supported Python Versions -.. image:: https://pyup.io/repos/github/rnag/dataclass-wizard/shield.svg - :target: https://pyup.io/repos/github/rnag/dataclass-wizard/ - :alt: Updates - +.. image:: https://img.shields.io/pypi/l/dataclass-wizard.svg + :target: https://pypi.org/project/dataclass-wizard/ + :alt: License +.. image:: https://static.pepy.tech/badge/dataclass-wizard/month + :target: https://pepy.tech/project/dataclass-wizard + :alt: Monthly Downloads -**Dataclass Wizard** offers simple, elegant, *wizarding* ๐Ÿช„ tools for -interacting with Python's ``dataclasses``. +**Dataclass Wizard** ๐Ÿช„ +Simple, elegant *wizarding* tools for Pythonโ€™s ``dataclasses``. - It excels at โšก๏ธ lightning-fast de/serialization, effortlessly - converting dataclass instances to/from JSON -- perfect for - *nested dataclass* models! +Lightning-fast โšก, pure Python, and lightweight โ€” effortlessly +convert dataclass instances to/from JSON, perfect +for complex and *nested dataclass* models! ------------------- @@ -71,63 +64,96 @@ interacting with Python's ``dataclasses``. :local: :backlinks: none +Why Use Dataclass Wizard? +------------------------- + +Effortlessly handle complex data with one of the *fastest* and *lightweight* libraries available! Perfect for APIs, JSON wrangling, and more. + +- ๐Ÿš€ **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 + +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. Installation ------------ -Dataclass Wizard is available on `PyPI`_. Install with ``pip``: +*Dataclass Wizard* is available on `PyPI`_. You can install it with ``pip``: .. code-block:: console $ pip install dataclass-wizard -Also available on `conda`_ via `conda-forge`_. Install with ``conda``: +Also available on `conda`_ via `conda-forge`_. To install via ``conda``: .. code-block:: console $ conda install dataclass-wizard -c conda-forge -This library supports **Python 3.9** or higher. +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. + +For convenience, the table below outlines the last compatible version +of *Dataclass Wizard* for unsupported Python versions (3.6 โ€“ 3.8): +.. list-table:: + :header-rows: 1 + :widths: 15 35 15 + + * - Python Version + - Last Version of ``dataclass-wizard`` + - Python EOL + * - 3.6 + - 0.26.1_ + - 2021-12-23 + * - 3.7 + - 0.26.1_ + - 2023-06-27 + * - 3.8 + - 0.26.1_ + - 2024-10-07 + +.. _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/ -Features --------- +See `PyPI`_ for the latest version details. -Unlock the full potential of your `dataclasses`_ with these key features: - -- *Flexible (de)serialization*: Marshal dataclasses to/from JSON, TOML, YAML, or ``dict`` with ease. -- *Environment magic*: Map env vars and ``dotenv`` 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. +Wizard Mixins โœจ +---------------- -Wizard Mixins -------------- +In addition to ``JSONWizard``, these `Mixin`_ classes simplify common tasks and make your data handling *spellbindingly* efficient: -In addition to ``JSONWizard``, these handy Mixin_ classes simplify your workflow: +- ๐Ÿช„ `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``. -* `EnvWizard`_ โ€” Seamlessly load env variables and ``.env`` files into typed schemas. Supports secret files (file names as keys). -* `JSONPyWizard`_ โ€” A ``JSONWizard`` helper to skip *camelCase* and preserve keys as-is. -* `JSONListWizard`_ โ€” Extends ``JSONWizard`` to return `Container`_ objects instead of *lists* when possible. -* `JSONFileWizard`_ โ€” Effortlessly convert dataclass instances from/to JSON files on your local drive. -* `TOMLWizard`_ โ€” Easily map dataclass instances to/from TOML format. -* `YAMLWizard`_ โ€” Instantly convert dataclass instances to/from YAML, using the default ``PyYAML`` parser. +Supported Types ๐Ÿง‘โ€๐Ÿ’ป +-------------------- -Supported Types ---------------- +*Dataclass Wizard* supports: -The Dataclass Wizard library natively supports standard Python -collections like ``list``, ``dict``, and ``set``, along with -popular `typing`_ module Generics such as ``Union`` and ``Any``. -Additionally, it handles commonly used types like ``Enum``, -``defaultdict``, and date/time objects (e.g., ``datetime``) -with ease. +- ๐Ÿ“‹ **Collections**: Handle ``list``, ``dict``, and ``set`` effortlessly. +- ๐Ÿ”ข **Typing Generics**: Manage ``Union``, ``Any``, and other types from the `typing`_ module. +- ๐ŸŒŸ **Advanced Types**: Work with ``Enum``, ``defaultdict``, and ``datetime`` with ease. -For a detailed list of supported types and insights into the -load/dump process for special types, visit the -`Supported Types`_ section of the docs. +For more info, check out the `Supported Types`_ section in the docs for detailed insights into each type and the load/dump process! Usage and Examples ------------------ diff --git a/docs/dataclass_wizard.rst b/docs/dataclass_wizard.rst index 6e07e03..613f1f1 100644 --- a/docs/dataclass_wizard.rst +++ b/docs/dataclass_wizard.rst @@ -9,6 +9,7 @@ Subpackages dataclass_wizard.environ dataclass_wizard.utils + dataclass_wizard.v1 dataclass_wizard.wizard_cli Submodules @@ -94,6 +95,14 @@ dataclass\_wizard.lazy\_imports module :undoc-members: :show-inheritance: +dataclass\_wizard.loader\_selection module +------------------------------------------ + +.. automodule:: dataclass_wizard.loader_selection + :members: + :undoc-members: + :show-inheritance: + dataclass\_wizard.loaders module -------------------------------- diff --git a/requirements-bench.txt b/requirements-bench.txt index 06d49d0..64bf6c0 100644 --- a/requirements-bench.txt +++ b/requirements-bench.txt @@ -6,4 +6,4 @@ jsons==1.6.3 dataclass-factory==2.16 # pyup: ignore dacite==1.8.1 mashumaro==3.15 -pydantic==2.10.2 +pydantic==2.10.3