feat: Parse attribute values, parameter defaults and decorators as expressions

This commit refactors how we build expressions
(visiting AST nodes) to make it more performant
(reduced memory consumption) while handling the
different possible scenarios (future annotations
or not, trying to reparse strings or not).

Building values, defaults and decorators
as expressions allows us expression
features (full name resolution) within
the visitor. This will also allow us
to render cross-references in mkdocstrings.

Author: pawamoy

config/ruff.toml

@@ -85,7 +85,8 @@ ignore = [
     "S603",  # `subprocess` call: check for execution of untrusted input
     "S607",  # Starting a process with a partial executable path
 ]
-"src/*/*/nodes.py" = [
+"src/*/*/nodes/*.py" = [
+    "ARG001",  # Unused function argument
     "N812",  # Lowercase `keyword` imported as non-lowercase `NodeKeyword`
 ]
 "scripts/*.py" = [

docs/schema.json

@@ -223,9 +223,9 @@
                   "type": "object",
                   "properties": {
                     "value": {
-                      "title": "The decorator, as a string.",
+                      "title": "The decorator value (string, name or expression).",
                       "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Decorator.value",
-                      "type": "string"
+                      "$ref": "#/$defs/annotation"
                     },
                     "lineno": {
                       "title": "The decorator starting line number.",
@@ -291,10 +291,7 @@
                     "default": {
                       "title": "The default value of the parameter.",
                       "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Parameter.default",
-                      "type": [
-                        "string",
-                        "null"
-                      ]
+                      "$ref": "#/$defs/annotation"
                     }
                   },
                   "required": [
@@ -328,7 +325,7 @@
               "value": {
                 "title": "For attributes, their value.",
                 "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Attribute.value",
-                "type": "string"
+                "$ref": "#/$defs/annotation"
               },
               "annotation": {
                 "title": "For attributes, their type annotation.",
@@ -342,7 +339,7 @@
     }
   ],
   "$defs": {
-    "annotation_name": {
+    "name": {
       "type": "object",
       "properties": {
         "source": {
@@ -362,18 +359,18 @@
         "full"
       ]
     },
-    "annotation_expression": {
+    "expression": {
       "type": "array",
       "items": {
         "oneOf": [
           {
             "type": "string"
           },
           {
-            "$ref": "#/$defs/annotation_name"
+            "$ref": "#/$defs/name"
           },
           {
-            "$ref": "#/$defs/annotation_expression"
+            "$ref": "#/$defs/expression"
           }
         ]
       }
@@ -384,13 +381,13 @@
           "type": "null"
         },
         {
-          "const": "None"
+          "type": "string"
         },
         {
-          "$ref": "#/$defs/annotation_name"
+          "$ref": "#/$defs/name"
         },
         {
-          "$ref": "#/$defs/annotation_expression"
+          "$ref": "#/$defs/expression"
         }
       ]
     }

src/griffe/agents/nodes/__init__.py

@@ -27,7 +27,7 @@
 )
 from griffe.agents.nodes._imports import relative_to_absolute
 from griffe.agents.nodes._names import get_instance_names, get_name, get_names
-from griffe.agents.nodes._parameters import get_parameter_default
+from griffe.agents.nodes._parameters import get_call_keyword_arguments
 from griffe.agents.nodes._runtime import ObjectKind, ObjectNode
 from griffe.agents.nodes._values import get_value, safe_get_value
 
@@ -44,13 +44,13 @@
     "get__all__",
     "get_annotation",
     "get_base_class",
+    "get_call_keyword_arguments",
     "get_condition",
     "get_docstring",
     "get_expression",
     "get_instance_names",
     "get_name",
     "get_names",
-    "get_parameter_default",
     "get_value",
     "ObjectKind",
     "ObjectNode",

src/griffe/agents/nodes/_all.py

@@ -27,7 +27,7 @@
 logger = get_logger(__name__)
 
 
-def _extract_constant(node: NodeConstant, parent: Module) -> list[str | Name]:  # noqa: ARG001
+def _extract_constant(node: NodeConstant, parent: Module) -> list[str | Name]:
     return [node.value]