History

22.2.0 (2022-10-03)

• Potentially breaking: cattrs.Converter has been renamed to cattrs.BaseConverter, and cattrs.GenConverter to cattrs.Converter. The GenConverter name is still available for backwards compatibility, but is deprecated. If you were depending on functionality specific to the old Converter, change your import to from cattrs import BaseConverter.

• NewTypes are now supported by the cattrs.Converter. (#255, #94, #297)

• cattrs.Converter and cattrs.BaseConverter can now copy themselves using the copy method. (#284)

• Python 3.11 support.

• cattrs now supports un/structuring kw_only fields on attrs classes into/from dictionaries. (#247)

• PyPy support (and tests, using a minimal Hypothesis profile) restored. (#253)

• Fix propagating the detailed_validation flag to mapping and counter structuring generators.

• Fix typing.Set applying too broadly when used with the GenConverter.unstruct_collection_overrides parameter on Python versions below 3.9. Switch to typing.AbstractSet on those versions to restore the old behavior. (#264)

• Uncap the required Python version, to avoid problems detailed in https://iscinumpy.dev/post/bound-version-constraints/#pinning-the-python-version-is-special (#275)

• Fix Converter.register_structure_hook_factory and cattrs.gen.make_dict_unstructure_fn type annotations. (#281)

• Expose all error classes in the cattr.errors namespace. Note that it is deprecated, just use cattrs.errors. (#252)

• Fix generating structuring functions for types with quotes in the name. (#291 #277)

• Fix usage of notes for the final version of PEP 678, supported since exceptiongroup>=1.0.0rc4. (#303 <303)

22.1.0 (2022-04-03)

• cattrs now uses the CalVer versioning convention.

• cattrs now has a detailed validation mode, which is enabled by default. Learn more here. The old behavior can be restored by creating the converter with detailed_validation=False.

• attrs and dataclass structuring is now ~25% faster.

• Fix an issue structuring bare typing.List s on Pythons lower than 3.9. (#209)

• Fix structuring of non-parametrized containers like list/dict/... on Pythons lower than 3.9. (#218)

• Fix structuring bare typing.Tuple on Pythons lower than 3.9. (#218)

• Fix a wrong AttributeError of an missing __parameters__ attribute. This could happen when inheriting certain generic classes – for example typing.* classes are affected. (#217)

• Fix structuring of enum.Enum instances in typing.Literal types. (#231)

• Fix unstructuring all tuples - unannotated, variable-length, homogenous and heterogenous - to list. (#226)

• For forbid_extra_keys raise custom ForbiddenExtraKeyError instead of generic Exception. (#225)

• All preconf converters now support loads and dumps directly. See an example here.

• Fix mappings with byte keys for the orjson, bson and tomlkit converters. (#241)

1.10.0 (2022-01-04)

• Add PEP 563 (string annotations) support for dataclasses. (#195)

• Fix handling of dictionaries with string Enum keys for bson, orjson, and tomlkit.

• Rename the cattr.gen.make_dict_unstructure_fn.omit_if_default parameter to _cattrs_omit_if_default, for consistency. The omit_if_default parameters to GenConverter and override are unchanged.

• Following the changes in attrs 21.3.0, add a cattrs package mirroring the existing cattr package. Both package names may be used as desired, and the cattr package isn’t going away.

1.9.0 (2021-12-06)

• Python 3.10 support, including support for the new union syntax (A | B vs Union[A, B]).

• The GenConverter can now properly structure generic classes with generic collection fields. (#149)

• omit=True now also affects generated structuring functions. (#166)

• cattr.gen.{make_dict_structure_fn, make_dict_unstructure_fn} now resolve type annotations automatically when PEP 563 is used. (#169)

• Protocols are now unstructured as their runtime types. (#177)

• Fix an issue generating structuring functions with renaming and _cattrs_forbid_extra_keys=True. (#190)

1.8.0 (2021-08-13)

• Fix GenConverter mapping structuring for unannotated dicts on Python 3.8. (#151)

• The source code for generated un/structuring functions is stored in the linecache cache, which enables more informative stack traces when un/structuring errors happen using the GenConverter. This behavior can optionally be disabled to save memory.

• Support using the attr converter callback during structure. By default, this is a method of last resort, but it can be elevated to the default by setting prefer_attrib_converters=True on Converter or GenConverter. (#138)

• Fix structuring recursive classes. (#159)

• Converters now support un/structuring hook factories. This is the most powerful and complex venue for customizing un/structuring. This had previously been an internal feature.

• The Common Usage Examples documentation page now has a section on advanced hook factory usage.

• cattr.override now supports the omit parameter, which makes cattrs skip the atribute entirely when unstructuring.

• The cattr.preconf.bson module is now tested against the bson module bundled with the pymongo package, because that package is much more popular than the standalone PyPI bson package.

1.7.1 (2021-05-28)

• Literal s are not supported on Python 3.9.0 (supported on 3.9.1 and later), so we skip importing them there. (#150)

1.7.0 (2021-05-26)

• cattr.global_converter (which provides cattr.unstructure, cattr.structure etc.) is now an instance of cattr.GenConverter.

• Literal s are now supported and validated when structuring.

• Fix dependency metadata information for attrs. (#147)

• Fix GenConverter mapping structuring for unannotated dicts. (#148)

1.6.0 (2021-04-28)

• cattrs now uses Poetry.

• GenConverter mapping structuring is now ~25% faster, and unstructuring heterogenous tuples is significantly faster.

• Add cattr.preconf. This package contains modules for making converters for particular serialization libraries. We currently support the standard library json, and third-party ujson, orjson, msgpack, bson, pyyaml and tomlkit libraries.

1.5.0 (2021-04-15)

• Fix an issue with GenConverter unstructuring attrs classes and dataclasses with generic fields. (#65)

• GenConverter has support for easy overriding of collection unstructuring types (for example, unstructure all sets to lists) through its unstruct_collection_overrides argument. (#137)

• Unstructuring mappings with GenConverter is significantly faster.

• GenConverter supports strict handling of unexpected dictionary keys through its forbid_extra_keys argument. (#142)

1.4.0 (2021-03-21)

• Fix an issue with GenConverter un/structuring hooks when a function hook is registered after the converter has already been used.

• Add support for collections.abc.{Sequence, MutableSequence, Set, MutableSet}. These should be used on 3.9+ instead of their typing alternatives, which are deprecated. (#128)

• The GenConverter will unstructure iterables (list[T], tuple[T, ...], set[T]) using their type argument instead of the runtime class if its elements, if possible. These unstructuring operations are up to 40% faster. (#129)

• Flesh out Converter and GenConverter initializer type annotations. (#131)

• Add support for typing.Annotated on Python 3.9+. cattrs will use the first annotation present. cattrs specific annotations may be added in the future. (#127)

• Add support for dataclasses. (#43)

1.3.0 (2021-02-25)

• cattrs now has a benchmark suite to help make and keep cattrs the fastest it can be. The instructions on using it can be found under the Benchmarking <https://cattrs.readthedocs.io/en/latest/benchmarking.html> section in the docs. (#123)

• Fix an issue unstructuring tuples of non-primitives. (#125)

• cattrs now calls attr.resolve_types on attrs classes when registering un/structuring hooks.

• GenConverter structuring and unstructuring of attrs classes is significantly faster.

1.2.0 (2021-01-31)

• converter.unstructure now supports an optional parameter, unstructure_as, which can be used to unstructure something as a different type. Useful for unions.

• Improve support for union un/structuring hooks. Flesh out docs for advanced union handling. (#115)

• Fix GenConverter behavior with inheritance hierarchies of attrs classes. (#117) (#116)

• Refactor GenConverter.un/structure_attrs_fromdict into GenConverter.gen_un/structure_attrs_fromdict to allow calling back to Converter.un/structure_attrs_fromdict without sideeffects. (#118)

1.1.2 (2020-11-29)

• The default disambiguator will not consider non-required fields any more. (#108)

• Fix a couple type annotations. (#107) (#105)

• Fix a GenConverter unstructuring issue and tests.

1.1.1 (2020-10-30)

• Add metadata for supported Python versions. (#103)

1.1.0 (2020-10-29)

• Python 2, 3.5 and 3.6 support removal. If you need it, use a version below 1.1.0.

• Python 3.9 support, including support for built-in generic types (list[int] vs typing.List[int]).

• cattrs now includes functions to generate specialized structuring and unstructuring hooks. Specialized hooks are faster and support overrides (omit_if_default and rename). See the cattr.gen module.

• cattrs now includes a converter variant, cattr.GenConverter, that automatically generates specialized hooks for attrs classes. This converter will become the default in the future.

• Generating specialized structuring hooks now invokes attr.resolve_types on a class if the class makes use of the new PEP 563 annotations.

• cattrs now depends on attrs >= 20.1.0, because of attr.resolve_types.

• Specialized hooks now support generic classes. The default converter will generate and use a specialized hook upon encountering a generic class.

1.0.0 (2019-12-27)

• attrs classes with private attributes can now be structured by default.

• Structuring from dictionaries is now more lenient: extra keys are ignored.

• cattrs has improved type annotations for use with Mypy.

• Unstructuring sets and frozensets now works properly.

0.9.1 (2019-10-26)

• Python 3.8 support.

0.9.0 (2018-07-22)

• Python 3.7 support.

0.8.1 (2018-06-19)

• The disambiguation function generator now supports unions of attrs classes and NoneType.

0.8.0 (2018-04-14)

• Distribution fix.

0.7.0 (2018-04-12)

• Removed the undocumented Converter.unstruct_strat property setter.

• Removed the ability to set the Converter.structure_attrs instance field.

  As an alternative, create a new Converter::

  
  

  .. code-block:: python

  
  

  >>> converter = cattr.Converter(unstruct_strat=cattr.UnstructureStrategy.AS_TUPLE)

• Some micro-optimizations were applied; a structure(unstructure(obj)) roundtrip is now up to 2 times faster.

0.6.0 (2017-12-25)

• Packaging fixes. (#17)

0.5.0 (2017-12-11)

• structure/unstructure now supports using functions as well as classes for deciding the appropriate function.

• added Converter.register_structure_hook_func, to register a function instead of a class for determining handler func.

• added Converter.register_unstructure_hook_func, to register a function instead of a class for determining handler func.

• vendored typing is no longer needed, nor provided.

• Attributes with default values can now be structured if they are missing in the input. (#15)

• Optional attributes can no longer be structured if they are missing in the input.

  In other words, this no longer works:

  
  

  .. code-block:: python

  
  

  @attr.s

  class A:

  a: Optional[int] = attr.ib()

  
  

  >>> cattr.structure({}, A)

  
  

• cattr.typed removed since the functionality is now present in attrs itself. Replace instances of cattr.typed(type) with attr.ib(type=type).

0.4.0 (2017-07-17)

• Converter.loads is now Converter.structure, and Converter.dumps is now Converter.unstructure.

• Python 2.7 is supported.

• Moved cattr.typing to cattr.vendor.typing to support different vendored versions of typing.py for Python 2 and Python 3.

• Type metadata can be added to attrs classes using cattr.typed.

0.3.0 (2017-03-18)

• Python 3.4 is no longer supported.

• Introduced cattr.typing for use with Python versions 3.5.2 and 3.6.0.

• Minor changes to work with newer versions of typing.

  • Bare Optionals are not supported any more (use Optional[Any]).

• Attempting to load unrecognized classes will result in a ValueError, and a helpful message to register a loads hook.

• Loading attrs classes is now documented.

• The global converter is now documented.

• cattr.loads_attrs_fromtuple and cattr.loads_attrs_fromdict are now exposed.

0.2.0 (2016-10-02)

• Tests and documentation.

0.1.0 (2016-08-13)

• First release on PyPI.