🚚 Rename Root annotation to FullPayload (#217)

Author: aleksul

docs/integrations/fastapi_and_pydantic.md

@@ -52,7 +52,7 @@ As long as Pydantic is installed in your environment, Repid will automatically s
 `PydanticConverter`. This means any type hints you use in your actor signature will be strictly
 validated, and you can use `pydantic.Field` for defaults and aliases.
 
-For detailed examples on defining actors with Pydantic validation and using the `Root()` dependency
+For detailed examples on defining actors with Pydantic validation and using the `FullPayload()` dependency
 annotation, see the [Actors guide](../user_guide/actors/parsing.md#parsing-with-pydantic).
 
 ## Integration with FastAPI

docs/user_guide/actors/parsing.md

@@ -78,29 +78,29 @@ async def process_order(
     pass
 ```
 
-### The `Root()` Annotation
+### The `FullPayload()` Annotation
 
 Sometimes you don't want your JSON payload's keys scattered as individual arguments. If you want to
-accept an entire Pydantic model representing the exact root JSON payload, you can use the `Root`
+accept an entire Pydantic model representing the exact root JSON payload, you can use the `FullPayload`
 annotation:
 
 ```python
 from typing import Annotated
 from pydantic import BaseModel
-from repid import Root
+from repid import FullPayload
 
 class UserPayload(BaseModel):
     user_id: int
     is_active: bool
 
 @router.actor
-async def process_user(user: Annotated[UserPayload, Root()]):
+async def process_user(user: Annotated[UserPayload, FullPayload()]):
     # `user` contains the fully validated payload model
     print(user.user_id)
 ```
 
 !!! tip
-    `Root()` is only available when Pydantic is installed.
+    `FullPayload()` is only available when Pydantic is installed.
 
 ## Extracting Headers
 

repid/__init__.py

@@ -8,10 +8,10 @@
 from .converter import PydanticConverter as PydanticConverter
 from .data import *  # noqa: F403
 from .dependencies import Depends as Depends
+from .dependencies import FullPayload as FullPayload
 from .dependencies import Header as Header
 from .dependencies import Message as Message
 from .dependencies import MessageDependency as MessageDependency
-from .dependencies import Root as Root
 from .health_check_server import HealthCheckServer as HealthCheckServer
 from .health_check_server import HealthCheckServerSettings as HealthCheckServerSettings
 from .health_check_server import HealthCheckStatus as HealthCheckStatus

repid/converter.py

@@ -9,7 +9,7 @@
 
 from repid._utils import is_installed
 from repid.data import ConverterInputSchema
-from repid.dependencies._utils import DependencyContext, get_dependency, get_root_marker
+from repid.dependencies._utils import DependencyContext, get_dependency, get_full_payload_marker
 from repid.dependencies.depends import Depends as DependsClass
 from repid.dependencies.header_dependency import Header
 
@@ -154,8 +154,8 @@ def __init__(
                 inspect.Parameter.POSITIONAL_OR_KEYWORD,
                 inspect.Parameter.KEYWORD_ONLY,
             ):
-                if get_root_marker(p.annotation) is not None:
-                    raise ValueError("Root() requires PydanticConverter.")
+                if get_full_payload_marker(p.annotation) is not None:
+                    raise ValueError("FullPayload() requires PydanticConverter.")
                 if (dep := get_dependency(p.annotation)) is not None:
                     self.dependency_kwargs[p.name] = dep
                     continue
@@ -306,9 +306,9 @@ def _parse_signature(
             if p.kind in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY):
                 if (dep := get_dependency(p.annotation)) is not None:
                     dependency_kwargs[p.name] = dep
-                elif get_root_marker(p.annotation) is not None:
+                elif get_full_payload_marker(p.annotation) is not None:
                     if root_arg is not None:
-                        raise ValueError("Only one Root() marker is allowed per actor.")
+                        raise ValueError("Only one FullPayload() marker is allowed per actor.")
                     root_arg = (p.name, get_args(p.annotation)[0])
                 else:
                     kwargs.append(p.name)

repid/dependencies/__init__.py

@@ -1,9 +1,9 @@
 from ._utils import DependencyContext as DependencyContext
 from ._utils import DependencyT as DependencyT
 from ._utils import get_dependency as get_dependency
-from ._utils import get_root_marker as get_root_marker
+from ._utils import get_full_payload_marker as get_full_payload_marker
 from .depends import Depends as Depends
+from .full_payload import FullPayload as FullPayload
 from .header_dependency import Header as Header
 from .message_dependency import Message as Message
 from .message_dependency import MessageDependency as MessageDependency
-from .root import Root as Root

repid/dependencies/_utils.py

@@ -5,9 +5,9 @@
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Annotated, Any, Protocol, get_origin, runtime_checkable
 
+from repid.dependencies.full_payload import FullPayload
 from repid.dependencies.header_dependency import Header
 from repid.dependencies.message_dependency import MessageDependency
-from repid.dependencies.root import Root
 
 if TYPE_CHECKING:
     from repid.connections.abc import ReceivedMessageT, ServerT
@@ -45,12 +45,12 @@ def get_dependency(t: Any) -> DependencyT | None:
     return None
 
 
-def get_root_marker(t: Any) -> Root | None:
-    """Return the `Root` instance from a type annotation if present."""
+def get_full_payload_marker(t: Any) -> FullPayload | None:
+    """Return the `FullPayload` instance from a type annotation if present."""
     if get_origin(t) is not Annotated:
         return None
     for metadata in t.__metadata__:
-        if isinstance(metadata, Root):
+        if isinstance(metadata, FullPayload):
             return metadata
     return None
 

repid/dependencies/root.py repid/dependencies/full_payload.pyrepid/dependencies/root.py renamed to repid/dependencies/full_payload.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
 
-class Root:
+class FullPayload:
     """Annotation marker designating a Pydantic model as the root payload.
 
-    When applied as ``Annotated[MyModel, Root()]``, the model's fields are
+    When applied as ``Annotated[MyModel, FullPayload()]``, the model's fields are
     read directly from the top level of the incoming JSON rather than being
-    nested under the argument name.  Only one ``Root()`` marker is allowed
+    nested under the argument name.  Only one ``FullPayload()`` marker is allowed
     per actor.
     """
 

tests/unit/test_converter.py

@@ -6,7 +6,7 @@
 import pytest
 from pydantic import BaseModel, ValidationError
 
-from repid import Header, Root
+from repid import FullPayload, Header
 from repid.converter import BasicConverter, ConverterT, PydanticConverter
 from repid.data import MessageData
 from repid.dependencies import Depends
@@ -773,12 +773,12 @@ async def _fn_with_shared_header_in_two_depends(
     }
 
 
-async def test_pydantic_converter_root_model_parse() -> None:
+async def test_pydantic_converter_full_payload_model_parse() -> None:
     class MyModel(BaseModel):
         a: int
         b: float
 
-    async def fn(model: Annotated[MyModel, Root()]) -> None: ...
+    async def fn(model: Annotated[MyModel, FullPayload()]) -> None: ...
 
     conv = PydanticConverter(fn, fn_locals=locals(), correlation_id=None)
     args, kwargs = await conv.convert_inputs(
@@ -795,12 +795,12 @@ async def fn(model: Annotated[MyModel, Root()]) -> None: ...
     assert kwargs == {"model": MyModel(a=1, b=2.5)}
 
 
-async def test_pydantic_converter_root_model_schema() -> None:
+async def test_pydantic_converter_full_payload_model_schema() -> None:
     class MyModel(BaseModel):
         a: int
         b: float
 
-    async def fn(model: Annotated[MyModel, Root()]) -> None: ...
+    async def fn(model: Annotated[MyModel, FullPayload()]) -> None: ...
 
     conv = PydanticConverter(fn, fn_locals=locals(), correlation_id=None)
     schema = conv.get_input_schema()
@@ -817,12 +817,12 @@ async def fn(model: Annotated[MyModel, Root()]) -> None: ...
     assert schema.content_type == "application/json"
 
 
-async def test_pydantic_converter_root_model_with_extra_kwargs() -> None:
+async def test_pydantic_converter_full_payload_model_with_extra_kwargs() -> None:
     class MyModel(BaseModel):
         a: int
         b: float
 
-    async def fn(model: Annotated[MyModel, Root()], extra: str = "default") -> None: ...
+    async def fn(model: Annotated[MyModel, FullPayload()], extra: str = "default") -> None: ...
 
     conv = PydanticConverter(fn, fn_locals=locals(), correlation_id=None)
     args, kwargs = await conv.convert_inputs(
@@ -842,11 +842,11 @@ async def fn(model: Annotated[MyModel, Root()], extra: str = "default") -> None:
     assert kwargs["model"].b == 2.5
 
 
-async def test_pydantic_converter_root_model_with_extra_kwargs_schema() -> None:
+async def test_pydantic_converter_full_payload_model_with_extra_kwargs_schema() -> None:
     class MyModel(BaseModel):
         a: int
 
-    async def fn(model: Annotated[MyModel, Root()], extra: str = "default") -> None: ...
+    async def fn(model: Annotated[MyModel, FullPayload()], extra: str = "default") -> None: ...
 
     conv = PydanticConverter(fn, fn_locals=locals(), correlation_id=None)
     schema = conv.get_input_schema()
@@ -857,27 +857,27 @@ async def fn(model: Annotated[MyModel, Root()], extra: str = "default") -> None:
     assert "extra" in props
 
 
-def test_pydantic_converter_root_model_multiple_raises() -> None:
+def test_pydantic_converter_full_payload_model_multiple_raises() -> None:
     class M1(BaseModel):
         a: int
 
     class M2(BaseModel):
         b: int
 
     async def fn(
-        m1: Annotated[M1, Root()],
-        m2: Annotated[M2, Root()],
+        m1: Annotated[M1, FullPayload()],
+        m2: Annotated[M2, FullPayload()],
     ) -> None: ...
 
-    with pytest.raises(ValueError, match="Only one Root\\(\\) marker is allowed per actor"):
+    with pytest.raises(ValueError, match="Only one FullPayload\\(\\) marker is allowed per actor"):
         PydanticConverter(fn, fn_locals=locals(), correlation_id=None)
 
 
-def test_basic_converter_root_model_raises() -> None:
+def test_basic_converter_full_payload_model_raises() -> None:
     class MyModel(BaseModel):
         a: int
 
-    async def fn(model: Annotated[MyModel, Root()]) -> None: ...
+    async def fn(model: Annotated[MyModel, FullPayload()]) -> None: ...
 
-    with pytest.raises(ValueError, match="Root\\(\\) requires PydanticConverter"):
+    with pytest.raises(ValueError, match="FullPayload\\(\\) requires PydanticConverter"):
         BasicConverter(fn, fn_locals=locals(), correlation_id=None)