iii-helpers 0.19.4a2__tar.gz

iii_helpers-0.19.4a2/.gitignore

@@ -0,0 +1,92 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~

iii_helpers-0.19.4a2/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: iii-helpers
+Version: 0.19.4a2
+Summary: Shared helper primitives across iii SDKs.
+Project-URL: Homepage, https://github.com/iii-hq/iii
+Project-URL: Repository, https://github.com/iii-hq/iii
+Author: III
+License: Apache-2.0
+Keywords: helpers,iii
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# iii-helpers
+
+Shared helper primitives across the iii SDKs.
+
+See https://github.com/iii-hq/iii for the full project.

iii_helpers-0.19.4a2/README.md

@@ -0,0 +1,5 @@
+# iii-helpers
+
+Shared helper primitives across the iii SDKs.
+
+See https://github.com/iii-hq/iii for the full project.

iii_helpers-0.19.4a2/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "iii-helpers"
+version = "0.19.4a2"
+description = "Shared helper primitives across iii SDKs."
+authors = [{ name = "III" }]
+license = { text = "Apache-2.0" }
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["iii", "helpers"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/iii-hq/iii"
+Repository = "https://github.com/iii-hq/iii"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=6.0",
+    "pytest-httpx>=0.30",
+    "mypy>=1.8",
+    "ruff>=0.2",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/iii_helpers"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+addopts = "--cov=src/iii_helpers --cov-branch --cov-report=term-missing"
+testpaths = ["tests"]
+asyncio_mode = "auto"

iii_helpers-0.19.4a2/src/iii_helpers/__init__.py

@@ -0,0 +1 @@
+"""iii helpers."""

iii_helpers-0.19.4a2/src/iii_helpers/http/__init__.py

@@ -0,0 +1,142 @@
+"""iii http helpers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Generic, Literal, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if TYPE_CHECKING:
+    from iii.types import StreamRequest, StreamResponse
+
+TInput = TypeVar("TInput")
+TOutput = TypeVar("TOutput")
+
+HttpMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+"""HTTP method accepted by :data:`HttpInvocationConfig`. Distinct from the core
+``builtin_triggers`` HTTP method enum, which also covers HEAD/OPTIONS."""
+
+
+class HttpAuthHmac(BaseModel):
+    """HMAC signature verification using a shared secret."""
+
+    type: Literal["hmac"] = "hmac"
+    secret_key: str = Field(description="Environment variable name containing the HMAC shared secret.")
+
+
+class HttpAuthBearer(BaseModel):
+    """Bearer token authentication."""
+
+    type: Literal["bearer"] = "bearer"
+    token_key: str = Field(description="Environment variable name containing the bearer token.")
+
+
+class HttpAuthApiKey(BaseModel):
+    """API key sent via a custom header."""
+
+    type: Literal["api_key"] = "api_key"
+    header: str = Field(description="HTTP header name for the API key.")
+    value_key: str = Field(description="Environment variable name containing the API key value.")
+
+
+HttpAuthConfig = HttpAuthHmac | HttpAuthBearer | HttpAuthApiKey
+"""Authentication configuration for HTTP-invoked functions."""
+
+
+class HttpInvocationConfig(BaseModel):
+    """Config for HTTP external function invocation.
+
+    Attributes:
+        url: Target URL for the HTTP invocation.
+        method: HTTP method. Defaults to ``'POST'``.
+        timeout_ms: Request timeout in milliseconds.
+        headers: Additional HTTP headers to include in the request.
+        auth: Authentication configuration (bearer, HMAC, or API key).
+    """
+
+    url: str = Field(description="Target URL for the HTTP invocation.")
+    method: HttpMethod = Field(default="POST", description="HTTP method. Defaults to ``'POST'``.")
+    timeout_ms: int | None = Field(default=None, description="Request timeout in milliseconds.")
+    headers: dict[str, str] | None = Field(
+        default=None,
+        description="Additional HTTP headers to include in the request.",
+    )
+    auth: HttpAuthConfig | None = Field(
+        default=None,
+        description="Authentication configuration (bearer, HMAC, or API key).",
+    )
+
+
+class HttpRequest(BaseModel, Generic[TInput]):
+    """Represents a buffered HTTP request."""
+
+    path_params: dict[str, str] = Field(default_factory=dict)
+    query_params: dict[str, str | list[str]] = Field(default_factory=dict)
+    body: Any | None = None
+    headers: dict[str, str | list[str]] = Field(default_factory=dict)
+    method: str = "GET"
+
+
+class HttpResponse(BaseModel, Generic[TOutput]):
+    """Represents a buffered HTTP response."""
+
+    model_config = ConfigDict(populate_by_name=True, arbitrary_types_allowed=True)
+
+    status_code: int = Field(alias="statusCode")
+    body: Any | None = None
+    headers: dict[str, str] = Field(default_factory=dict)
+
+
+def http(
+    callback: Callable[[StreamRequest, StreamResponse], Awaitable[HttpResponse[Any] | None]],
+) -> Callable[[Any], Awaitable[HttpResponse[Any] | None]]:
+    """Wrap a streaming handler so it receives typed StreamRequest and StreamResponse.
+
+    Takes a callback ``(req, res) -> HttpResponse | None`` and returns a
+    function the iii engine can invoke directly.  The wrapper converts the
+    raw dict (or ``InternalHttpRequest``) delivered by the engine into the
+    typed ``StreamRequest`` / ``StreamResponse`` pair that the callback expects.
+    """
+    from iii.types import InternalHttpRequest, StreamRequest, StreamResponse
+
+    async def wrapper(req: Any) -> HttpResponse[Any] | None:
+        if isinstance(req, InternalHttpRequest):
+            internal = req
+        elif isinstance(req, dict):
+            internal = InternalHttpRequest(
+                path_params=req.get("path_params", {}),
+                query_params=req.get("query_params", {}),
+                body=req.get("body"),
+                headers=req.get("headers", {}),
+                method=req.get("method", "GET"),
+                response=req["response"],
+                request_body=req["request_body"],
+            )
+        else:
+            internal = req
+
+        http_response = StreamResponse(internal.response)
+        http_request = StreamRequest(
+            path_params=internal.path_params,
+            query_params=internal.query_params,
+            body=internal.body,
+            headers=internal.headers,
+            method=internal.method,
+            request_body=internal.request_body,
+        )
+        return await callback(http_request, http_response)
+
+    return wrapper
+
+
+__all__ = [
+    "HttpAuthApiKey",
+    "HttpAuthBearer",
+    "HttpAuthConfig",
+    "HttpAuthHmac",
+    "HttpInvocationConfig",
+    "HttpMethod",
+    "HttpRequest",
+    "HttpResponse",
+    "http",
+]

iii_helpers-0.19.4a2/src/iii_helpers/queue/__init__.py

@@ -0,0 +1,18 @@
+"""iii queue helpers."""
+
+from pydantic import BaseModel, Field
+
+
+class EnqueueResult(BaseModel):
+    """Result returned when a function is invoked with ``TriggerAction.Enqueue``.
+
+    Attributes:
+        messageReceiptId: UUID assigned by the engine to the enqueued job.
+    """
+
+    messageReceiptId: str = Field(description="UUID assigned by the engine to the enqueued job.")
+
+
+__all__ = [
+    "EnqueueResult",
+]

iii_helpers-0.19.4a2/src/iii_helpers/stream/__init__.py

@@ -0,0 +1,334 @@
+"""iii stream helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, Literal, TypeVar
+
+from pydantic import BaseModel, Field, model_serializer
+
+__all__ = [
+    "MergePath",
+    "StreamAuthInput",
+    "StreamAuthResult",
+    "StreamChangeEvent",
+    "StreamChangeEventDetail",
+    "StreamContext",
+    "StreamDeleteInput",
+    "StreamDeleteResult",
+    "StreamGetInput",
+    "StreamJoinLeaveEvent",
+    "StreamJoinLeaveTriggerConfig",
+    "StreamJoinResult",
+    "StreamListGroupsInput",
+    "StreamListInput",
+    "StreamSetInput",
+    "StreamSetResult",
+    "StreamTriggerConfig",
+    "StreamUpdateInput",
+    "StreamUpdateResult",
+    "UpdateAppend",
+    "UpdateDecrement",
+    "UpdateIncrement",
+    "UpdateMerge",
+    "UpdateOp",
+    "UpdateOpError",
+    "UpdateRemove",
+    "UpdateSet",
+]
+
+TData = TypeVar("TData")
+
+# Path target for a ``merge`` / ``append`` op. Accepts either a single
+# string (legacy / first-level key) or a list of literal segments
+# (nested path). Mirrors the Node ``string | string[]`` alias and the
+# Rust ``MergePath`` enum.
+MergePath = str | list[str]
+
+
+class StreamAuthInput(BaseModel):
+    """Input for stream authentication."""
+
+    headers: dict[str, str]
+    path: str
+    query_params: dict[str, list[str]]
+    addr: str
+
+
+class StreamAuthResult(BaseModel):
+    """Result of stream authentication."""
+
+    context: Any | None = None
+
+
+StreamContext = Any
+
+
+class StreamJoinLeaveEvent(BaseModel):
+    """Event for stream join/leave."""
+
+    subscription_id: str
+    stream_name: str
+    group_id: str
+    id: str | None = None
+    context: Any | None = None
+
+
+class StreamJoinResult(BaseModel):
+    """Result of stream join."""
+
+    unauthorized: bool
+
+
+class StreamGetInput(BaseModel):
+    """Input for stream get operation."""
+
+    stream_name: str
+    group_id: str
+    item_id: str
+
+
+class StreamSetInput(BaseModel):
+    """Input for stream set operation."""
+
+    stream_name: str
+    group_id: str
+    item_id: str
+    data: Any
+
+
+class StreamDeleteInput(BaseModel):
+    """Input for stream delete operation."""
+
+    stream_name: str
+    group_id: str
+    item_id: str
+
+
+class StreamListInput(BaseModel):
+    """Input for stream list operation."""
+
+    stream_name: str
+    group_id: str
+
+
+class StreamListGroupsInput(BaseModel):
+    """Input for stream list groups operation."""
+
+    stream_name: str
+
+
+class StreamUpdateInput(BaseModel):
+    """Input for stream update operation."""
+
+    stream_name: str
+    group_id: str
+    item_id: str
+    ops: list["UpdateOp"]
+
+
+class UpdateOpError(BaseModel):
+    """Per-op error returned by ``state::update`` / ``stream::update``.
+
+    Currently emitted only by the ``merge`` op when input violates the
+    new validation bounds. Successfully applied ops are still
+    reflected in the response's ``new_value``.
+    """
+
+    op_index: int
+    code: str
+    message: str
+    doc_url: str | None = None
+
+
+class StreamSetResult(BaseModel, Generic[TData]):
+    """Result of stream set operation."""
+
+    old_value: TData | None = None
+    new_value: TData
+
+
+class StreamUpdateResult(BaseModel, Generic[TData]):
+    """Result of stream update operation."""
+
+    old_value: TData | None = None
+    new_value: TData
+    # Per-op errors. Emitted by ``merge`` and ``append`` for validation
+    # rejections (path/value bounds, proto-pollution segments) and by
+    # ``append`` for the ``append.type_mismatch`` and
+    # ``append.target_not_object`` surfaces. Field is omitted from the
+    # JSON wire when empty. ``default_factory`` is used (not ``= []``)
+    # to keep Pydantic's parameterized-Generic + default handling
+    # well-behaved across Python versions.
+    errors: list[UpdateOpError] = Field(default_factory=list)
+
+
+class StreamDeleteResult(BaseModel):
+    """Result of stream delete operation."""
+
+    old_value: Any | None = None
+
+
+class UpdateSet(BaseModel):
+    """Set operation for stream update."""
+
+    type: str = "set"
+    path: str
+    value: Any
+
+
+class UpdateIncrement(BaseModel):
+    """Increment operation for stream update."""
+
+    type: str = "increment"
+    path: str
+    by: int | float
+
+
+class UpdateDecrement(BaseModel):
+    """Decrement operation for stream update."""
+
+    type: str = "decrement"
+    path: str
+    by: int | float
+
+
+class UpdateAppend(BaseModel):
+    """Append an element to an array, concatenate a string, or push at a nested path.
+
+    The target is the root (when ``path`` is omitted, an empty string,
+    or an empty list), a single first-level key (when ``path`` is a
+    non-empty string), or an arbitrary nested location (when ``path``
+    is a list of literal segments).
+
+    Path forms accepted (mirrors :class:`UpdateMerge` after #1547):
+      - ``None`` / ``""`` / ``[]``: append at the root.
+      - ``"foo"``: append at the first-level key ``foo``. A dotted
+        string like ``"a.b"`` is the literal key ``"a.b"``, *not*
+        traversed as ``a -> b``.
+      - ``["a", "b", "c"]``: nested path; each element is a literal
+        segment.
+
+    Engine semantics:
+      - Missing/non-object intermediates along a nested path are
+        auto-created/replaced with ``{}``.
+      - At the leaf:
+          - missing/null + nested path -> ``[value]`` (always an array)
+          - missing/null + single-string path -> string-as-string for
+            the string-concat tier, otherwise ``[value]``
+          - existing array -> push
+          - existing string + string value -> concatenate
+          - existing object/scalar at the leaf -> ``append.type_mismatch``
+
+    Validation: invalid paths (depth > 32 segments, segment > 256
+    bytes, or any ``__proto__`` / ``constructor`` / ``prototype``
+    segment) are rejected with a structured error in the ``errors``
+    field of the ``state::update`` / ``stream::update`` response. The
+    append does not apply when an error is returned for that op.
+    """
+
+    type: str = "append"
+    # Optional. Accepts a single string (legacy / first-level key) or
+    # a list of literal segments (nested append). ``None`` / ``""`` /
+    # ``[]`` all route to root append. See :data:`MergePath`.
+    path: MergePath | None = None
+    value: Any
+
+    @model_serializer(mode="wrap")
+    def _omit_none_path(self, handler):  # type: ignore[no-untyped-def]
+        # Drop ``path: None`` from the wire so cross-SDK consumers see
+        # the field absent rather than ``null``. Mirrors the Rust
+        # ``#[serde(skip_serializing_if = "Option::is_none")]`` on
+        # ``UpdateOp::Append.path``.
+        data = handler(self)
+        if data.get("path") is None:
+            data.pop("path", None)
+        return data
+
+
+class UpdateRemove(BaseModel):
+    """Remove operation for stream update."""
+
+    type: str = "remove"
+    path: str
+
+
+class UpdateMerge(BaseModel):
+    """Shallow merge an object into the target.
+
+    The target is the root (when ``path`` is omitted, an empty string,
+    or an empty list) or an arbitrary nested location specified by an
+    array of literal segments.
+
+    Path forms accepted:
+      - ``None`` / ``""`` / ``[]``: merge at the root.
+      - ``"foo"``: equivalent to ``["foo"]`` -- single first-level key.
+      - ``["a", "b", "c"]``: nested path. Each element is a *literal*
+        key. ``["a.b"]`` writes a single key named ``"a.b"``, not
+        ``a -> b``.
+
+    Engine semantics:
+      - Missing or non-object intermediates along the path are
+        auto-replaced with ``{}``.
+      - The merge is shallow at the target node (top-level keys of
+        ``value`` overwrite same-named keys; siblings preserved).
+
+    Validation: invalid paths/values (depth > 32 segments, segment >
+    256 bytes, value depth > 16, > 1024 top-level keys, or any
+    ``__proto__`` / ``constructor`` / ``prototype`` segment or
+    top-level key) are rejected with a structured error in the
+    ``errors`` array of the ``state::update`` / ``stream::update``
+    response. The merge does not apply when an error is returned.
+    """
+
+    type: str = "merge"
+    # Optional. Accepts a single string or a list of literal segments.
+    # Pydantic resolves ``str | list[str]`` via smart-union: string
+    # input -> str, array input -> list[str]. See :data:`MergePath`.
+    path: MergePath | None = None
+    value: Any
+
+    @model_serializer(mode="wrap")
+    def _omit_none_path(self, handler):  # type: ignore[no-untyped-def]
+        # Mirrors the same skip-when-none rule applied to
+        # ``UpdateOp::Merge.path`` in the Rust SDK so cross-SDK wire
+        # payloads are byte-identical for root merges.
+        data = handler(self)
+        if data.get("path") is None:
+            data.pop("path", None)
+        return data
+
+
+UpdateOp = UpdateSet | UpdateIncrement | UpdateDecrement | UpdateAppend | UpdateRemove | UpdateMerge
+
+
+class StreamTriggerConfig(BaseModel):
+    """Trigger config for ``stream`` triggers. Filters which item changes fire the handler."""
+
+    stream_name: str
+    group_id: str | None = None
+    item_id: str | None = None
+    condition_function_id: str | None = None
+
+
+class StreamJoinLeaveTriggerConfig(BaseModel):
+    """Trigger config for ``stream:join`` and ``stream:leave`` triggers."""
+
+    condition_function_id: str | None = None
+
+
+class StreamChangeEventDetail(BaseModel):
+    """Detail of a stream change event containing the mutation type and data."""
+
+    type: Literal["create", "update", "delete"]
+    data: Any
+
+
+class StreamChangeEvent(BaseModel):
+    """Handler input for ``stream`` triggers, fired when an item changes."""
+
+    type: Literal["stream"]
+    timestamp: int
+    streamName: str
+    groupId: str
+    id: str | None = None
+    event: StreamChangeEventDetail