ci: Increase minimum bounds of pysource-codegen and pysource-minimize

Author: pawamoy

pyproject.toml

@@ -98,8 +98,8 @@ ci = [
     "duty>=1.6",
     "griffe-inherited-docstrings>=1.1",
     "jsonschema>=4.17",
-    "pysource-codegen>=0.4",
-    "pysource-minimize>=0.5",
+    "pysource-codegen>=0.7",
+    "pysource-minimize>=0.10",
     "pytest>=8.2",
     "pytest-cov>=5.0",
     "pytest-randomly>=3.15",

src/griffe/_internal/extensions/unpack_typeddict.py

@@ -1,8 +1,17 @@
+# TODO: Support `typing.ReadOnly`.
+# TODO: Support `extra_items=type`.
+# TODO: Support `closed=True/False`.
+
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+import ast
+from typing import TYPE_CHECKING, Any, TypedDict
 
-from griffe._internal.docstrings.models import DocstringParameter, DocstringSectionParameters
+from griffe._internal.docstrings.models import (
+    DocstringParameter,
+    DocstringSectionOtherParameters,
+    DocstringSectionParameters,
+)
 from griffe._internal.enumerations import DocstringSectionKind, ParameterKind
 from griffe._internal.expressions import Expr, ExprSubscript
 from griffe._internal.extensions.base import Extension
@@ -12,47 +21,152 @@
     from collections.abc import Iterable
 
 
-def _update_docstring(func: Function, parameters: Iterable[Parameter], kwparam: Parameter | None = None) -> None:
+class _TypedDictAttr(TypedDict):
+    name: str
+    annotation: str | Expr | None
+    docstring: Docstring | None
+    required: bool
+
+
+def _get_or_set_attrs(cls: Class) -> list[_TypedDictAttr]:
+    if (attrs := cls.extra.get("unpack_typeddict", {}).get("_attributes")) is not None:
+        return attrs
+
+    attrs = []
+    default_required = True
+    for arg, value in cls.keywords.items():
+        if arg == "total":
+            try:
+                total = ast.literal_eval(str(value))
+            except (ValueError, SyntaxError):
+                break
+            if total is True:
+                default_required = True
+            elif total is False:
+                default_required = False
+            break
+    for attr in cls.attributes.values():
+        annotation = attr.annotation
+        required = default_required
+        if isinstance(annotation, ExprSubscript):
+            if annotation.canonical_path in {
+                "typing.Required",
+                "typing_extensions.Required",
+            }:
+                annotation = annotation.slice.elements[0]  # type: ignore[union-attr]
+                required = True
+            elif annotation.canonical_path in {
+                "typing.NotRequired",
+                "typing_extensions.NotRequired",
+            }:
+                annotation = annotation.slice.elements[0]  # type: ignore[union-attr]
+                required = False
+        attrs.append(
+            _TypedDictAttr(
+                name=attr.name,
+                annotation=annotation,
+                docstring=attr.docstring,
+                required=required,
+            ),
+        )
+
+    cls.extra["unpack_typeddict"]["_attributes"] = attrs
+    return attrs
+
+
+def _update_docstring(func: Function, attributes: Iterable[_TypedDictAttr], kwparam: Parameter | None = None) -> None:
     if not func.docstring:
         func.docstring = Docstring("", parent=func)
+
+    required = []
+    optional = []
+    for attribute in attributes:
+        if attribute["required"]:
+            required.append(attribute)
+        else:
+            optional.append(attribute)
+
+    params_section = None
+    other_params_section = None
     sections = func.docstring.parsed
+
+    # Find existing "Parameters" section.
     section_gen = (section for section in sections if section.kind is DocstringSectionKind.parameters)
-    if kwparam and (params_section := next(section_gen, None)):
-        # Remove the `**kwargs` entry.
+    params_section = next(section_gen, None)
+
+    # Pop original variadic keyword parameter from section.
+    varkw_param = None
+    if kwparam and params_section is not None:
         param_gen = (i for i, arg in enumerate(params_section.value) if arg.name.lstrip("*") == kwparam.name)
         if (kwarg_pos := next(param_gen, None)) is not None:
-            params_section.value.pop(kwarg_pos)
-    else:
-        # Create a parameters section if none exists.
-        params_section = DocstringSectionParameters([])
-        func.docstring.parsed.append(params_section)
-    # Add entries for all parameters.
-    for param in parameters:
-        if param.name != "self":
+            varkw_param = params_section.value.pop(kwarg_pos)
+
+    # If we have required parameters, add them to the "Parameters" section.
+    if required:
+        # Create a "Parameters" section if none exists.
+        if params_section is None:
+            params_section = DocstringSectionParameters([])
+            func.docstring.parsed.append(params_section)
+
+        # Add required parameters to the section.
+        for attr in required:
             params_section.value.append(
                 DocstringParameter(
-                    name=param.name,
-                    description=param.docstring.value if param.docstring else "",
-                    annotation=param.annotation,
-                    value=param.default,
+                    name=attr["name"],
+                    description=attr["docstring"].value if attr["docstring"] else "",
+                    annotation=attr["annotation"],
                 ),
             )
 
+        # Add back the original variadic keyword parameter if it was present,
+        # and if some parameters are optional.
+        if optional and varkw_param is not None:
+            params_section.value.append(
+                DocstringParameter(
+                    name=varkw_param.name,
+                    description=varkw_param.description,
+                    annotation=varkw_param.annotation,
+                ),
+            )
 
-def _params_from_attrs(attrs: Iterable[Any]) -> Parameters:
-    return Parameters(
-        Parameter(name="self", kind=ParameterKind.positional_or_keyword),
-        *(
-            Parameter(
-                name=attr.name,
-                annotation=attr.annotation,
-                kind=ParameterKind.keyword_only,
-                default=attr.value,
-                docstring=attr.docstring,
+    # If we have optional parameters, add them to the "Other parameters" section.
+    if optional:
+        # Create an "Other parameters" section if none exists.
+        section_gen = (section for section in sections if section.kind is DocstringSectionKind.other_parameters)
+        if (other_params_section := next(section_gen, None)) is None:
+            other_params_section = DocstringSectionOtherParameters([])
+            func.docstring.parsed.append(other_params_section)
+
+        # Add optional parameters to the section.
+        for attr in optional:
+            other_params_section.value.append(
+                DocstringParameter(
+                    name=attr["name"],
+                    description=attr["docstring"].value if attr["docstring"] else "",
+                    annotation=attr["annotation"],
+                ),
             )
-            for attr in attrs
-        ),
-    )
+
+
+def _params_from_attrs(attrs: Iterable[_TypedDictAttr]) -> Parameters:
+    parameters = Parameters(Parameter(name="self", kind=ParameterKind.positional_or_keyword))
+    found_optional = False
+    for attr in attrs:
+        if attr["required"]:
+            parameters.add(
+                Parameter(
+                    name=attr["name"],
+                    annotation=attr["annotation"],
+                    kind=ParameterKind.keyword_only,
+                    docstring=attr["docstring"],
+                ),
+            )
+        else:
+            found_optional = True
+    if found_optional:
+        name = "_kwargs" if "kwargs" in parameters else "kwargs"
+        parameters.add(Parameter(name=name, kind=ParameterKind.var_keyword))
+    return parameters
 
 
 class UnpackTypedDictExtension(Extension):
@@ -67,19 +181,19 @@ def on_class(self, *, cls: Class, **kwargs: Any) -> None:  # noqa: ARG002
         else:
             return
 
-        attributes = cls.attributes.values()
+        attributes = _get_or_set_attrs(cls)
 
         if "__init__" not in cls.members:
             # Build the `__init__` method and add it to the class.
             parameters = _params_from_attrs(attributes)
             init = Function(name="__init__", parameters=parameters, returns="None")
             cls.set_member("__init__", init)
             # Update the `__init__` docstring.
-            _update_docstring(init, parameters)
+            _update_docstring(init, attributes)
 
         # Remove attributes from the class, as they are now in the `__init__` method.
         for attr in attributes:
-            cls.del_member(attr.name)
+            cls.del_member(attr["name"])
 
     def on_function(self, *, func: Function, **kwargs: Any) -> None:  # noqa: ARG002
         """Expand `**kwargs: Unpack[TypedDict]` in function signatures."""
@@ -102,17 +216,19 @@ def on_function(self, *, func: Function, **kwargs: Any) -> None:  # noqa: ARG002
         else:
             return
 
+        attributes = _get_or_set_attrs(typed_dict)
+
         if "__init__" in typed_dict.members:
             # The `__init__` was already generated: use its parameters.
             parameters = typed_dict["__init__"].parameters
         else:
             # Fallback to building parameters from attributes.
-            parameters = _params_from_attrs(typed_dict.attributes.values())
+            parameters = _params_from_attrs(attributes)
 
         # Update any parameter section in the docstring.
         # We do this before updating the signature so that
         # parsing the docstring doesn't emit warnings.
-        _update_docstring(func, parameters, parameter)
+        _update_docstring(func, attributes, parameter)
 
         # Update the function parameters.
         del func.parameters[parameter.name]

src/griffe/_internal/finder.py

@@ -125,7 +125,9 @@ def append_search_path(self, path: Path) -> None:
         Parameters:
             path: The path to append.
         """
-        path = path.resolve()
+        self._append_search_path(path.resolve())
+
+    def _append_search_path(self, path: Path) -> None:
         if path not in self.search_paths:
             self.search_paths.append(path)
 
@@ -379,10 +381,6 @@ def _contents(self, path: Path) -> list[Path]:
                 self._paths_contents[path] = []
         return self._paths_contents[path]
 
-    def _append_search_path(self, path: Path) -> None:
-        if path not in self.search_paths:
-            self.search_paths.append(path)
-
     def _extend_from_pth_files(self) -> None:
         for path in self.search_paths:
             for item in self._contents(path):

src/griffe/_internal/mixins.py

@@ -249,6 +249,23 @@ def from_json(cls: type[_ObjType], json_string: str, **kwargs: Any) -> _ObjType:
             raise TypeError(f"provided JSON object is not of type {cls}")
         return obj
 
+    def as_index(self, **kwargs: Any) -> dict[str, dict[str, Any]]:
+        """Return an index of this object/alias and its members.
+
+        Parameters:
+            **kwargs: Additional serialization options.
+
+        Returns:
+            A dictionary mapping paths to dictionaries.
+        """
+        index = {self.path: self.as_dict(full=True, flat=True, **kwargs)}  # type: ignore[attr-defined]
+        try:
+            for member in self.members.values():  # type: ignore[attr-defined]
+                index.update(member.as_index(**kwargs))
+        except AliasResolutionError:
+            pass
+        return index
+
 
 class ObjectAliasMixin(GetMembersMixin, SetMembersMixin, DelMembersMixin, SerializationMixin):
     """Mixin class to share methods that appear both in objects and aliases, unchanged."""