fix: Fix JSON encoder and decoder

docs/gen_griffe_json.py

@@ -5,13 +5,13 @@
 import mkdocs_gen_files
 
 from griffe.docstrings.parsers import Parser
-from griffe.encoders import Encoder
+from griffe.encoders import JSONEncoder
 from griffe.loader import GriffeLoader
 
 griffe = GriffeLoader().load_module("griffe")
 serialized = json.dumps(
     griffe,
-    cls=Encoder,
+    cls=JSONEncoder,
     indent=0,
     full=True,
     docstring_parser=Parser.google,

src/griffe/cli.py

@@ -25,7 +25,7 @@
 from griffe.agents.extensions import Extensions
 from griffe.agents.extensions.base import load_extensions
 from griffe.docstrings.parsers import Parser
-from griffe.encoders import Encoder
+from griffe.encoders import JSONEncoder
 from griffe.exceptions import ExtensionError
 from griffe.loader import GriffeLoader
 from griffe.logger import get_logger
@@ -302,10 +302,10 @@ def main(args: list[str] | None = None) -> int:  # noqa: WPS231
     started = datetime.now()
     if per_package_output:
         for package_name, data in packages.items():
-            serialized = json.dumps(data, cls=Encoder, indent=2, full=opts.full)
+            serialized = json.dumps(data, cls=JSONEncoder, indent=2, full=opts.full)
             _print_data(serialized, output.format(package=package_name))
     else:
-        serialized = json.dumps(packages, cls=Encoder, indent=2, full=opts.full)
+        serialized = json.dumps(packages, cls=JSONEncoder, indent=2, full=opts.full)
         _print_data(serialized, output)
     elapsed = datetime.now() - started
 

src/griffe/encoders.py

@@ -2,7 +2,7 @@
 
 The available formats are:
 
-- `JSON`: see the [encoder][griffe.encoders.Encoder] and [decoder][griffe.encoders.decoder].
+- `JSON`: see the [`JSONEncoder`][griffe.encoders.JSONEncoder] and [`json_decoder`][griffe.encoders.json_decoder].
 """
 
 from __future__ import annotations
@@ -11,16 +11,30 @@
 from pathlib import Path, PosixPath
 from typing import Any, Callable, Type
 
-from griffe.dataclasses import Attribute, Class, Function, Kind, Module, Object, ParameterKind
+from griffe.dataclasses import (
+    Alias,
+    Attribute,
+    Class,
+    Decorator,
+    Docstring,
+    Function,
+    Kind,
+    Module,
+    Object,
+    Parameter,
+    ParameterKind,
+    Parameters,
+)
 from griffe.docstrings.dataclasses import DocstringSectionKind
 from griffe.docstrings.parsers import Parser
+from griffe.expressions import Expression, Name
 
 
 def _enum_value(obj):
     return obj.value
 
 
-_type_map: dict[Type, Callable[[Any], Any]] = {
+_json_encoder_map: dict[Type, Callable[[Any], Any]] = {
     Path: str,
     PosixPath: str,
     ParameterKind: _enum_value,
@@ -30,16 +44,19 @@ def _enum_value(obj):
 }
 
 
-class Encoder(json.JSONEncoder):
+class JSONEncoder(json.JSONEncoder):
     """JSON encoder.
 
-    JSON encoders are not used directly, but through
+    JSON encoders can be used directly, or through
     the [`json.dump`][] or [`json.dumps`][] methods.
 
     Examples:
+        >>> from griffe.encoders import JSONEncoder
+        >>> JSONEncoder(full=True).encode(..., **kwargs)
+
         >>> import json
-        >>> from griffe.encoders import Encoder
-        >>> json.dumps(..., cls=Encoder, full=True, **kwargs)
+        >>> from griffe.encoders import JSONEncoder
+        >>> json.dumps(..., cls=JSONEncoder, full=True, **kwargs)
     """
 
     def __init__(
@@ -56,7 +73,7 @@ def __init__(
             *args: See [`json.JSONEncoder`][].
             full: Whether to dump full data or base data.
                 If you plan to reload the data in Python memory
-                using the [decoder][griffe.encoders.decoder],
+                using the [`json_decoder`][griffe.encoders.json_decoder],
                 you don't need the full data as it can be infered again
                 using the base data. If you want to feed a non-Python
                 tool instead, dump the full data.
@@ -81,34 +98,129 @@ def default(self, obj: Any) -> Any:  # noqa: WPS212
         try:
             return obj.as_dict(full=self.full, docstring_parser=self.docstring_parser, **self.docstring_options)
         except AttributeError:
-            return _type_map.get(type(obj), super().default)(obj)
+            return _json_encoder_map.get(type(obj), super().default)(obj)
+
+
+def _load_docstring(obj_dict):
+    if "docstring" in obj_dict:
+        return Docstring(**obj_dict["docstring"])
+    return None
+
+
+def _load_decorators(obj_dict):
+    return [Decorator(**dec) for dec in obj_dict.get("decorators", [])]
+
+
+_annotation_loader_map = {
+    str: lambda _: _,
+    dict: lambda dct: Name(dct["source"], dct["full"]),
+    list: lambda lst: Expression(*[_load_annotation(_) for _ in lst]),
+}
 
 
-def decoder(obj_dict: dict[str, Any]) -> dict[str, Any] | Object:  # noqa: WPS231
+def _load_annotation(annotation: str | dict | list) -> str | Name | Expression:
+    if annotation is None:
+        return None
+    return _annotation_loader_map[type(annotation)](annotation)
+
+
+def _load_parameter(obj_dict: dict[str, Any]) -> Parameter:
+    return Parameter(
+        obj_dict["name"],
+        annotation=_load_annotation(obj_dict["annotation"]),
+        kind=ParameterKind(obj_dict["kind"]),
+        default=obj_dict["default"],
+    )
+
+
+def _load_module(obj_dict: dict[str, Any]) -> Module:
+    module = Module(name=obj_dict["name"], filepath=Path(obj_dict["filepath"]), docstring=_load_docstring(obj_dict))
+    for module_member in obj_dict.get("members", []):
+        module[module_member.name] = module_member
+    module.labels |= set(obj_dict.get("labels", ()))
+    return module
+
+
+def _load_class(obj_dict: dict[str, Any]) -> Class:
+    class_ = Class(
+        name=obj_dict["name"],
+        lineno=obj_dict["lineno"],
+        endlineno=obj_dict.get("endlineno", None),
+        docstring=_load_docstring(obj_dict),
+        decorators=_load_decorators(obj_dict),
+        bases=[_load_annotation(_) for _ in obj_dict["bases"]],
+    )
+    for class_member in obj_dict.get("members", []):
+        class_[class_member.name] = class_member
+    class_.labels |= set(obj_dict.get("labels", ()))
+    return class_
+
+
+def _load_function(obj_dict: dict[str, Any]) -> Function:
+    function = Function(
+        name=obj_dict["name"],
+        parameters=Parameters(*obj_dict["parameters"]),
+        returns=_load_annotation(obj_dict["returns"]),
+        decorators=_load_decorators(obj_dict),
+        lineno=obj_dict["lineno"],
+        endlineno=obj_dict.get("endlineno", None),
+        docstring=_load_docstring(obj_dict),
+    )
+    function.labels |= set(obj_dict.get("labels", ()))
+    return function
+
+
+def _load_attribute(obj_dict: dict[str, Any]) -> Attribute:
+    attribute = Attribute(
+        name=obj_dict["name"],
+        lineno=obj_dict["lineno"],
+        endlineno=obj_dict.get("endlineno", None),
+        docstring=_load_docstring(obj_dict),
+        value=obj_dict["value"],
+        annotation=_load_annotation(obj_dict.get("annotation", None)),
+    )
+    attribute.labels |= set(obj_dict.get("labels", ()))
+    return attribute
+
+
+def _load_alias(obj_dict: dict[str, Any]) -> Alias:
+    return Alias(
+        name=obj_dict["name"],
+        target=obj_dict["target_path"],
+        lineno=obj_dict["lineno"],
+        endlineno=obj_dict.get("endlineno", None),
+    )
+
+
+_loader_map: dict[Kind, Callable[[dict[str, Any]], Module | Class | Function | Attribute | Alias]] = {  # noqa: WPS234
+    Kind.MODULE: _load_module,
+    Kind.CLASS: _load_class,
+    Kind.FUNCTION: _load_function,
+    Kind.ATTRIBUTE: _load_attribute,
+    Kind.ALIAS: _load_alias,
+}
+
+
+def json_decoder(obj_dict: dict[str, Any]) -> dict[str, Any] | Object | Alias | Parameter:  # noqa: WPS231
     """Decode dictionaries as data classes.
 
     The [`json.loads`][] method walks the tree from bottom to top.
 
+    Examples:
+        >>> import json
+        >>> from griffe.encoders import json_decoder
+        >>> json.loads(..., object_hook=json_decoder)
+
     Parameters:
         obj_dict: The dictionary to decode.
 
     Returns:
         An instance of a data class.
     """
     if "kind" in obj_dict:
-        kind = Kind(obj_dict["kind"])
-        if kind == Kind.MODULE:
-            module = Module(name=obj_dict["name"], filepath=Path(obj_dict["filepath"]))
-            for module_member in obj_dict.get("members", []):
-                module[module_member.name] = module_member
-            return module
-        elif kind == Kind.CLASS:
-            class_ = Class(name=obj_dict["name"], lineno=obj_dict["lineno"], endlineno=obj_dict["endlineno"])
-            for class_member in obj_dict.get("members", []):
-                class_[class_member.name] = class_member
-            return class_
-        elif kind == Kind.FUNCTION:
-            return Function(name=obj_dict["name"], lineno=obj_dict["lineno"], endlineno=obj_dict["endlineno"])
-        elif kind == Kind.ATTRIBUTE:
-            return Attribute(name=obj_dict["name"], lineno=obj_dict["lineno"], endlineno=obj_dict["endlineno"])
+        try:
+            kind = Kind(obj_dict["kind"])
+        except ValueError:
+            return _load_parameter(obj_dict)
+        return _loader_map[kind](obj_dict)
     return obj_dict

tests/test_encoders.py

@@ -0,0 +1,22 @@
+"""Tests for the `encoders` module."""
+
+import json
+
+from griffe.encoders import JSONEncoder, json_decoder
+from griffe.loader import GriffeLoader
+
+
+def test_minimal_data_is_enough():
+    """Test serialization and de-serialization.
+
+    This is an end-to-end test that asserts
+    we can load back a serialized tree and
+    infer as much data as within the original tree.
+    """
+    loader = GriffeLoader()
+    module = loader.load_module("griffe")
+    minimal = json.dumps(module, cls=JSONEncoder, full=False, indent=2)
+    full = json.dumps(module, cls=JSONEncoder, full=True, indent=2)
+    reloaded = json.loads(minimal, object_hook=json_decoder)
+    assert json.dumps(reloaded, cls=JSONEncoder, full=False, indent=2) == minimal
+    assert json.dumps(reloaded, cls=JSONEncoder, full=True, indent=2) == full