History#
23.2.0 (UNRELEASED)#
23.1.2 (2023-06-02)#
Improve
typing_extensions
version bound. (#372)
23.1.1 (2023-05-30)#
23.1.0 (2023-05-30)#
Introduce the
cattrs.transform_error
helper function for formatting validation exceptions. (258 342)Add support for
typing.TypedDict
andtyping_extensions.TypedDict
. (#296 #364)Introduce
override.struct_hook
andoverride.unstruct_hook
. Learn more here. (#326)Fix generating structuring functions for types with angle brackets (
<>
) and pipe symbols (|
) in the name. (#319 #327)pathlib.Path
is now supported by default. (#81)Add
cbor2
serialization library to thecattr.preconf
package.Add optional dependencies for
cattrs.preconf
third-party libraries. (#337)All preconf converters now allow overriding the default
unstruct_collection_overrides
inmake_converter
. (#350 #353)Subclasses structuring and unstructuring is now supported via a custom
include_subclasses
strategy. (#312)Add support for
typing_extensions.Annotated
when the python version is less than3.9
. (#366)Add unstructuring and structuring support for the standard library
deque
. (#355)
22.2.0 (2022-10-03)#
Potentially breaking:
cattrs.Converter
has been renamed tocattrs.BaseConverter
, andcattrs.GenConverter
tocattrs.Converter
. TheGenConverter
name is still available for backwards compatibility, but is deprecated. If you were depending on functionality specific to the oldConverter
, change your import tofrom cattrs import BaseConverter
.NewTypes are now supported by the
cattrs.Converter
. (#255 #94 #297)cattrs.Converter
andcattrs.BaseConverter
can now copy themselves using thecopy
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 theGenConverter.unstruct_collection_overrides
parameter on Python versions below 3.9. Switch totyping.AbstractSet
on those versions to restore the old behavior. (#264)Uncap the required Python version, to avoid problems detailed here (#275)
Fix
Converter.register_structure_hook_factory
andcattrs.gen.make_dict_unstructure_fn
type annotations. (#281)Expose all error classes in the
cattr.errors
namespace. Note that it is deprecated, just usecattrs.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)
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 exampletyping.*
classes are affected. (#217)Fix structuring of
enum.Enum
instances intyping.Literal
types. (#231)Fix unstructuring all tuples - unannotated, variable-length, homogenous and heterogenous - to
list
. (#226)For
forbid_extra_keys
raise customForbiddenExtraKeyError
instead of genericException
. (#225)All preconf converters now support
loads
anddumps
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. Theomit_if_default
parameters toGenConverter
andoverride
are unchanged.Following the changes in attrs 21.3.0, add a
cattrs
package mirroring the existingcattr
package. Both package names may be used as desired, and thecattr
package isn’t going away.
1.9.0 (2021-12-06)#
Python 3.10 support, including support for the new union syntax (
A | B
vsUnion[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 theGenConverter
. 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
onConverter
orGenConverter
. (#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 theomit
parameter, which makes cattrs skip the atribute entirely when unstructuring.The
cattr.preconf.bson
module is now tested against thebson
module bundled with thepymongo
package, because that package is much more popular than the standalone PyPIbson
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 providescattr.unstructure
,cattr.structure
etc.) is now an instance ofcattr.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 libraryjson
, and third-partyujson
,orjson
,msgpack
,bson
,pyyaml
andtomlkit
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 itsunstruct_collection_overrides
argument. (#137)Unstructuring mappings with
GenConverter
is significantly faster.GenConverter
supports strict handling of unexpected dictionary keys through itsforbid_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 theirtyping
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
andGenConverter
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 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](https://github.com/python-attrs/cattrs/pull/117 #116)Refactor
GenConverter.un/structure_attrs_fromdict
intoGenConverter.gen_un/structure_attrs_fromdict
to allow calling back toConverter.un/structure_attrs_fromdict
without sideeffects. (#118)
1.1.2 (2020-11-29)#
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]
vstyping.List[int]
).cattrs now includes functions to generate specialized structuring and unstructuring hooks. Specialized hooks are faster and support overrides (
omit_if_default
andrename
). See thecattr.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.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.cattr.typed
removed since the functionality is now present in attrs itself. Replace instances ofcattr.typed(type)
withattr.ib(type=type)
.
0.4.0 (2017-07-17)#
Converter.loads
is nowConverter.structure
, andConverter.dumps
is nowConverter.unstructure
.Python 2.7 is supported.
Moved
cattr.typing
tocattr.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
andcattr.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.