refactor: Improve expressions

Expressions are now proper objects,
not just recursive lists of strings and names.
This increases robustness for checking if
an expression is a tuple, an iterator, etc.,
and when getting the n-th item of tuples, etc.

This will also make it easier to write
powerful and robust Griffe extensions.

Breaking changes:
- `griffe.expressions.Name` was removed
- `griffe.expressions.Expression` was removed
- mkdocstrings-python 1.2.1 templates won't work
  with the new expressions

docs/schema.json

@@ -339,41 +339,9 @@
  }
  ],
  "$defs": {
- "name": {
- "type": "object",
- "properties": {
- "source": {
- "title": "The annotation as written in the source code.",
- "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.expressions.Name",
- "type": "string"
- },
- "full": {
- "title": "The full path of the .",
- "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.expressions.Name",
- "type": "string"
- }
- },
- "additionalProperties": false,
- "required": [
- "source",
- "full"
- ]
- },
  "expression": {
- "type": "array",
- "items": {
- "oneOf": [
- {
- "type": "string"
- },
- {
- "$ref": "#/$defs/name"
- },
- {
- "$ref": "#/$defs/expression"
- }
- ]
- }
+ "type": "object",
+ "additionalProperties": true
  },
  "annotation": {
  "oneOf": [
@@ -383,9 +351,6 @@
  {
  "type": "string"
  },
- {
- "$ref": "#/$defs/name"
- },
  {
  "$ref": "#/$defs/expression"
  }

src/griffe/agents/inspector.py

@@ -48,7 +48,7 @@
  from pathlib import Path
 
  from griffe.docstrings.parsers import Parser
- from griffe.expressions import Expression, Name
+ from griffe.expressions import Expr
 
 
 empty = Signature.empty
@@ -405,7 +405,7 @@ def inspect_attribute(self, node: ObjectNode) -> None:
  """
  self.handle_attribute(node)
 
- def handle_attribute(self, node: ObjectNode, annotation: str | Name | Expression | None = None) -> None:
+ def handle_attribute(self, node: ObjectNode, annotation: str | Expr | None = None) -> None:
  """Handle an attribute.
 
  Parameters:
@@ -478,7 +478,7 @@ def _convert_parameter(parameter: SignatureParameter, parent: Module | Class) ->
  return Parameter(name, annotation=annotation, kind=kind, default=default)
 
 
-def _convert_object_to_annotation(obj: Any, parent: Module | Class) -> str | Name | Expression | None:
+def _convert_object_to_annotation(obj: Any, parent: Module | Class) -> str | Expr | None:
  # even when *we* import future annotations,
  # the object from which we get a signature
  # can come from modules which did *not* import them,

src/griffe/agents/nodes/__init__.py

@@ -15,7 +15,12 @@
  ast_siblings,
 )
 from griffe.agents.nodes._docstrings import get_docstring
-from griffe.agents.nodes._expressions import (
+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_call_keyword_arguments
+from griffe.agents.nodes._runtime import ObjectKind, ObjectNode
+from griffe.agents.nodes._values import get_value, safe_get_value
+from griffe.expressions import (
  get_annotation,
  get_base_class,
  get_condition,
@@ -25,11 +30,6 @@
  safe_get_condition,
  safe_get_expression,
 )
-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_call_keyword_arguments
-from griffe.agents.nodes._runtime import ObjectKind, ObjectNode
-from griffe.agents.nodes._values import get_value, safe_get_value
 
 __all__ = [
  "ast_children",

src/griffe/agents/nodes/_all.py

@@ -4,11 +4,10 @@
 
 import ast
 from contextlib import suppress
-from functools import partial
 from typing import TYPE_CHECKING, Any, Callable
 
 from griffe.agents.nodes._values import get_value
-from griffe.expressions import Name
+from griffe.expressions import ExprName
 from griffe.logger import LogLevel, get_logger
 
 if TYPE_CHECKING:
@@ -18,32 +17,32 @@
 logger = get_logger(__name__)
 
 
-def _extract_constant(node: ast.Constant, parent: Module) -> list[str | Name]:
+def _extract_constant(node: ast.Constant, parent: Module) -> list[str | ExprName]:
  return [node.value]
 
 
-def _extract_name(node: ast.Name, parent: Module) -> list[str | Name]:
- return [Name(node.id, partial(parent.resolve, node.id))]
+def _extract_name(node: ast.Name, parent: Module) -> list[str | ExprName]:
+ return [ExprName(node.id, parent)]
 
 
-def _extract_starred(node: ast.Starred, parent: Module) -> list[str | Name]:
+def _extract_starred(node: ast.Starred, parent: Module) -> list[str | ExprName]:
  return _extract(node.value, parent)
 
 
-def _extract_sequence(node: ast.List | ast.Set | ast.Tuple, parent: Module) -> list[str | Name]:
+def _extract_sequence(node: ast.List | ast.Set | ast.Tuple, parent: Module) -> list[str | ExprName]:
  sequence = []
  for elt in node.elts:
  sequence.extend(_extract(elt, parent))
  return sequence
 
 
-def _extract_binop(node: ast.BinOp, parent: Module) -> list[str | Name]:
+def _extract_binop(node: ast.BinOp, parent: Module) -> list[str | ExprName]:
  left = _extract(node.left, parent)
  right = _extract(node.right, parent)
  return left + right
 
 
-_node_map: dict[type, Callable[[Any, Module], list[str | Name]]] = {
+_node_map: dict[type, Callable[[Any, Module], list[str | ExprName]]] = {
  ast.Constant: _extract_constant,
  ast.Name: _extract_name,
  ast.Starred: _extract_starred,
@@ -54,11 +53,11 @@ def _extract_binop(node: ast.BinOp, parent: Module) -> list[str | Name]:
 }
 
 
-def _extract(node: ast.AST, parent: Module) -> list[str | Name]:
+def _extract(node: ast.AST, parent: Module) -> list[str | ExprName]:
  return _node_map[type(node)](node, parent)
 
 
-def get__all__(node: ast.Assign | ast.AugAssign, parent: Module) -> list[str | Name]:
+def get__all__(node: ast.Assign | ast.AugAssign, parent: Module) -> list[str | ExprName]:
  """Get the values declared in `__all__`.
 
  Parameters:
@@ -77,7 +76,7 @@ def safe_get__all__(
  node: ast.Assign | ast.AugAssign,
  parent: Module,
  log_level: LogLevel = LogLevel.debug, # TODO: set to error when we handle more things
-) -> list[str | Name]:
+) -> list[str | ExprName]:
  """Safely (no exception) extract values in `__all__`.
 
  Parameters: