ewokssphinx 2.2.0__tar.gz → 2.2.1__tar.gz

{ewokssphinx-2.2.0/src/ewokssphinx.egg-info → ewokssphinx-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ewokssphinx
-Version: 2.2.0
+Version: 2.2.1
 Summary: Ewoks Sphinx directives
 Author-email: ESRF <dau-pydev@esrf.fr>
 License: # MIT License

{ewokssphinx-2.2.0 → ewokssphinx-2.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ewokssphinx"
-version = "2.2.0"
+version = "2.2.1"
 keywords = ['ewoks', 'sphinx']
 authors = [{ name = "ESRF", email = "dau-pydev@esrf.fr" }]
 description = "Ewoks Sphinx directives"

{ewokssphinx-2.2.0 → ewokssphinx-2.2.1}/src/ewokssphinx/ewoks_task_utils.py

@@ -1,11 +1,19 @@
 import importlib
 import inspect
 import json
+from functools import reduce
 from pathlib import Path
+from typing import Annotated
 from typing import Any
+from typing import Iterator
+from typing import Type
+from typing import get_args
+from typing import get_origin
 
 from ewokscore.task_discovery import discover_tasks_from_modules
+from ewoksutils.import_utils import qualname
 from pydantic import BaseModel
+from pydantic.fields import FieldInfo
 from pydantic_core import PydanticUndefined
 from sphinx.util.typing import stringify_annotation
 
@@ -24,18 +32,26 @@ def discover_tasks(
     ):
         task_name = _get_task_name(task["task_identifier"], task["task_type"])
 
-        if task.get("input_model"):
-            inputs = parse_pydantic_model(task["input_model"])
+        input_model_name = task.get("input_model")
+        if input_model_name is not None:
+            input_model = _import_model(input_model_name)
+            inputs = _parse_pydantic_model(input_model)
         else:
+            input_model = None
             inputs = _parse_parameter_names(
                 task.get("required_input_names", []),
                 task.get("optional_input_names", []),
             )
-        if task.get("output_model"):
-            outputs = parse_pydantic_model(task["output_model"])
+
+        output_model_name = task.get("output_model")
+        if output_model_name:
+            output_model = _import_model(output_model_name)
+            outputs = _parse_pydantic_model(output_model)
         else:
+            output_model = None
             outputs = _parse_parameter_names(task.get("output_names", []), [])
 
+        submodels = _extract_submodels(input_model, output_model)
         serialized_task = {
             "task_name": task_name,
             "task_identifier": task["task_identifier"],
@@ -43,6 +59,7 @@ def discover_tasks(
             "description": _parse_doc(task.get("description")),
             "inputs": inputs,
             "outputs": outputs,
+            "submodels": {k: _parse_pydantic_model(v) for k, v in submodels.items()},
         }
         _ = TaskDescription(**serialized_task)
 
@@ -103,30 +120,27 @@ def _parse_parameter_names(
     return parameters
 
 
-def parse_pydantic_model(model: str | None) -> list[ParameterDescription]:
-    parameters = []
-    if model is None:
-        return parameters
-
-    model_cls = _import_model(model)
-    if not issubclass(model_cls, BaseModel):
-        raise ValueError("Not a pydantic model")
-    for name, field_info in model_cls.model_fields.items():
-        parameters.append(_parse_pydantic_field(name, field_info))
-    return parameters
+def _parse_pydantic_model(model: Type[BaseModel]) -> list[ParameterDescription]:
+    return [
+        _parse_pydantic_field(name, field_info)
+        for name, field_info in model.model_fields.items()
+    ]
 
 
-def _import_model(input_model_qual_name: str) -> type:
-    module_name, _, model_name = input_model_qual_name.rpartition(".")
+def _import_model(model_qual_name: str) -> Type[BaseModel]:
+    module_name, _, model_name = model_qual_name.rpartition(".")
     mod = importlib.import_module(module_name)
-    return getattr(mod, model_name)
+    model = getattr(mod, model_name)
+    if not issubclass(model, BaseModel):
+        raise ValueError("Not a pydantic model")
+    return model
 
 
 def _parse_doc(text) -> str:
     return inspect.cleandoc(text) if text else ""
 
 
-def _parse_pydantic_field(name, field_info) -> ParameterDescription:
+def _parse_pydantic_field(name: str, field_info: FieldInfo) -> ParameterDescription:
     examples = getattr(field_info, "examples", None)
     default = getattr(field_info, "default", None)
     if default is PydanticUndefined:
@@ -145,3 +159,45 @@ def _parse_pydantic_field(name, field_info) -> ParameterDescription:
         "default": None if default is None else str(default),
         "has_default": has_default,
     }
+
+
+def _extract_submodels(*raw_annotations: Any) -> dict[str, Type[BaseModel]]:
+    annotations = tuple(a for a in raw_annotations if a is not None)
+
+    if not annotations:
+        return {}
+
+    # Iterate over the union to have depth-first ordering
+    union_of_annotations = reduce(lambda a, b: a | b, annotations)
+
+    return {
+        qualname(model_cls): model_cls
+        for model_cls in _iter_models(union_of_annotations, set())
+        # Remove original models to get only submodels
+        if model_cls not in annotations
+    }
+
+
+def _iter_models(annotation: Any, seen: set[int]) -> Iterator[Type[BaseModel]]:
+    annotation_id = id(annotation)
+    if annotation_id in seen:
+        return
+    seen.add(annotation_id)
+
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        yield annotation
+
+        # Recurse into model fields
+        for field in annotation.model_fields.values():
+            yield from _iter_models(field.annotation, seen)
+
+    origin = get_origin(annotation)
+    # Handle Annotated[T, ...]
+    if origin is Annotated:
+        base_type, *_ = get_args(annotation)
+        yield from _iter_models(base_type, seen)
+        return
+
+    # Recurse into generic arguments (Union, list, dict, etc.)
+    for arg in get_args(annotation):
+        yield from _iter_models(arg, seen)

{ewokssphinx-2.2.0 → ewokssphinx-2.2.1}/src/ewokssphinx/sphinx_task_utils.py

@@ -4,7 +4,6 @@ from typing import Sequence
 from docutils import nodes
 from sphinx.util.docutils import SphinxDirective
 
-from .ewoks_task_utils import parse_pydantic_model
 from .type_utils import ParameterDescription
 from .type_utils import TaskDescription
 
@@ -193,43 +192,18 @@ def _rst_to_nodes(directive: SphinxDirective, text: str) -> list[nodes.Node]:
     return directive.parse_text_to_nodes(text)
 
 
-def _get_annotations(tasks: Sequence[dict[str, Any]]):
-    annotations: set[str] = set()
-
-    for task_dict in tasks:
-        task = TaskDescription(**task_dict)
-        parameters = task.inputs + task.outputs
-        for parameter in parameters:
-            annotation = parameter.annotation
-            if annotation is None:
-                continue
-            if "|" in annotation:
-                for a in annotation.split("|"):
-                    annotations.add(a.strip())
-            else:
-                annotations.add(annotation)
-
-    # Enforce consistent ordering
-    return sorted(annotations)
-
-
 def additional_model_nodes(
     directive: SphinxDirective, tasks: Sequence[dict[str, Any]]
 ) -> nodes.section | None:
-    annotations = _get_annotations(tasks)
-
     model_sections = []
-    for annotation in annotations:
-        try:
-            model = parse_pydantic_model(annotation)
-        except (ValueError, ModuleNotFoundError):
-            # Not a Pydantic model
-            continue
-        section = nodes.section("", ids=[annotation])
-        section.append(nodes.title("", annotation.split(".")[-1]))
+    for task in tasks:
+        for model_name, model_fields in task["submodels"].items():
+            section = nodes.section("", ids=[model_name])
+            section.append(nodes.title("", model_name.split(".")[-1]))
+
+            section.append(_field_list(directive, {"fields": model_fields}))
+            model_sections.append(section)
 
-        section.append(_field_list(directive, {"fields": model}))
-        model_sections.append(section)
     if not model_sections:
         return None
 

{ewokssphinx-2.2.0 → ewokssphinx-2.2.1}/src/ewokssphinx/tests/conftest.py

@@ -97,6 +97,7 @@ def app_with_cache(tmp_path_factory):
                 "required": True,
             },
         ],
+        "submodels": dict(),
     }
     cache = {"ewoksnoexisting.tasks.MyNonExistingTask": {"class": [task]}}
     with open(json_cache_path, "w") as fp:

{ewokssphinx-2.2.0 → ewokssphinx-2.2.1}/src/ewokssphinx/tests/dummy_tasks_nested.py

@@ -1,3 +1,4 @@
+from typing import Annotated
 from typing import Literal
 
 from ewokscore import Task
@@ -7,8 +8,14 @@ from pydantic import BaseModel
 from pydantic import Field
 
 
+class Planet(BaseModel):
+    name: str
+    radius: Annotated[float, Field(gt=0)]
+    gaseous: bool
+
+
 class Coordinates(BaseModel):
-    planet: str = "Earth"
+    planet: Planet
     latitude: int = Field(examples=[-90, 0, 90])
     longitude: float = Field(
         description="Longitude of the GPS point. **In degrees.**", examples=[-90, 0, 90]

{ewokssphinx-2.2.0 → ewokssphinx-2.2.1}/src/ewokssphinx/tests/test_task_cache.py

@@ -1,6 +1,6 @@
 from sphinx.testing import restructuredtext
 
-from .test_utils import assert_task_nodes
+from .utils import assert_task_nodes
 
 
 def test_cache(app_with_cache):

{ewokssphinx-2.2.0 → ewokssphinx-2.2.1}/src/ewokssphinx/tests/test_task_directive.py

@@ -1,7 +1,7 @@
 import pytest
 from sphinx.testing import restructuredtext
 
-from .test_utils import assert_task_nodes
+from .utils import assert_task_nodes
 
 
 def test_ewokstasks(app):

{ewokssphinx-2.2.0 → ewokssphinx-2.2.1}/src/ewokssphinx/tests/test_task_directive_pydantic.py

@@ -1,9 +1,9 @@
 from docutils import nodes
 from sphinx.testing import restructuredtext
 
-from .test_utils import assert_node
-from .test_utils import assert_section
-from .test_utils import assert_task_preamble
+from .utils import assert_node
+from .utils import assert_section
+from .utils import assert_task_preamble
 
 
 def test_ewokstasks_with_pydantic_input_model(app):
@@ -72,7 +72,8 @@ def test_ewokstasks_with_nested_pydantic_model(app):
     task_section, model_section = parsed_nodes
     assert_section(task_section, "ComputeTimeToGo")
 
-    assert len(model_section) == 3
+    assert len(model_section) == 4
     assert_section(model_section, "Additional models")
     assert_section(model_section[1], "Coordinates")
-    assert_section(model_section[2], "Location")
+    assert_section(model_section[2], "Planet")
+    assert_section(model_section[3], "Location")

ewokssphinx-2.2.1/src/ewokssphinx/tests/test_utils.py

@@ -0,0 +1,46 @@
+from pydantic import BaseModel
+
+from ewokssphinx.ewoks_task_utils import _extract_submodels
+
+
+class Type1(BaseModel):
+    pass
+
+
+class SubType1(BaseModel):
+    pass
+
+
+class SubSubType(BaseModel):
+    pass
+
+
+class SubType2(BaseModel):
+    var: dict[str, SubSubType]
+
+
+class Type2(BaseModel):
+    var: tuple[SubType2 | SubType1]
+
+
+Annotation = Type1 | list[SubType2] | dict[str, list[int | Type2]]
+
+
+def test_extract_type():
+
+    assert list(_extract_submodels(Annotation).keys()) == [
+        "ewokssphinx.tests.test_utils.Type1",
+        "ewokssphinx.tests.test_utils.SubType2",
+        "ewokssphinx.tests.test_utils.SubSubType",
+        "ewokssphinx.tests.test_utils.Type2",
+        "ewokssphinx.tests.test_utils.SubType1",
+    ]
+
+
+def test_extract_type_inputs():
+    from ewokssphinx.tests.dummy_tasks_nested import Inputs
+
+    assert list(_extract_submodels(Inputs).keys()) == [
+        "ewokssphinx.tests.dummy_tasks_nested.Coordinates",
+        "ewokssphinx.tests.dummy_tasks_nested.Planet",
+    ]

{ewokssphinx-2.2.0 → ewokssphinx-2.2.1}/src/ewokssphinx/type_utils.py

@@ -18,6 +18,7 @@ class TaskDescription(BaseModel, extra="forbid"):
     description: str
     inputs: list[TaskParameter]
     outputs: list[TaskParameter]
+    submodels: dict[str, list[TaskParameter]]
 
 
 ParameterDescription = dict[str, str | list[str] | bool | None]

{ewokssphinx-2.2.0 → ewokssphinx-2.2.1/src/ewokssphinx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ewokssphinx
-Version: 2.2.0
+Version: 2.2.1
 Summary: Ewoks Sphinx directives
 Author-email: ESRF <dau-pydev@esrf.fr>
 License: # MIT License

{ewokssphinx-2.2.0 → ewokssphinx-2.2.1}/src/ewokssphinx.egg-info/SOURCES.txt

@@ -20,4 +20,5 @@ src/ewokssphinx/tests/dummy_tasks_pydantic.py
 src/ewokssphinx/tests/test_task_cache.py
 src/ewokssphinx/tests/test_task_directive.py
 src/ewokssphinx/tests/test_task_directive_pydantic.py
-src/ewokssphinx/tests/test_utils.py
+src/ewokssphinx/tests/test_utils.py
+src/ewokssphinx/tests/utils.py