From 45acfa1f43db99b3d7a580d4cce45e0870a5730c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tin=20Tvrtkovi=C4=87?= <tinchester@gmail.com>
Date: Thu, 25 Jul 2024 00:00:47 +0200
Subject: [PATCH] Docs and changelog

---
 HISTORY.md           |  7 +++++--
 docs/defaulthooks.md | 14 +++++++++-----
 2 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/HISTORY.md b/HISTORY.md
index 97997350..17612f43 100644
--- a/HISTORY.md
+++ b/HISTORY.md
@@ -23,12 +23,15 @@ Our backwards-compatibility policy can be found [here](https://github.com/python
 - Introduce {meth}`BaseConverter.get_structure_hook` and {meth}`BaseConverter.get_unstructure_hook` methods.
   ([#432](https://github.com/python-attrs/cattrs/issues/432) [#472](https://github.com/python-attrs/cattrs/pull/472))
 - {meth}`BaseConverter.register_structure_hook`, {meth}`BaseConverter.register_unstructure_hook`,
-{meth}`BaseConverter.register_unstructure_hook_factory` and {meth}`BaseConverter.register_structure_hook_factory`
-can now be used as decorators and have gained new features.
+  {meth}`BaseConverter.register_unstructure_hook_factory` and {meth}`BaseConverter.register_structure_hook_factory`
+  can now be used as decorators and have gained new features.
   See [here](https://catt.rs/en/latest/customizing.html#use-as-decorators) and [here](https://catt.rs/en/latest/customizing.html#id1) for more details.
   ([#487](https://github.com/python-attrs/cattrs/pull/487))
 - Introduce and [document](https://catt.rs/en/latest/customizing.html#customizing-collections) the {mod}`cattrs.cols` module for better collection customizations.
   ([#504](https://github.com/python-attrs/cattrs/issues/504) [#540](https://github.com/python-attrs/cattrs/pull/540))
+- Enhance the {func}`cattrs.cols.is_mapping` predicate function to also cover virtual subclasses of `abc.Mapping`.
+  This enables map classes from libraries such as _immutables_ or _sortedcontainers_ to structure out-of-the-box.
+  ([#555](https://github.com/python-attrs/cattrs/issues/555) [#556](https://github.com/python-attrs/cattrs/pull/556))
 - Introduce the [_msgspec_](https://jcristharif.com/msgspec/) {mod}`preconf converter <cattrs.preconf.msgspec>`.
   Only JSON is supported for now, with other formats supported by _msgspec_ to come later.
   ([#481](https://github.com/python-attrs/cattrs/pull/481))
diff --git a/docs/defaulthooks.md b/docs/defaulthooks.md
index 27997380..46b1fc56 100644
--- a/docs/defaulthooks.md
+++ b/docs/defaulthooks.md
@@ -156,13 +156,13 @@ A useful use case for unstructuring collections is to create a deep copy of a co
 ### Dictionaries
 
 Dictionaries can be produced from other mapping objects.
-More precisely, the unstructured object must expose an [`items()`](https://docs.python.org/3/library/stdtypes.html#dict.items) method producing an iterable of key-value tuples, and be able to be passed to the `dict` constructor as an argument.
+More precisely, the unstructured object must expose an [`items()`](https://docs.python.org/3/library/stdtypes.html#dict.items) method producing an iterable of key-value tuples,
+and be able to be passed to the `dict` constructor as an argument.
 Types converting to dictionaries are:
 
-- `typing.Dict[K, V]`
-- `typing.MutableMapping[K, V]`
-- `typing.Mapping[K, V]`
-- `dict[K, V]`
+- `dict[K, V]` and `typing.Dict[K, V]`
+- `collections.abc.MutableMapping[K, V]` and `typing.MutableMapping[K, V]`
+- `collections.abc.Mapping[K, V]` and `typing.Mapping[K, V]`
 
 In all cases, a new dict will be returned, so this operation can be used to copy a mapping into a dict.
 Any type parameters set to `typing.Any` will be passed through unconverted.
@@ -183,6 +183,10 @@ Both keys and values are converted.
 {'1': None, '2': 2}
 ```
 
+### Virtual Subclasses of [`abc.Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping) and [`abc.MutableMapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping)
+
+If a class declares itself a virtual subclass of `collections.abc.Mapping` or `collections.abc.MutableMapping` and its initializer accepts a dictionary,
+_cattrs_ will be able to structure it by default.
 
 ### Homogeneous and Heterogeneous Tuples