Unify/control placement of members, better support attrs (#21)

tlambert03 · web-flow · commit 155a7f211343 · 2025-07-30T17:40:46.000-04:00
* fix: changes for baybe

* typing

* pragmas

* add tests

* update readme
diff --git a/README.md b/README.md
@@ -47,13 +47,19 @@ You may use any of the following options, provided as a dictionary under the
 |---------------------|--------------------------------------------------|---------|
 | `include_inherited` | Include inherited fields in class parameters.    | `False` |
 | `include_private`   | Include private fields in the documentation.     | `False` |
+| `add_fields_to` | Where in the documentation to add the detected fields. Must be one of:<br><br>- `docstring-parameters`: add fields to the *Parameters* section of the docstring<br>- `docstring-attributes`: add fields to the *Attributes* section of the docstring<br>- `class-attributes`: add fields as class attributes | `docstring-parameters` |
+| `remove_fields_from_members` | If `True`, fields are *removed* as class members.  This is not encouraged (since fields are *indeed* class attributes), but will prevent duplication of the name in the docstring as well as the class.  This value is ignored if `add_fields_to` is `class-attributes`. | `False` |
 
 For example:
 
 ```yml
         options:
           extensions:
-          - griffe_fieldz: {include_inherited: true}
+          - griffe_fieldz:
+              include_inherited: false
+              include_private: false
+              add_fields_to: docstring-attributes
+              remove_fields_from_members: false
 ```
 
 ## Example
diff --git a/src/griffe_fieldz/_extension.py b/src/griffe_fieldz/_extension.py
@@ -5,15 +5,17 @@
 import inspect
 import textwrap
 from contextlib import suppress
-from typing import TYPE_CHECKING, Any, Iterable, Sequence
+from typing import TYPE_CHECKING, Any, Iterable, Literal, TypedDict, TypeVar, cast
 
 import fieldz
 from fieldz._repr import display_as_type
 from griffe import (
+    Attribute,
     Class,
     Docstring,
     DocstringAttribute,
     DocstringParameter,
+    DocstringSection,
     DocstringSectionAttributes,
     DocstringSectionParameters,
     Extension,
@@ -29,7 +31,11 @@
 
     from griffe import Expr, Inspector, Visitor
 
-logger = get_logger(__name__)
+    AddFieldsTo = Literal[
+        "docstring-parameters", "docstring-attributes", "class-attributes"
+    ]
+
+logger = get_logger("griffe-fieldz")
 
 
 class FieldzExtension(Extension):
@@ -40,14 +46,35 @@ def __init__(
         object_paths: list[str] | None = None,
         include_private: bool = False,
         include_inherited: bool = False,
+        add_fields_to: AddFieldsTo = "docstring-parameters",
+        remove_fields_from_members: bool = False,
         **kwargs: Any,
     ) -> None:
         self.object_paths = object_paths
         self._kwargs = kwargs
+        if kwargs:
+            logger.warning(
+                "Unknown kwargs passed to FieldzExtension: %s", ", ".join(kwargs)
+            )
         self.include_private = include_private
         self.include_inherited = include_inherited
 
-    def on_class_instance(
+        self.remove_fields_from_members = remove_fields_from_members
+        if add_fields_to not in (
+            "docstring-parameters",
+            "docstring-attributes",
+            "class-attributes",
+        ):  # pragma: no cover
+            logger.error(
+                "'add_fields_to' must be one of {'docstring-parameters', "
+                f"'docstring-attributes', or 'class-attributes'}}, not {add_fields_to}."
+                "\n\nDefaulting to 'docstring-parameters'."
+            )
+            add_fields_to = "docstring-parameters"
+
+        self.add_fields_to: AddFieldsTo = add_fields_to
+
+    def on_class_members(
         self,
         *,
         node: ast.AST | ObjectNode,
@@ -70,42 +97,31 @@ def on_class_instance(
 
         try:
             fieldz.get_adapter(runtime_obj)
-        except TypeError:
+        except TypeError:  # pragma: no cover
             return
         self._inject_fields(cls, runtime_obj)
 
     # ------------------------------
 
-    def _inject_fields(self, obj: Object, runtime_obj: Any) -> None:
+    def _inject_fields(self, griffe_obj: Object, runtime_obj: Any) -> None:
         # update the object instance with the evaluated docstring
         docstring = inspect.cleandoc(getattr(runtime_obj, "__doc__", "") or "")
-        if not obj.docstring:
-            obj.docstring = Docstring(docstring, parent=obj)
-        sections = obj.docstring.parsed
+        if not griffe_obj.docstring:
+            griffe_obj.docstring = Docstring(docstring, parent=griffe_obj)
 
         # collect field info
         fields = fieldz.fields(runtime_obj)
         if not self.include_inherited:
             annotations = getattr(runtime_obj, "__annotations__", {})
             fields = tuple(f for f in fields if f.name in annotations)
 
-        params, attrs = _fields_to_params(fields, obj.docstring, self.include_private)
-
-        # merge/add field info to docstring
-        if params:
-            for x in sections:
-                if isinstance(x, DocstringSectionParameters):
-                    _merge(x, params)
-                    break
-            else:
-                sections.insert(1, DocstringSectionParameters(params))
-        if attrs:
-            for x in sections:
-                if isinstance(x, DocstringSectionAttributes):
-                    _merge(x, params)
-                    break
-            else:
-                sections.append(DocstringSectionAttributes(attrs))
+        _unify_fields(
+            fields,
+            griffe_obj,
+            include_private=self.include_private,
+            add_fields_to=self.add_fields_to,
+            remove_fields_from_members=self.remove_fields_from_members,
+        )
 
 
 def _to_annotation(type_: Any, docstring: Docstring) -> str | Expr | None:
@@ -119,63 +135,136 @@ def _to_annotation(type_: Any, docstring: Docstring) -> str | Expr | None:
 
 def _default_repr(field: fieldz.Field) -> str | None:
     """Return a repr for a field default."""
-    if field.default is not field.MISSING:
-        return repr(field.default)
-    if (factory := field.default_factory) is not field.MISSING:
-        if len(inspect.signature(factory).parameters) == 0:
-            with suppress(Exception):
-                return repr(factory())  # type: ignore[call-arg]
-        return "<dynamic>"
+    try:
+        if field.default is not field.MISSING:
+            return repr(field.default)
+        if (factory := field.default_factory) is not field.MISSING:
+            try:
+                sig = inspect.signature(factory)
+            except ValueError:
+                return repr(factory)
+            else:
+                if len(sig.parameters) == 0:
+                    with suppress(Exception):
+                        return repr(factory())  # type: ignore[call-arg]
+
+            return "<dynamic>"
+    except Exception as exc:  # pragma: no cover
+        logger.warning("Failed to get default repr for %s: %s", field.name, exc)
+        pass
     return None
 
 
-def _fields_to_params(
+class DocstringNamedElementKwargs(TypedDict):
+    """Docstring named element kwargs."""
+
+    name: str
+    description: str
+    annotation: str | Expr | None
+    value: str | None
+
+
+def _unify_fields(
     fields: Iterable[fieldz.Field],
-    docstring: Docstring,
-    include_private: bool = False,
-) -> tuple[list[DocstringParameter], list[DocstringAttribute]]:
-    """Get all docstring attributes and parameters for fields."""
-    params: list[DocstringParameter] = []
-    attrs: list[DocstringAttribute] = []
+    griffe_obj: Object,
+    include_private: bool,
+    add_fields_to: AddFieldsTo,
+    remove_fields_from_members: bool,
+) -> None:
+    docstring = cast("Docstring", griffe_obj.docstring)
+    sections = docstring.parsed
+
     for field in fields:
+        if not include_private and field.name.startswith("_"):
+            continue
+
         try:
-            desc = field.description or field.metadata.get("description", "") or ""
-            if not desc and (doc := getattr(field.default_factory, "__doc__", None)):
-                desc = inspect.cleandoc(doc) or ""
-
-            kwargs: dict = {
-                "name": field.name,
-                "annotation": _to_annotation(field.type, docstring),
-                "description": textwrap.dedent(desc).strip(),
-                "value": _default_repr(field),
-            }
-            if field.init:
-                params.append(DocstringParameter(**kwargs))
-            elif include_private or not field.name.startswith("_"):
-                attrs.append(DocstringAttribute(**kwargs))
+            item_kwargs = _merged_kwargs(field, docstring, griffe_obj)
+
+            if add_fields_to == "class-attributes":
+                if field.name not in griffe_obj.attributes:
+                    griffe_obj.members[field.name] = Attribute(
+                        name=item_kwargs["name"],
+                        value=item_kwargs["value"],
+                        annotation=item_kwargs["annotation"],
+                        docstring=item_kwargs["description"],
+                    )
+            elif add_fields_to == "docstring-attributes" or (not field.init):
+                _add_if_missing(sections, DocstringAttribute(**item_kwargs))
+                # remove from parameters if it exists
+                if p_sect := _get_section(sections, DocstringSectionParameters):
+                    p_sect.value = [x for x in p_sect.value if x.name != field.name]
+                if remove_fields_from_members:
+                    # remove from griffe_obj.parameters
+                    griffe_obj.members.pop(field.name, None)
+                    griffe_obj.inherited_members.pop(field.name, None)
+            elif add_fields_to == "docstring-parameters":
+                _add_if_missing(sections, DocstringParameter(**item_kwargs))
+                # remove from attributes if it exists
+                if a_sect := _get_section(sections, DocstringSectionAttributes):
+                    a_sect.value = [x for x in a_sect.value if x.name != field.name]
+                if remove_fields_from_members:
+                    # remove from griffe_obj.attributes
+                    griffe_obj.members.pop(field.name, None)
+                    griffe_obj.inherited_members.pop(field.name, None)
+
         except Exception as exc:
             logger.warning("Failed to parse field %s: %s", field.name, exc)
 
-    return params, attrs
+
+def _merged_kwargs(
+    field: fieldz.Field, docstring: Docstring, griffe_obj: Object
+) -> DocstringNamedElementKwargs:
+    desc = field.description or field.metadata.get("description", "") or ""
+    if not desc and (doc := getattr(field.default_factory, "__doc__", None)):
+        desc = inspect.cleandoc(doc) or ""
+
+    if not desc and field.name in griffe_obj.attributes:
+        griffe_attr = griffe_obj.attributes[field.name]
+        if griffe_attr.docstring:
+            desc = griffe_attr.docstring.value
+
+    return DocstringNamedElementKwargs(
+        name=field.name,
+        description=textwrap.dedent(desc).strip(),
+        annotation=_to_annotation(field.type, docstring),
+        value=_default_repr(field),
+    )
 
 
-def _merge(
-    existing_section: DocstringSectionParameters | DocstringSectionAttributes,
-    field_params: Sequence[DocstringParameter],
+T = TypeVar("T", bound="DocstringSectionParameters | DocstringSectionAttributes")
+
+
+def _get_section(sections: list[DocstringSection], cls: type[T]) -> T | None:
+    for section in sections:
+        if isinstance(section, cls):
+            return section
+    return None
+
+
+def _add_if_missing(
+    sections: list[DocstringSection], item: DocstringParameter | DocstringAttribute
 ) -> None:
-    """Update DocstringSection with field params (if missing)."""
-    existing_members = {x.name: x for x in existing_section.value}
-
-    for param in field_params:
-        if existing := existing_members.get(param.name):
-            # if the field already exists ...
-            # extend missing attributes with the values from the fieldz params
-            if existing.value is None and param.value is not None:
-                existing.value = param.value
-            if existing.description is None and param.description:
-                existing.description = param.description
-            if existing.annotation is None and param.annotation is not None:
-                existing.annotation = param.annotation
-        else:
-            # otherwise, add the missing fields
-            existing_section.value.append(param)  # type: ignore
+    section: DocstringSectionParameters | DocstringSectionAttributes | None
+    if isinstance(item, DocstringParameter):
+        if not (section := _get_section(sections, DocstringSectionParameters)):
+            section = DocstringSectionParameters([])
+            sections.append(section)
+    elif isinstance(item, DocstringAttribute):
+        if not (section := _get_section(sections, DocstringSectionAttributes)):
+            section = DocstringSectionAttributes([])
+            sections.append(section)
+    else:  # pragma: no cover
+        raise TypeError(f"Unknown section type: {type(item)}")
+
+    existing = {x.name: x for x in section.value}
+    if item.name in existing:
+        current = existing[item.name]
+        if current.description is None and item.description:
+            current.description = item.description
+        if current.annotation is None and item.annotation:
+            current.annotation = item.annotation
+        if current.value is None and item.value is not None:
+            current.value = item.value
+    else:
+        section.value.append(item)  # type: ignore [arg-type]
diff --git a/tests/fake_module.py b/tests/fake_module.py
@@ -6,3 +6,25 @@ class SomeDataclass:
     """SomeDataclass."""
 
     x: int = field(default=1, metadata={"description": "The x field."})
+
+
+@dataclass
+class Inherited(SomeDataclass):
+    y: int = 2
+
+
+@dataclass
+class WithPrivate:
+    """Class with private field."""
+
+    _hidden: int = 99
+
+
+def factory_func() -> int:
+    """Factory docstring."""
+    return 7
+
+
+@dataclass
+class WithFactory:
+    y: int = field(default_factory=factory_func)
diff --git a/tests/test_griffe_fieldz.py b/tests/test_griffe_fieldz.py
