Allow for model extensions

CHANGES.md

@@ -2,29 +2,35 @@
 
 ### Enhancements
 
-The Cuiman client package has been enhanced by _job result openers_,
-which ease working with the results of a process job (#65):
-  - Client classes now have a method 
-    `open_job_result(job_id, **options)` that is used to open the results 
-    of a job. Both sync and async versions of the method are available in 
-    `cuiman.Client` and `cuiman.AsyncClient`. 
-  - Applications can customize how job results are opened by  
-    adding their application-specific openers using the new 
-    `register_job_result_opener(opener)` in class `cuiman.ClientConfig`.
-  - Added a new `notebooks/cuiman-openers.ipynb` that demonstrates a
-    custom opener. 
-  - Added a new section in Cuiman usage documentation.
-  - Added some default openers for `xarray.Dataset`, 
-    `pandas.DataFrame`, and `geopandas.GeoDataFrame` 
-    given that a respective job result is a link.
-
-The model classes that correspond to the OGC API - Processes in 
-`gavicore.models` are no longer generated and have been adjusted to
-be more user-friendly (#71):
-  - `InlineValue` is now a simple type alias instead of a `pydantic.RootModel`.
-  - Same for `InlineValueOrRef` which has also been renamed to `JobResult`.
-  - Replaced type of optional fields `Optional[T]` by `T | None`.
-
+- The Cuiman client package has been enhanced by _job result openers_,
+  which ease working with the results of a process job (#65):
+    - Client classes now have a method 
+      `open_job_result(job_id, **options)` that is used to open the results 
+      of a job. Both sync and async versions of the method are available in 
+      `cuiman.Client` and `cuiman.AsyncClient`. 
+    - Applications can customize how job results are opened by  
+      adding their application-specific openers using the new 
+      `register_job_result_opener(opener)` in class `cuiman.ClientConfig`.
+    - Added a new `notebooks/cuiman-openers.ipynb` that demonstrates a
+      custom opener. 
+    - Added a new section in Cuiman usage documentation.
+    - Added some default openers for `xarray.Dataset`, 
+      `pandas.DataFrame`, and `geopandas.GeoDataFrame` 
+      given that a respective job result is a link.
+
+- The model classes that correspond to the OGC API - Processes in 
+  `gavicore.models` are no longer generated and have been adjusted to
+  be more user-friendly (#71):
+    - `InlineValue` is now a simple type alias instead of a `pydantic.RootModel`.
+    - Same for `InlineValueOrRef` which has also been renamed to `JobResult`.
+    - Replaced type of optional fields `Optional[T]` by `T | None`.
+    - The following models are now extendable, e.g., using `"x-"` prefixed fields:
+        - `gavicore.models.InputDescription` (e.g., extra "x-ui")
+        - `gavicore.models.OutputDescription` (e.g., extra "x-ui")
+        - `gavicore.models.JobStatus`  (e.g., extra "x-traceback")
+        - `gavicore.models.ApiError`  (e.g., extra "x-traceback")
+
+- Lifted some mypy restrictions and enabled mypy pydantic plugin.
 
 ## Changes in version 0.0.9
 

cuiman/tests/cli/test_client.py

@@ -36,7 +36,7 @@ def test_fail_with_client_error(self):
                         title="Not found",
                         status=404,
                         detail="Something was not found",
-                        traceback=["a", "b", "c"],
+                        **{"x-traceback": ["a", "b", "c"]},
                     ),
                 )
 
@@ -51,7 +51,7 @@ def test_fail_with_client_error_and_traceback(self):
                         title="Not found",
                         status=404,
                         detail="Something was not found",
-                        traceback=["a", "b", "c"],
+                        **{"x-traceback": ["a", "b", "c"]},
                     ),
                 )
 

gavicore/src/gavicore/models.py

@@ -6,7 +6,7 @@
 
 from datetime import date
 from enum import Enum
-from typing import Annotated, Any, TypeAlias, Union
+from typing import Any, TypeAlias, Union
 
 from pydantic import AnyUrl, AwareDatetime, BaseModel, ConfigDict, Field, RootModel
 
@@ -152,6 +152,11 @@ class AdditionalParameters(Metadata):
 
 
 class DescriptionType(BaseModel):
+    model_config = ConfigDict(
+        # allow for extensions, e.g., using field name prefix "x-"
+        extra="allow",
+    )
+
     title: str | None = None
     description: str | None = None
     keywords: list[str] | None = None
@@ -263,6 +268,7 @@ class JobControlOptions(Enum):
 
 class JobInfo(BaseModel):
     model_config = ConfigDict(
+        # allow for extensions, e.g., using field name prefix "x-"
         extra="allow",
     )
 
@@ -276,10 +282,10 @@ class JobInfo(BaseModel):
     finished: AwareDatetime | None = None
     updated: AwareDatetime | None = None
     # noinspection Pydantic
-    progress: Annotated[int | None, Field(None, ge=0, le=100)] = None
+    progress: int | None = Field(None, ge=0, le=100)
     links: list[Link] | None = None
-    # --- Enhancements to the standard
-    traceback: list[str] | None = None
+    # -- recognized extensions
+    traceback: str | list[str] | None = Field(None, alias="x-traceback")
 
 
 class JobList(BaseModel):
@@ -310,6 +316,7 @@ class ApiError(BaseModel):
     """
 
     model_config = ConfigDict(
+        # allow for extensions, e.g., using field name prefix "x-"
         extra="allow",
     )
 
@@ -318,8 +325,8 @@ class ApiError(BaseModel):
     status: int | None = None
     detail: str | None = None
     instance: str | None = None
-    # --- Enhancements to the standard
-    traceback: list[str] | None = None
+    # -- recognized extensions
+    traceback: str | list[str] | None = Field(None, alias="x-traceback")
 
 
 Format.model_rebuild()

gavicore/tests/test_models.py

@@ -4,11 +4,12 @@
 
 import inspect
 from enum import Enum
+from typing import Any, TypeVar
 from unittest import TestCase
 
 from pydantic import BaseModel
 
-import gavicore.models as gc_models
+import gavicore.models as m
 
 REQUIRED_ENUMS = {
     "CRS",
@@ -37,20 +38,22 @@
     "Schema",
 }
 
+T = TypeVar("T", bound=BaseModel)
+
 
 class ModelsTest(TestCase):
     def test_enums(self):
         all_enums = set(
             name
-            for name, obj in inspect.getmembers(gc_models, inspect.isclass)
+            for name, obj in inspect.getmembers(m, inspect.isclass)
             if issubclass(obj, Enum)
         )
         self.assertSetIsOk(REQUIRED_ENUMS, all_enums)
 
     def test_classes(self):
         all_classes = set(
             name
-            for name, obj in inspect.getmembers(gc_models, inspect.isclass)
+            for name, obj in inspect.getmembers(m, inspect.isclass)
             if issubclass(obj, BaseModel)
         )
         self.assertSetIsOk(REQUIRED_CLASSES, all_classes)
@@ -60,11 +63,12 @@ def assertSetIsOk(self, required: set[str], actual: set[str]):
         self.assertSetEqual(required, contained_items, "contained")
 
     def test_models_have_repr_json(self):
-        for name, obj in inspect.getmembers(gc_models, inspect.isclass):
+        for name, obj in inspect.getmembers(m, inspect.isclass):
             if name in REQUIRED_CLASSES and issubclass(obj, BaseModel):
                 self.assertTrue(hasattr(obj, "_repr_json_"), msg=f"model {name}")
 
-        obj = gc_models.Bbox(bbox=[10, 20, 30, 40])
+        obj = m.Bbox(bbox=[10, 20, 30, 40])
+        # noinspection PyUnresolvedReferences
         json_repr = obj._repr_json_()
         self.assertEqual(
             (
@@ -73,3 +77,56 @@ def test_models_have_repr_json(self):
             ),
             json_repr,
         )
+
+    def test_models_with_extensions(self):
+        api_error = self._assert_extendable_model(
+            m.ApiError,
+            {
+                "title": "Key not found",
+                "status": 500,
+                "type": "KeyError",
+                "x-traceback": ["hello", "world"],
+            },
+        )
+        self.assertEqual(["hello", "world"], api_error.traceback)
+
+        job_info = self._assert_extendable_model(
+            m.JobInfo,
+            {
+                "type": "process",
+                "jobID": "job_1",
+                "status": "failed",
+                "x-traceback": "hello\nworld",
+            },
+        )
+        self.assertEqual("hello\nworld", job_info.traceback)
+
+        input_description = self._assert_extendable_model(
+            m.InputDescription,
+            {
+                "title": "Threshold",
+                "schema": {"type": "number"},
+                "x-ui": {"widget": "slider"},
+            },
+        )
+        self.assertEqual(
+            {"widget": "slider"}, input_description.model_extra.get("x-ui")
+        )
+
+        output_description = self._assert_extendable_model(
+            m.OutputDescription,
+            {
+                "title": "Output URL",
+                "schema": {"type": "string", "format": "uri"},
+                "x-ui": {"widget": "text"},
+            },
+        )
+        self.assertEqual({"widget": "text"}, output_description.model_extra.get("x-ui"))
+
+    def _assert_extendable_model(self, model_cls: type[T], data: dict[str, Any]) -> T:
+        model_instance = model_cls(**data)
+        self.assertEqual(
+            data,
+            model_instance.model_dump(mode="json", by_alias=True, exclude_unset=True),
+        )
+        return model_instance

pyproject.toml

@@ -143,7 +143,8 @@ omit = [
 [tool.mypy]
 python_version = "3.10"
 check_untyped_defs = true
-disable_error_code = ["valid-type", "import-untyped"]
+disable_error_code = ["import-untyped"]
+plugins = ["pydantic.mypy"]
 exclude = [
     "appligator/tests",
     "cuiman/tests",
@@ -156,9 +157,6 @@ exclude = [
     "tools",
     "_pkg_reservations",
 ]
-[[tool.mypy.overrides]]
-module = "gavicore.models"
-disable_error_code = ["valid-type"]
 
 ########################## Tasks ###############################
 

wraptile/src/wraptile/exceptions.py

@@ -26,13 +26,15 @@ def __init__(
             status=status_code,
             title=HTTPStatus(status_code).phrase,
             detail=detail,
-            traceback=(
-                traceback.format_exception(
-                    type(exception), exception, exception.__traceback__
+            **{
+                "x-traceback": (
+                    traceback.format_exception(
+                        type(exception), exception, exception.__traceback__
+                    )
+                    if exception is not None
+                    else None
                 )
-                if exception is not None
-                else None
-            ),
+            },
         )