Structure sequences into tuples

Author: Tinche

HISTORY.md

@@ -13,7 +13,10 @@ Our backwards-compatibility policy can be found [here](https://github.com/python
 
 ## 25.2.0 (unreleased)
 
-- Add a `use_alias` parameter to {class}`cattrs.Converter`. 
+- **Potentially breaking**: Sequences are now structured into tuples.
+  This allows hashability, better immutability and is more consistent with the [`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence) type.
+  See [Migrations](https://catt.rs/en/latest/migrations.html#sequences-structuring-into-tuples) for steps to restore legacy behavior.
+- Add a `use_alias` parameter to {class}`cattrs.Converter`.
   {func}`cattrs.gen.make_dict_unstructure_fn_from_attrs`, {func}`cattrs.gen.make_dict_unstructure_fn`,
   {func}`cattrs.gen.make_dict_structure_fn_from_attrs`, {func}`cattrs.gen.make_dict_structure_fn`
   and {func}`cattrs.gen.typeddicts.make_dict_structure_fn` will use the value for the `use_alias` parameter from the given converter by default now.

docs/customizing.md

@@ -413,6 +413,7 @@ Available predicates are:
 - {meth}`is_any_set`
 - {meth}`is_frozenset`
 - {meth}`is_set`
+- {meth}`is_mutable_sequence`
 - {meth}`is_sequence`
 - {meth}`is_mapping`
 - {meth}`is_namedtuple`
@@ -432,6 +433,7 @@ Available hook factories are:
 
 - {meth}`iterable_unstructure_factory`
 - {meth}`list_structure_factory`
+- {meth}`homogenous_tuple_structure_factory`
 - {meth}`namedtuple_structure_factory`
 - {meth}`namedtuple_unstructure_factory`
 - {meth}`namedtuple_dict_structure_factory`
@@ -442,15 +444,15 @@ Available hook factories are:
 
 Additional predicates and hook factories will be added as requested.
 
-For example, by default sequences are structured from any iterable into lists.
+For example, by default mutable sequences are structured from any iterable into lists.
 This may be too lax, and additional validation may be applied by wrapping the default list structuring hook factory.
 
 ```{testcode} list-customization
-from cattrs.cols import is_sequence, list_structure_factory
+from cattrs.cols import is_mutable_sequence, list_structure_factory
 
 c = Converter()
 
-@c.register_structure_hook_factory(is_sequence)
+@c.register_structure_hook_factory(is_mutable_sequence)
 def strict_list_hook_factory(type, converter):
 
     # First, we generate the default hook...
@@ -466,7 +468,7 @@ def strict_list_hook_factory(type, converter):
     return strict_list_hook
 ```
 
-Now, all sequence structuring will be stricter:
+Now, all mutable sequence structuring will be stricter:
 
 ```{doctest} list-customization
 >>> c.structure({"a", "b", "c"}, list[str])
@@ -477,6 +479,9 @@ ValueError: Not a list!
 
 ```{versionadded} 24.1.0
 
+```
+```{versionchanged} 25.2.0
+Added the {meth}`is_mutable_sequence` predicate and {meth}`homogenous_tuple_structure_factory` hook factory.
 ```
 
 ### Customizing Named Tuples

docs/migrations.md

@@ -3,6 +3,20 @@
 _cattrs_ sometimes changes in backwards-incompatible ways.
 This page contains guidance for changes and workarounds for restoring legacy behavior.
 
+## 25.2.0
+
+### Sequences structuring into tuples
+
+Sequences were changed to structure into tuples instead of lists.
+
+The old behavior can be restored by registering the `list_structure_factory` using the `is_sequence` predicate on a converter.
+
+```python
+>>> from cattrs.cols import is_sequence, list_structure_factory
+
+>>> converter.register_structure_hook_factory(is_sequence, list_structure_factory)
+```
+
 ## 24.2.0
 
 ### The default structure hook fallback factory
@@ -24,4 +38,4 @@ The old behavior can be restored by explicitly passing in the old hook fallback
 
 The internal `cattrs.gen.MappingStructureFn` and `cattrs.gen.DictStructureFn` types were replaced by a more general type, `cattrs.SimpleStructureHook[In, T]`.
 If you were using `MappingStructureFn`, use `SimpleStructureHook[Mapping[Any, Any], T]` instead.
-If you were using `DictStructureFn`, use `SimpleStructureHook[Mapping[str, Any], T]` instead.
+If you were using `DictStructureFn`, use `SimpleStructureHook[Mapping[str, Any], T]` instead.

src/cattrs/_compat.py

@@ -306,34 +306,42 @@ def get_notrequired_base(type) -> Union[Any, NothingType]:
     return NOTHING
 
 
+def is_mutable_sequence(type: Any) -> bool:
+    """A predicate function for mutable sequences.
+
+    Matches lists, mutable sequences, and deques.
+    """
+    origin = getattr(type, "__origin__", None)
+    return (
+        type in (List, list, TypingMutableSequence, AbcMutableSequence, deque, Deque)
+        or (
+            type.__class__ is _GenericAlias
+            and (
+                ((origin is not tuple) and is_subclass(origin, TypingMutableSequence))
+                or (origin is tuple and type.__args__[1] is ...)
+            )
+        )
+        or (origin in (list, deque, AbcMutableSequence))
+    )
+
+
 def is_sequence(type: Any) -> bool:
     """A predicate function for sequences.
 
     Matches lists, sequences, mutable sequences, deques and homogenous
     tuples.
     """
     origin = getattr(type, "__origin__", None)
-    return (
-        type
-        in (
-            List,
-            list,
-            TypingSequence,
-            TypingMutableSequence,
-            AbcMutableSequence,
-            tuple,
-            Tuple,
-            deque,
-            Deque,
-        )
+    return is_mutable_sequence(type) or (
+        type in (TypingSequence, tuple, Tuple)
         or (
             type.__class__ is _GenericAlias
             and (
                 ((origin is not tuple) and is_subclass(origin, TypingSequence))
                 or (origin is tuple and type.__args__[1] is ...)
             )
         )
-        or (origin in (list, deque, AbcMutableSequence, AbcSequence))
+        or (origin is AbcSequence)
         or (origin is tuple and type.__args__[1] is ...)
     )
 

src/cattrs/cols.py

@@ -25,6 +25,7 @@
     is_frozenset,
     is_mapping,
     is_sequence,
+    is_mutable_sequence,
     is_subclass,
 )
 from ._compat import is_mutable_set as is_set
@@ -52,10 +53,12 @@
     "is_frozenset",
     "is_mapping",
     "is_namedtuple",
+    "is_mutable_sequence",
     "is_sequence",
     "is_set",
     "iterable_unstructure_factory",
     "list_structure_factory",
+    "homogenous_tuple_structure_factory",
     "mapping_structure_factory",
     "mapping_unstructure_factory",
     "namedtuple_dict_structure_factory",
@@ -151,6 +154,47 @@ def structure_list(
     return structure_list
 
 
+def homogenous_tuple_structure_factory(
+    type: type, converter: BaseConverter
+) -> StructureHook:
+    """A hook factory for homogenous (all elements the same, indeterminate length) tuples.
+
+    Converts any given iterable into a tuple.
+    """
+
+    if is_bare(type) or type.__args__[0] in ANIES:
+
+        def structure_tuple(obj: Iterable[T], _: type = type) -> tuple[T, ...]:
+            return tuple(obj)
+
+        return structure_tuple
+
+    elem_type = type.__args__[0]
+
+    try:
+        handler = converter.get_structure_hook(elem_type)
+    except RecursionError:
+        # Break the cycle by using late binding.
+        handler = converter.structure
+
+    if converter.detailed_validation:
+
+        # We have to structure into a list first anyway.
+        list_structure = list_structure_factory(type, converter)
+
+        def structure_tuple(obj: Iterable[T], _: type = type) -> tuple[T, ...]:
+            return tuple(list_structure(obj, _))
+
+    else:
+
+        def structure_tuple(
+            obj: Iterable[T], _: type = type, _handler=handler, _elem_type=elem_type
+        ) -> tuple[T, ...]:
+            return tuple([_handler(e, _elem_type) for e in obj])
+
+    return structure_tuple
+
+
 def namedtuple_unstructure_factory(
     cl: type[tuple], converter: BaseConverter, unstructure_to: Any = None
 ) -> UnstructureHook:

src/cattrs/converters.py

@@ -46,22 +46,24 @@
     is_mutable_set,
     is_optional,
     is_protocol,
-    is_sequence,
     is_tuple,
     is_typeddict,
     is_union_type,
     signature,
+    is_mutable_sequence,
 )
 from .cols import (
     defaultdict_structure_factory,
     is_defaultdict,
     is_namedtuple,
     iterable_unstructure_factory,
     list_structure_factory,
+    homogenous_tuple_structure_factory,
     mapping_structure_factory,
     mapping_unstructure_factory,
     namedtuple_structure_factory,
     namedtuple_unstructure_factory,
+    is_sequence,
 )
 from .disambiguators import create_default_dis_func, is_supported_union
 from .dispatch import (
@@ -271,7 +273,8 @@ def __init__(
                 ),
                 (is_literal, self._structure_simple_literal),
                 (is_literal_containing_enums, self._structure_enum_literal),
-                (is_sequence, list_structure_factory, "extended"),
+                (is_sequence, homogenous_tuple_structure_factory, "extended"),
+                (is_mutable_sequence, list_structure_factory, "extended"),
                 (is_deque, self._structure_deque),
                 (is_mutable_set, self._structure_set),
                 (is_frozenset, self._structure_frozenset),

tests/test_cols.py

@@ -1,6 +1,6 @@
 """Tests for the `cattrs.cols` module."""
 
-from collections.abc import Set
+from collections.abc import MutableSequence, Sequence, Set
 from typing import Dict
 
 from immutables import Map
@@ -11,6 +11,8 @@
     is_any_set,
     iterable_unstructure_factory,
     mapping_unstructure_factory,
+    is_sequence,
+    list_structure_factory,
 )
 
 from ._compat import is_py310_plus
@@ -53,3 +55,23 @@ def test_mapping_unstructure_to(genconverter: Converter):
     """`unstructure_to` works."""
     hook = mapping_unstructure_factory(Dict[str, str], genconverter, unstructure_to=Map)
     assert hook({"a": "a"}).__class__ is Map
+
+
+def test_structure_sequences(converter: BaseConverter):
+    """Sequences are structured to tuples."""
+
+    assert converter.structure(["1", 2, 3.0], Sequence[int]) == (1, 2, 3)
+
+
+def test_structure_sequences_override(converter: BaseConverter):
+    """Sequences can be overriden to structure to lists, as previously."""
+
+    converter.register_structure_hook_factory(is_sequence, list_structure_factory)
+
+    assert converter.structure(["1", 2, 3.0], Sequence[int]) == [1, 2, 3]
+
+
+def test_structure_mut_sequences(converter: BaseConverter):
+    """Mutable sequences are structured to lists."""
+
+    assert converter.structure(["1", 2, 3.0], MutableSequence[int]) == [1, 2, 3]