Add collections.Counter support (#692)

Author: yukinarit

README.md

@@ -68,7 +68,7 @@ Happy coding with pyserde! 🚀
         - `list`, `collections.abc.Sequence`, `collections.abc.MutableSequence`, `tuple`
         - `set`, `collections.abc.Set`, `collections.abc.MutableSet`
         - `dict`, `collections.abc.Mapping`, `collections.abc.MutableMapping`
-        - [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset), [`defaultdict`](https://docs.python.org/3/library/collections.html#collections.defaultdict), [`deque`](https://docs.python.org/3/library/collections.html#collections.deque)
+        - [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset), [`defaultdict`](https://docs.python.org/3/library/collections.html#collections.defaultdict), [`deque`](https://docs.python.org/3/library/collections.html#collections.deque), [`Counter`](https://docs.python.org/3/library/collections.html#collections.Counter)
     - [`typing.Optional`](https://docs.python.org/3/library/typing.html#typing.Optional)
     - [`typing.Union`](https://docs.python.org/3/library/typing.html#typing.Union)
     - User defined class with [`@dataclass`](https://docs.python.org/3/library/dataclasses.html)

docs/en/types.md

@@ -10,6 +10,7 @@ Here is the list of the supported types. See the simple example for each type in
     * [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset), [^3]
     * [`defaultdict`](https://docs.python.org/3/library/collections.html#collections.defaultdict) [^4]
     * [`deque`](https://docs.python.org/3/library/collections.html#collections.deque) [^25]
+    * [`Counter`](https://docs.python.org/3/library/collections.html#collections.Counter) [^26]
 * [`typing.Optional`](https://docs.python.org/3/library/typing.html#typing.Optional) [^5]
 * [`typing.Union`](https://docs.python.org/3/library/typing.html#typing.Union) [^6] [^7] [^8]
 * User defined class with [`@dataclass`](https://docs.python.org/3/library/dataclasses.html) [^9] [^10]
@@ -151,3 +152,5 @@ If you need to use a type which is currently not supported in the standard libra
 [^24]: See [examples/type_sqlalchemy.py](https://github.com/yukinarit/pyserde/blob/main/examples/type_sqlalchemy.py)
 
 [^25]: See [examples/deque.py](https://github.com/yukinarit/pyserde/blob/main/examples/deque.py)
+
+[^26]: See [examples/counter.py](https://github.com/yukinarit/pyserde/blob/main/examples/counter.py)

docs/ja/types.md

@@ -10,6 +10,7 @@
     * [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset) [^3]
     * [`defaultdict`](https://docs.python.org/3/library/collections.html#collections.defaultdict) [^4]
     * [`deque`](https://docs.python.org/3/library/collections.html#collections.deque) [^25]
+    * [`Counter`](https://docs.python.org/3/library/collections.html#collections.Counter) [^26]
 * [`typing.Optional`](https://docs.python.org/3/library/typing.html#typing.Optional)[^5]
 * [`typing.Union`](https://docs.python.org/3/library/typing.html#typing.Union) [^6] [^7] [^8]
 * [`@dataclass`](https://docs.python.org/3/library/dataclasses.html) を用いたユーザ定義クラス [^9] [^10]
@@ -156,3 +157,5 @@ SQLAlchemy宣言的データクラスマッピング統合の実験的サポー
 [^24]: [examples/type_sqlalchemy.py](https://github.com/yukinarit/pyserde/blob/main/examples/type_sqlalchemy.py) を参照
 
 [^25]: [examples/deque.py](https://github.com/yukinarit/pyserde/blob/main/examples/deque.py) を参照
+
+[^26]: [examples/counter.py](https://github.com/yukinarit/pyserde/blob/main/examples/counter.py) を参照

examples/counter.py

@@ -0,0 +1,28 @@
+from collections import Counter
+
+from serde import serde
+from serde.json import from_json, to_json
+
+
+@serde
+class WordCount:
+    counts: Counter[str]
+
+
+def main() -> None:
+    # Create a Counter from a list of words
+    wc = WordCount(counts=Counter(["apple", "banana", "apple", "cherry", "banana", "apple"]))
+    print(f"Original: {wc}")
+    print(f"Into Json: {to_json(wc)}")
+
+    # Deserialize from JSON
+    s = '{"counts": {"apple": 3, "banana": 2, "cherry": 1}}'
+    print(f"From Json: {from_json(WordCount, s)}")
+
+    # Counter methods still work after deserialization
+    wc2 = from_json(WordCount, s)
+    print(f"Most common: {wc2.counts.most_common(2)}")
+
+
+if __name__ == "__main__":
+    main()

serde/compat.py

@@ -14,7 +14,7 @@
 import uuid
 import typing
 import typing_extensions
-from collections import defaultdict, deque
+from collections import defaultdict, deque, Counter
 from collections.abc import Iterator, Sequence, MutableSequence
 from collections.abc import Mapping, MutableMapping, Set, MutableSet
 from dataclasses import is_dataclass
@@ -218,6 +218,13 @@ def typename(typ: Any, with_typing_module: bool = False) -> str:
             return f"deque[{et}]"
         else:
             return "deque"
+    elif is_counter(typ):
+        args = type_args(typ)
+        if args:
+            et = thisfunc(args[0])
+            return f"Counter[{et}]"
+        else:
+            return "Counter"
     elif is_tuple(typ):
         args = type_args(typ)
         if args:
@@ -373,6 +380,11 @@ def recursive(cls: Union[type[Any], Any]) -> None:
             args = type_args(cls)
             if args:
                 recursive(args[0])
+        elif is_counter(cls):
+            lst.add(Counter)
+            args = type_args(cls)
+            if args:
+                recursive(args[0])
         elif is_tuple(cls):
             lst.add(tuple)
             for arg in type_args(cls):
@@ -419,7 +431,7 @@ def recursive(cls: TypeLike) -> None:
             args = type_args(cls)
             if args:
                 recursive(args[0])
-        elif is_list(cls) or is_set(cls) or is_deque(cls):
+        elif is_list(cls) or is_set(cls) or is_deque(cls) or is_counter(cls):
             args = type_args(cls)
             if args:
                 recursive(args[0])
@@ -462,7 +474,7 @@ def recursive(cls: Union[type[Any], Any]) -> None:
             args = type_args(cls)
             if args:
                 recursive(args[0])
-        elif is_list(cls) or is_set(cls) or is_deque(cls):
+        elif is_list(cls) or is_set(cls) or is_deque(cls) or is_counter(cls):
             args = type_args(cls)
             if args:
                 recursive(args[0])
@@ -830,6 +842,40 @@ def is_bare_deque(typ: type[Any]) -> bool:
     return typ is deque
 
 
+@cache
+def is_counter(typ: type[Any]) -> bool:
+    """
+    Test if the type is `collections.Counter`.
+
+    >>> is_counter(Counter[str])
+    True
+    >>> is_counter(Counter)
+    True
+    >>> is_counter(dict[str, int])
+    False
+    """
+    try:
+        return issubclass(get_origin(typ), Counter)  # type: ignore
+    except TypeError:
+        return typ is Counter
+
+
+@cache
+def is_bare_counter(typ: type[Any]) -> bool:
+    """
+    Test if the type is `collections.Counter` without type args.
+
+    >>> is_bare_counter(Counter[str])
+    False
+    >>> is_bare_counter(Counter)
+    True
+    """
+    origin = get_origin(typ)
+    if origin is Counter:
+        return not type_args(typ)
+    return typ is Counter
+
+
 @cache
 def is_none(typ: type[Any]) -> bool:
     """

serde/core.py

@@ -12,7 +12,7 @@
 from dataclasses import dataclass
 
 from beartype.door import is_bearable
-from collections import deque
+from collections import deque, Counter
 from collections.abc import Mapping, Sequence, MutableSequence, Set, Callable, Hashable
 from typing import (
     overload,
@@ -29,12 +29,14 @@
     SerdeError,
     dataclass_fields,
     get_origin,
+    is_bare_counter,
     is_bare_deque,
     is_bare_dict,
     is_bare_list,
     is_bare_set,
     is_bare_tuple,
     is_class_var,
+    is_counter,
     is_deque,
     is_dict,
     is_generic,
@@ -374,6 +376,9 @@ def is_instance(obj: Any, typ: Any) -> bool:
         return is_set_instance(obj, typ)
     elif is_tuple(typ):
         return is_tuple_instance(obj, typ)
+    elif is_counter(typ):
+        # Counter must be checked before dict since Counter is a subclass of dict
+        return is_counter_instance(obj, typ)
     elif is_dict(typ):
         return is_dict_instance(obj, typ)
     elif is_deque(typ):
@@ -500,6 +505,16 @@ def is_deque_instance(obj: Any, typ: type[Any]) -> bool:
     return is_instance(obj[0], deque_arg)
 
 
+def is_counter_instance(obj: Any, typ: type[Any]) -> bool:
+    if not isinstance(obj, Counter):
+        return False
+    if len(obj) == 0 or is_bare_counter(typ):
+        return True
+    counter_arg = type_args(typ)[0]
+    # for speed reasons we just check the type of the 1st key
+    return is_instance(next(iter(obj.keys())), counter_arg)
+
+
 def is_generic_instance(obj: Any, typ: type[Any]) -> bool:
     return is_instance(obj, get_origin(typ))
 

serde/de.py

@@ -31,11 +31,13 @@
     get_origin,
     get_type_var_names,
     is_any,
+    is_bare_counter,
     is_bare_deque,
     is_bare_dict,
     is_bare_list,
     is_bare_set,
     is_bare_tuple,
+    is_counter,
     is_datetime,
     is_default_dict,
     is_deque,
@@ -516,6 +518,11 @@ def deserializable_to_obj(cls: type[T]) -> T:
                 res = collections.deque(o)
             else:
                 res = collections.deque(thisfunc(type_args(c)[0], e) for e in o)
+        elif is_counter(c):
+            if is_bare_counter(c):
+                res = collections.Counter(o)
+            else:
+                res = collections.Counter({thisfunc(type_args(c)[0], k): v for k, v in o.items()})
         elif is_tuple(c):
             if is_bare_tuple(c) or is_variable_tuple(c):
                 res = tuple(e for e in o)
@@ -709,7 +716,13 @@ def __getitem__(self, n: int) -> DeField[Any] | InnerField[Any]:
             "flatten": self.flatten,
             "parent": self.parent,
         }
-        if is_list(self.type) or is_set(self.type) or is_dict(self.type) or is_deque(self.type):
+        if (
+            is_list(self.type)
+            or is_set(self.type)
+            or is_dict(self.type)
+            or is_deque(self.type)
+            or is_counter(self.type)
+        ):
             return InnerField(typ, "v", datavar="v", **opts)
         elif is_tuple(self.type):
             return InnerField(typ, f"{self.data}[{n}]", datavar=f"{self.data}[{n}]", **opts)
@@ -849,6 +862,8 @@ def render(self, arg: DeField[Any]) -> str:
             res = self.set(arg)
         elif is_deque(arg.type):
             res = self.deque(arg)
+        elif is_counter(arg.type):
+            res = self.counter(arg)
         elif is_dict(arg.type):
             res = self.dict(arg)
         elif is_tuple(arg.type):
@@ -1020,6 +1035,18 @@ def deque(self, arg: DeField[Any]) -> str:
         else:
             return f"collections.deque({self.render(arg[0])} for v in {arg.data})"
 
+    def counter(self, arg: DeField[Any]) -> str:
+        """
+        Render rvalue for Counter.
+        """
+        if is_bare_counter(arg.type):
+            return f"collections.Counter({arg.data})"
+        else:
+            k = arg[0]
+            k.name = "k"
+            k.datavar = "k"
+            return f"collections.Counter({{{self.render(k)}: v for k, v in {arg.data}.items()}})"
+
     def tuple(self, arg: DeField[Any]) -> str:
         """
         Render rvalue for tuple.

serde/se.py

@@ -13,7 +13,7 @@
 import jinja2
 from dataclasses import dataclass, is_dataclass
 from typing import Any, Generic, Literal, TypeVar
-from collections import deque
+from collections import deque, Counter
 from collections.abc import (
     Callable,
     Iterable,
@@ -32,13 +32,15 @@
     T,
     get_origin,
     is_any,
+    is_bare_counter,
     is_bare_deque,
     is_bare_dict,
     is_bare_list,
     is_bare_opt,
     is_bare_set,
     is_bare_tuple,
     is_class_var,
+    is_counter,
     is_datetime,
     is_datetime_instance,
     is_deque,
@@ -419,6 +421,8 @@ def serializable_to_obj(object: Any) -> Any:
             return [thisfunc(e) for e in o]
         elif isinstance(o, deque):
             return [thisfunc(e) for e in o]
+        elif isinstance(o, Counter):
+            return dict(o)
         elif is_str_serializable_instance(o) or is_datetime_instance(o):
             se_cls = o.__class__ if not c or c is Any else c
             return CACHE.serialize(
@@ -860,6 +864,8 @@ def render(self, arg: SeField[Any]) -> str:
             res = self.set(arg)
         elif is_deque(arg.type):
             res = self.deque(arg)
+        elif is_counter(arg.type):
+            res = self.counter(arg)
         elif is_dict(arg.type):
             res = self.dict(arg)
         elif is_tuple(arg.type):
@@ -994,6 +1000,17 @@ def deque(self, arg: SeField[Any]) -> str:
             earg.name = "v"
             return f"[{self.render(earg)} for v in {arg.varname}]"
 
+    def counter(self, arg: SeField[Any]) -> str:
+        """
+        Render rvalue for Counter.
+        """
+        if is_bare_counter(arg.type):
+            return f"dict({arg.varname})"
+        else:
+            karg = arg[0]
+            karg.name = "k"
+            return f"{{{self.render(karg)}: v for k, v in {arg.varname}.items()}}"
+
     def tuple(self, arg: SeField[Any]) -> str:
         """
         Render rvalue for tuple.

tests/common.py

@@ -6,7 +6,7 @@
 import pathlib
 import uuid
 from collections.abc import MutableSequence, MutableSet, Sequence, Set
-from collections import defaultdict, deque
+from collections import defaultdict, deque, Counter
 from typing import (
     Any,
     Generic,
@@ -136,6 +136,9 @@ def yaml_not_supported(se: Any, de: Any, opt: Any) -> bool:
     param(deque(["a", "b"]), deque[str]),
     param(deque(), deque[int]),
     param(deque([1, "a", 3.0]), deque),
+    param(Counter({"a": 1, "b": 2}), Counter[str]),  # Counter
+    param(Counter(), Counter[str]),
+    param(Counter({"a": 1}), Counter),
     param(data.Pri(10, "foo", 100.0, True), data.Pri),  # dataclass
     param(data.Pri(10, "foo", 100.0, True), Optional[data.Pri]),
     param(None, Optional[data.Pri], toml_not_supported),