===============================
Desert: DRY deserialization
===============================
Desert generates serialization schemas for ``dataclasses`` and ``attrs`` classes. Writing
code that's DRY ("don't repeat yourself") helps avoid bugs and improve readability. Desert
helps you write code that's DRY.
Installation
============
::
pip install desert
or with `Poetry`_
::
poetry add desert
Usage
=========
..
start-basic-usage
A simple example models two ``Person`` objects in a ``Car``.
.. code-block:: python
from dataclasses import dataclass
# Or using attrs
# from attr import dataclass
from typing import List
import desert
@dataclass
class Person:
name: str
age: int
@dataclass
class Car:
passengers: List[Person]
# Load some simple data types.
data = {'passengers': [{'name': 'Alice', 'age': 21}, {'name': 'Bob', 'age': 22}]}
# Create a schema for the Car class.
schema = desert.schema(Car)
# Load the data.
car = schema.load(data)
assert car == Car(passengers=[Person(name='Alice', age=21), Person(name='Bob', age=22)])
..
end-basic-usage
Documentation
=============
https://desert.readthedocs.io/
Limitations
============
String annotations and forward references inside of functions are not supported.
Acknowledgements
=================
- This package began as an extension of marshmallow-dataclass_ to add support for attrs_.
.. _Poetry: https://poetry.eustace.io
.. _marshmallow-dataclass: https://pypi.org/project/marshmallow-dataclass/
.. _attrs: http://www.attrs.org/
2022.09.22 (2022-09-22)
-----------------------
Backward-incompatible Changes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Update all project dependencies and fix all deprecated warnings. Python 3.6
support was dropped to allow updating deprecated dependencies.
`#161 <https://github.com/python-desert/desert/issues/161>`_
Changes
^^^^^^^
- It is now possible to use `type-variant generics`_ in your dataclasses, such as ``Sequence``
or ``MutableSequence`` instead of ``List``, ``Mapping`` instead of ``Dict``, etc.
This allows you to hide implementation details from users of your dataclasses. If a field
in your dataclass works just as fine with a tuple as a list, you no longer need to force
your users to pass in a ``list`` just to satisfy type checkers.
For example, by using ``Mapping`` or ``MutableMapping``, users can pass ``OrderedDict`` to
a ``Dict`` attribute without MyPy complaining.
.. code-block:: python
@dataclass
class OldWay:
str_list: List[str]
num_map: Dict[str, float]
# MyPy will reject this even though Marshmallow works just fine. If you use
# type-variant generics, MyPy will accept this code.
instance = OldClass([], collections.ChainMap(MY_DEFAULTS))
@dataclass
class NewWay:
str_list: List[str] # Type-invariants still work
num_map: MutableMapping[str, float] # Now generics do too
.. _type-variant generics: https://mypy.readthedocs.io/en/stable/generics.html
`#140 <https://github.com/python-desert/desert/issues/140>`_
----
2020.11.18 (2020-11-18)
-----------------------
Changes
^^^^^^^
- Schemas no longer copy non-field dataclass attributes. Thanks to @sveinse for report and test.
`#79 <https://github.com/python-desert/desert/issues/79>`_
----
2020.01.06 (2020-01-06)
-----------------------
Changes
^^^^^^^
- Additional metadata are supported in ib() and fields(). Thanks to @sveinse for reporting and testing.
`#28 <https://github.com/python-desert/desert/issues/28>`_
----
2020.01.05 (2020-01-05)
-----------------------
Changes
^^^^^^^
- Add support for attrs factories that take ``self`` (``attr.Factory(..., takes_self=True)``).
`#27 <https://github.com/python-desert/desert/issues/27>`_
----
2020.01.04 (2020-01-04)
-----------------------
Changes
^^^^^^^
- Add support for Tuple[int, ...] per https://docs.python.org/3/library/typing.html#typing.Tuple
`#16 <https://github.com/python-desert/desert/issues/16>`_ Thanks to @sveinse for reporting and testing.
- Use module imports internally.
`#18 <https://github.com/python-desert/desert/issues/18>`_
- Desert version only needs to be updated in _version.py
`#19 <https://github.com/python-desert/desert/issues/19>`_
- Fix doctests.
`#20 <https://github.com/python-desert/desert/issues/20>`_
----
2020.01.03
--------------
Changes
^^^^^^^^
- ``Optional`` fields allow ``None``. `#11 <https://github.com/python-desert/desert/issues/11>`__. Thanks to @sveinse for reporting and testing.
2019.12.18
--------------
Changes
^^^^^^^
- Improve error message for unknown generics.
`#10 <https://github.com/python-desert/desert/pull/10>`_
2019.12.10
--------------
Changes
^^^^^^^
- Add ``UnknownType`` exception with better error message for types that should be generic.
`#8 <https://github.com/python-desert/desert/issues/8>`_
2019.12.09
--------------
Changes
^^^^^^^
- Marshmallow schema ``Meta`` arguments are accepted, allowing exclusion of unknown fields and other options.
`#3 <https://github.com/python-desert/desert/pull/3>`_
2019.11.06 (2019-11-06)
-----------------------
Changes
^^^^^^^
- Add twine and wheel development dependencies.
`#2 <https://github.com/python-desert/desert/issues/2>`_
----
2019.11.06 (2019-11-06)
-----------------------
Changes
^^^^^^^
- Switch to calver
Backward-incompatible Changes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Non-optional fields without a default or factory now have `required=True` so raise ``marshmallow.exceptions.ValidationError`` when missing.
`#1 <https://github.com/python-desert/desert/issues/1>`_
----
0.1.0 (2019-06-22)
------------------
Changes
^^^^^^^
- First release on PyPI.
---