vention-communication 0.3.0__py3-none-any.whl → 0.3.4__py3-none-any.whl

communication/codegen.py

@@ -1,17 +1,30 @@
 from __future__ import annotations
-from typing import Any, Dict, List, Optional, Type, Union, get_args, get_origin
+import sys
+from typing import Any, Dict, List, Optional, Type, Union, get_args, get_origin, Annotated
 
 from .decorators import collect_bundle
 from .typing_utils import is_pydantic_model
 from .entries import RpcBundle, StreamEntry
 
+
+# Handle Python 3.10+ types.UnionType
+if sys.version_info >= (3, 10):
+    from types import UnionType
+
+    _UNION_TYPES = (Union, UnionType)
+else:
+    _UNION_TYPES = (Union,)
+
 _SCALAR_MAP = {
     int: "int32",
     float: "double",
     str: "string",
     bool: "bool",
+    bytes: "bytes",
 }
 
+MAX_NESTING_DEPTH = 10
+
 HEADER = """syntax = "proto3";
 package vention.app.v1;
 
@@ -20,22 +33,45 @@ import "google/protobuf/empty.proto";
 """
 
 
+def _unwrap_annotated(type_annotation: Any) -> Any:
+    """Unwrap Annotated[T, ...] to get the base type T."""
+    origin = get_origin(type_annotation)
+    if origin is Annotated:
+        args = get_args(type_annotation)
+        if args:
+            return args[0]
+    return type_annotation
+
+
+def _filter_non_none_types(args: tuple[Any, ...]) -> list[Any]:
+    """Filter out NoneType from union type arguments."""
+    return [arg for arg in args if arg is not type(None)]
+
+
 def _unwrap_optional(type_annotation: Any) -> tuple[Any, bool]:
+    type_annotation = _unwrap_annotated(type_annotation)
+
     origin = get_origin(type_annotation)
-    if origin is Union:
+    # Handle both typing.Union and types.UnionType (Python 3.10+)
+    if origin in _UNION_TYPES:
         args = get_args(type_annotation)
-        non_none_args = [arg for arg in args if arg is not type(None)]
+        non_none_args = _filter_non_none_types(args)
         if len(non_none_args) == 1:
-            return (non_none_args[0], True)
+            # Recursively unwrap in case the inner type is also Annotated
+            return (_unwrap_annotated(non_none_args[0]), True)
     return (type_annotation, False)
 
 
 def _unwrap_list(type_annotation: Any) -> tuple[Any, bool]:
+    # First unwrap Annotated if present
+    type_annotation = _unwrap_annotated(type_annotation)
+
     origin = get_origin(type_annotation)
     if origin in (list, List):
         args = get_args(type_annotation)
         if args:
-            return (args[0], True)
+            # Unwrap Annotated from the inner type as well
+            return (_unwrap_annotated(args[0]), True)
     return (type_annotation, False)
 
 
@@ -47,16 +83,20 @@ def _determine_proto_type_for_field(
     inner_type: Type[Any],
     seen_models: set[str],
     lines: list[str],
+    depth: int = 0,
 ) -> str:
+    if depth > MAX_NESTING_DEPTH:
+        raise ValueError(f"Maximum nesting depth ({MAX_NESTING_DEPTH}) exceeded in proto generation")
+
     if inner_type in _SCALAR_MAP:
         return _SCALAR_MAP[inner_type]
 
     if is_pydantic_model(inner_type):
         model_name = inner_type.__name__
-        # Recursively register nested model if not seen before
+
         if model_name not in seen_models:
             seen_models.add(model_name)
-            lines.extend(_generate_pydantic_message(inner_type, seen_models, lines))
+            lines.extend(_generate_pydantic_message(inner_type, seen_models, lines, depth + 1))
         return model_name
 
     # Fallback to string for unknown types
@@ -69,14 +109,18 @@ def _process_pydantic_field(
     field_index: int,
     seen_models: set[str],
     lines: list[str],
+    depth: int = 0,
 ) -> str:
-    inner_type, _ = _unwrap_optional(field_type)
-    list_inner_type, is_list = _unwrap_list(inner_type)
+    unwrapped_type = _unwrap_annotated(field_type)
+    unwrapped_type, _ = _unwrap_optional(unwrapped_type)
+    list_inner_type, is_list = _unwrap_list(unwrapped_type)
+    # One more unwrap in case list contains Optional[Annotated[...]]
+    final_inner_type = _unwrap_annotated(list_inner_type)
 
-    proto_type = _determine_proto_type_for_field(list_inner_type, seen_models, lines)
+    proto_type = _determine_proto_type_for_field(final_inner_type, seen_models, lines, depth)
 
     if is_list:
-        proto_type = f"repeated {proto_type}"
+        return f"  repeated {proto_type} {field_name} = {field_index};"
 
     return f"  {proto_type} {field_name} = {field_index};"
 
@@ -85,6 +129,7 @@ def _generate_pydantic_message(
     type_annotation: Type[Any],
     seen_models: set[str],
     lines: list[str],
+    depth: int = 0,
 ) -> list[str]:
     model_name = type_annotation.__name__
     fields = []
@@ -97,6 +142,7 @@ def _generate_pydantic_message(
             field_index,
             seen_models,
             lines,
+            depth,
         )
         fields.append(field_line)
         field_index += 1
@@ -107,9 +153,7 @@ def _generate_pydantic_message(
     return lines_result
 
 
-def _generate_scalar_wrapper_message(
-    stream_name: str, payload_type: Type[Any]
-) -> list[str]:
+def _generate_scalar_wrapper_message(stream_name: str, payload_type: Type[Any]) -> list[str]:
     wrapper_name = _msg_name_for_scalar_stream(stream_name)
     lines = [
         f"message {wrapper_name} {{",
@@ -150,17 +194,15 @@ def _register_pydantic_model(
     if type_annotation is None:
         return
 
-    inner_type, _ = _unwrap_optional(type_annotation)
+    unwrapped_type, _ = _unwrap_optional(type_annotation)
 
-    list_inner_type, _ = _unwrap_list(inner_type)
+    list_inner_type, _ = _unwrap_list(unwrapped_type)
 
     if is_pydantic_model(list_inner_type):
         model_name = list_inner_type.__name__
         if model_name not in seen_models:
             seen_models.add(model_name)
-            lines.extend(
-                _generate_pydantic_message(list_inner_type, seen_models, lines)
-            )
+            lines.extend(_generate_pydantic_message(list_inner_type, seen_models, lines))
 
 
 def _process_stream_payload(
@@ -169,17 +211,15 @@ def _process_stream_payload(
     lines: list[str],
     scalar_wrappers: Dict[str, str],
 ) -> None:
-    inner_type, _ = _unwrap_optional(stream_entry.payload_type)
-    list_inner_type, _ = _unwrap_list(inner_type)
+    unwrapped_type, _ = _unwrap_optional(stream_entry.payload_type)
+    list_inner_type, _ = _unwrap_list(unwrapped_type)
 
     if is_pydantic_model(list_inner_type):
         _register_pydantic_model(list_inner_type, seen_models, lines)
     elif list_inner_type in _SCALAR_MAP:
         wrapper_name = _msg_name_for_scalar_stream(stream_entry.name)
         scalar_wrappers[stream_entry.name] = wrapper_name
-        lines.extend(
-            _generate_scalar_wrapper_message(stream_entry.name, list_inner_type)
-        )
+        lines.extend(_generate_scalar_wrapper_message(stream_entry.name, list_inner_type))
 
 
 def _collect_message_types(
@@ -196,25 +236,17 @@ def _collect_message_types(
         _process_stream_payload(stream_entry, seen_models, lines, scalar_wrappers)
 
 
-def _generate_service_rpcs(
-    bundle: RpcBundle, lines: list[str], scalar_wrappers: Dict[str, str]
-) -> None:
+def _generate_service_rpcs(bundle: RpcBundle, lines: list[str], scalar_wrappers: Dict[str, str]) -> None:
     rpc_prefix = "  rpc"
 
     for action_entry in bundle.actions:
         input_type = _proto_type_name(action_entry.input_type, scalar_wrappers)
         output_type = _proto_type_name(action_entry.output_type, scalar_wrappers)
-        lines.append(
-            f"{rpc_prefix} {action_entry.name} ({input_type}) returns ({output_type});"
-        )
+        lines.append(f"{rpc_prefix} {action_entry.name} ({input_type}) returns ({output_type});")
 
     for stream_entry in bundle.streams:
-        output_type = _proto_type_name(
-            stream_entry.payload_type, scalar_wrappers, stream_entry.name
-        )
-        lines.append(
-            f"{rpc_prefix} {stream_entry.name} (google.protobuf.Empty) returns (stream {output_type});"
-        )
+        output_type = _proto_type_name(stream_entry.payload_type, scalar_wrappers, stream_entry.name)
+        lines.append(f"{rpc_prefix} {stream_entry.name} (google.protobuf.Empty) returns (stream {output_type});")
 
 
 def generate_proto(app_name: str, *, bundle: Optional[RpcBundle] = None) -> str:

communication/connect_router.py

@@ -18,9 +18,7 @@ CONTENT_TYPE = "application/connect+json"
 
 
 def _frame(payload: Dict[str, Any], *, trailer: bool = False) -> bytes:
-    body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode(
-        "utf-8"
-    )
+    body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
     flag = 0x80 if trailer else 0x00
     header = bytes([flag]) + len(body).to_bytes(4, byteorder="big", signed=False)
     return header + body
@@ -121,9 +119,7 @@ class StreamManager:
         """
         topic = self._topics[stream_name]
         entry: StreamEntry = topic["entry"]
-        subscriber_queue: asyncio.Queue[Any] = asyncio.Queue(
-            maxsize=entry.queue_maxsize
-        )
+        subscriber_queue: asyncio.Queue[Any] = asyncio.Queue(maxsize=entry.queue_maxsize)
         subscriber = _Subscriber(queue=subscriber_queue)
         topic["subscribers"].add(subscriber)
         self.start_distributor_if_needed(stream_name)
@@ -217,7 +213,7 @@ class ConnectRouter:
                     result = await _maybe_await(entry.func(validated_arg))
 
                 if hasattr(result, "model_dump"):
-                    result = result.model_dump(by_alias=True)
+                    result = result.model_dump(mode="json", by_alias=True)
                 return JSONResponse(result or {})
             except Exception as exc:
                 return JSONResponse(error_envelope(exc))
@@ -283,7 +279,7 @@ class ConnectRouter:
 
 def _serialize_stream_item(item: Any) -> Dict[str, Any]:
     if hasattr(item, "model_dump"):
-        dumped = item.model_dump(by_alias=True)
+        dumped = item.model_dump(mode="json", by_alias=True)
         if isinstance(dumped, dict):
             return dumped
         return {"value": dumped}

communication/decorators.py

@@ -38,9 +38,7 @@ def action(
     def decorator(function: Callable[..., Any]) -> Callable[..., Any]:
         input_type = infer_input_type(function)
         output_type = infer_output_type(function)
-        entry = ActionEntry(
-            name or function.__name__, function, input_type, output_type
-        )
+        entry = ActionEntry(name or function.__name__, function, input_type, output_type)
         _actions.append(entry)
         return function
 
@@ -71,9 +69,7 @@ def stream(
         Decorator function that registers the stream
     """
     if not (is_pydantic_model(payload) or payload in (int, float, str, bool, dict)):
-        raise ValueError(
-            "payload must be a pydantic BaseModel or a JSON-serializable scalar/dict"
-        )
+        raise ValueError("payload must be a pydantic BaseModel or a JSON-serializable scalar/dict")
 
     def decorator(function: Callable[..., Any]) -> Callable[..., Any]:
         entry = StreamEntry(

communication/errors.py

@@ -5,9 +5,7 @@ from typing import Any, Dict, List, Optional
 class ConnectError(Exception):
     """Application-level error to send over Connect transport."""
 
-    def __init__(
-        self, code: str, message: str, *, details: Optional[List[Any]] = None
-    ) -> None:
+    def __init__(self, code: str, message: str, *, details: Optional[List[Any]] = None) -> None:
         super().__init__(message)
         self.code = code
         self.message = message

communication/rpc_registry.py

@@ -39,9 +39,7 @@ class RpcRegistry:
         return merged
 
     # ------------- Model normalization / aliasing -------------
-    def _normalize_model(
-        self, model: Optional[Type[BaseModel]], seen: Set[Type[BaseModel]]
-    ) -> None:
+    def _normalize_model(self, model: Optional[Type[BaseModel]], seen: Set[Type[BaseModel]]) -> None:
         """Recursively normalize a model and all its nested models."""
         if model is None:
             return

communication/typing_utils.py

@@ -94,9 +94,7 @@ def is_pydantic_model(type_annotation: Any) -> bool:
         True if the type is a Pydantic BaseModel subclass, False otherwise
     """
     try:
-        return isinstance(type_annotation, type) and issubclass(
-            type_annotation, BaseModel
-        )
+        return isinstance(type_annotation, type) and issubclass(type_annotation, BaseModel)
     except Exception:
         return False
 
@@ -120,9 +118,7 @@ def apply_aliases(model_cls: Type[BaseModel]) -> None:
     if existing_config is None:
         existing_dict: dict[str, Any] = {}
     else:
-        existing_dict = (
-            dict(existing_config) if isinstance(existing_config, dict) else {}
-        )
+        existing_dict = dict(existing_config) if isinstance(existing_config, dict) else {}
 
     merged_config: dict[str, Any] = {
         "populate_by_name": True,

{vention_communication-0.3.0.dist-info → vention_communication-0.3.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vention-communication
-Version: 0.3.0
+Version: 0.3.4
 Summary: A framework for communication between machine apps and other services.
 License: Proprietary
 Author: VentionCo
@@ -8,8 +8,22 @@ Requires-Python: >=3.10,<3.11
 Classifier: License :: Other/Proprietary License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
-Requires-Dist: fastapi (==0.121.1)
-Requires-Dist: uvicorn (>=0.35.0,<0.36.0)
+Requires-Dist: annotated-doc (==0.0.4) ; python_version == "3.10"
+Requires-Dist: annotated-types (==0.7.0) ; python_version == "3.10"
+Requires-Dist: anyio (==4.11.0) ; python_version == "3.10"
+Requires-Dist: click (==8.1.8) ; python_version == "3.10"
+Requires-Dist: colorama (==0.4.6) ; python_version == "3.10" and platform_system == "Windows"
+Requires-Dist: exceptiongroup (==1.3.0) ; python_version == "3.10"
+Requires-Dist: fastapi (==0.121.1) ; python_version == "3.10"
+Requires-Dist: h11 (==0.16.0) ; python_version == "3.10"
+Requires-Dist: idna (==3.11) ; python_version == "3.10"
+Requires-Dist: pydantic (==2.12.3) ; python_version == "3.10"
+Requires-Dist: pydantic-core (==2.41.4) ; python_version == "3.10"
+Requires-Dist: sniffio (==1.3.1) ; python_version == "3.10"
+Requires-Dist: starlette (==0.48.0) ; python_version == "3.10"
+Requires-Dist: typing-extensions (==4.15.0) ; python_version == "3.10"
+Requires-Dist: typing-inspection (==0.4.2) ; python_version == "3.10"
+Requires-Dist: uvicorn (==0.35.0) ; python_version == "3.10"
 Description-Content-Type: text/markdown
 
 # Vention Communication
@@ -88,8 +102,10 @@ A complete "hello world" in three steps.
 
 ```python
 from pydantic import BaseModel
-from vention_communication import VentionApp, action, stream
-import time, random
+from communication.app import VentionApp
+from communication.decorators import action, stream
+import time
+import random
 
 class PingRequest(BaseModel):
     message: str
@@ -114,6 +130,15 @@ async def heartbeat():
 
 app.finalize()
 
+# Emit heartbeat every second
+@app.on_event("startup")
+async def startup():
+    asyncio.create_task(loop())
+
+async def loop():
+    while True:
+        asyncio.create_task(heartbeat())
+        await asyncio.sleep(1)
 ```
 
 **Run:**
@@ -128,21 +153,59 @@ Endpoints are automatically registered under `/rpc/vention.app.v1.DemoAppService
 
 After startup, `proto/app.proto` is emitted automatically.
 
-You can now use Buf or protoc to generate client SDKs:
+You can now use Buf or protoc to generate client SDKs, based on each client stack you desire.
+
+The next section will provide an example for Typescript applications, but for any other environment, please refer to the official documentation on how to install and quickstart code generation:
+
+https://buf.build/docs/cli/installation/
+
+### 3. Example TypeScript Client
+
+    Make sure you have Node 24+ installed. Use [NVM](https://github.com/nvm-sh/nvm) to easily install and manage different Node versions.
+
+1. Create a folder called `client` and `cd` into it.
+
+#### Protobuf Javascript/Typescript libraries
+
+2. Install the runtime library, code generator, and the Buf CLI:
 
 ```bash
-buf generate --template buf.gen.ts.yaml
-buf generate --template buf.gen.python.yaml
+npm install @bufbuild/protobuf
+npm install --save-dev @bufbuild/protoc-gen-es @bufbuild/buf
 ```
 
-SDK generation is external to vention-communication — allowing you to control versions and plugins.
+3. Create a buf.gen.yaml file that looks like this:
 
-### 3. Example TypeScript Client
+```yaml
+version: v2
+inputs:
+  - directory: proto
+plugins:
+  - local: protoc-gen-es
+    opt: target=ts
+    out: src/gen
+```
+
+4. Generate the client code, pointing the path to the newly generated *proto* folder:
+
+```bash
+npx buf generate ../proto
+```
+
+#### Client Application
+
+1. Install the client RPC libraries:
+
+```bash
+npm i @connectrpc/connect @connectrpc/connect-web
+```
+
+2. Then create an `index.ts` file in the `client/src` folder, and paste the following code in it:
 
 ```typescript
 import { createClient } from "@connectrpc/connect";
 import { createConnectTransport } from "@connectrpc/connect-web";
-import { DemoAppService } from "./gen/connect/proto/app_connect";
+import { DemoAppService } from "./gen/connect/app_pb.ts";
 
 const transport = createConnectTransport({
   baseUrl: "http://localhost:8000/rpc",
@@ -164,8 +227,11 @@ for await (const hb of client.heartbeat({})) {
 ### Add a new request-response endpoint
 
 ```python
+class StatusResponse(BaseModel):
+    ok: bool
+
 @action()
-async def get_status() -> dict:
+async def get_status() -> StatusResponse:
     return {"ok": True}
 ```
 
@@ -173,7 +239,7 @@ async def get_status() -> dict:
 
 ```python
 @stream(name="Status", payload=dict)
-async def publish_status() -> dict:
+async def publish_status() -> StatusResponse:
     return {"ok": True}
 ```
 

vention_communication-0.3.4.dist-info/RECORD

@@ -0,0 +1,13 @@
+communication/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+communication/app.py,sha256=dxbm7oG8-uQSu_dY4S8exHsBXND1N1nC2GdsMthqZE0,3423
+communication/codegen.py,sha256=uY-IJ1QggjNPxiGCGfBPhTAL8p_nzYhxSDshkDqm_EQ,8464
+communication/connect_router.py,sha256=fWn2KA8FAKYx1J_6RgtQSqS5hzAdPGEBn4Uk3UlqfqM,10517
+communication/decorators.py,sha256=a16UUi-J2zi9fB3CxMtOygL74VOlCZTrL3hYkyBHvGo,3375
+communication/entries.py,sha256=vdZc8GAQztRWEiav6R2wM4l35GE-EiEdRH0ZJR4GShM,1065
+communication/errors.py,sha256=pwFcb-uce-aPkSXIrM7Ov7XQQXJrNQIgKgRU9QEWrqY,1759
+communication/registry.py,sha256=acbhwU0z1iRHqzOahXG47GfJS5VQHjf69UiruoXrr7g,4517
+communication/rpc_registry.py,sha256=WLu5kRZdZsMr-TCGEXzsAIMQJFk4rPctB4mL53NU70U,2972
+communication/typing_utils.py,sha256=I3FdTTlvcPfiyf7t4nw4--eXf82opwjdGXfVYtprqoU,4513
+vention_communication-0.3.4.dist-info/METADATA,sha256=2cwpJSwgqcpDC7KjGv4HSZbVYkG7lSUEKG4tVhMdGhw,13546
+vention_communication-0.3.4.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+vention_communication-0.3.4.dist-info/RECORD,,

vention_communication-0.3.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-communication/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-communication/app.py,sha256=dxbm7oG8-uQSu_dY4S8exHsBXND1N1nC2GdsMthqZE0,3423
-communication/codegen.py,sha256=_1LYma-MXedwRHn_P3CqPs1xIMEZrZgiUAsGSj9yff4,7089
-communication/connect_router.py,sha256=tjNl9dRukjLecZH1y-GYIQXH-0xzz9JESbikSH5XhFo,10527
-communication/decorators.py,sha256=3pVlXUSX4KXSKlweskF0RfD8pST2zisTuFGJQHHIvcI,3419
-communication/entries.py,sha256=vdZc8GAQztRWEiav6R2wM4l35GE-EiEdRH0ZJR4GShM,1065
-communication/errors.py,sha256=hdJBB9jPJNWx8hbxIxwLBNKt2JVpmhZ1YF8q9VKk-dI,1773
-communication/registry.py,sha256=acbhwU0z1iRHqzOahXG47GfJS5VQHjf69UiruoXrr7g,4517
-communication/rpc_registry.py,sha256=90r4YYHKveVGBO-pOD91qAs9GSB3651WPclC6oRnrZo,2986
-communication/typing_utils.py,sha256=6S6LvtjFBZKo-gWPc8fbh4F1rlPWFgrH_mX8esZbzWM,4559
-vention_communication-0.3.0.dist-info/METADATA,sha256=e6h67l5DGs9LSAL_eBan_spH60FDQfBVcmeyoNWrlvg,11255
-vention_communication-0.3.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-vention_communication-0.3.0.dist-info/RECORD,,