volcano-sdk-python 0.11.0__tar.gz → 0.11.2__tar.gz

volcano_sdk_python-0.11.2/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.11.2"
+}

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.2}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.11.2](https://github.com/Kong/volcano-sdk-python/compare/v0.11.1...v0.11.2) (2026-09-23)
+
+
+### Bug Fixes
+
+* **test:** allow pytest discovery without weakening execution gate ([#324](https://github.com/Kong/volcano-sdk-python/issues/324)) ([ab3d9c5](https://github.com/Kong/volcano-sdk-python/commit/ab3d9c56e03ddf57e15225df623de40d66e12c06))
+
+## [0.11.1](https://github.com/Kong/volcano-sdk-python/compare/v0.11.0...v0.11.1) (2026-09-23)
+
+
+### Bug Fixes
+
+* **storage:** validate optional transport capabilities ([#303](https://github.com/Kong/volcano-sdk-python/issues/303)) ([e6b8e1a](https://github.com/Kong/volcano-sdk-python/commit/e6b8e1a9c677503c510ea58ec2a6956a21fb9652))
+
 ## [0.11.0](https://github.com/Kong/volcano-sdk-python/compare/v0.10.4...v0.11.0) (2026-09-23)
 
 

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.11.0
+Version: 0.11.2
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python

volcano_sdk_python-0.11.2/features/contract_fixture.py

@@ -0,0 +1,141 @@
+"""Typed boundary for the shared SDK contract fixture."""
+
+from __future__ import annotations
+
+from typing import TypeAlias, TypedDict, TypeGuard
+
+ContractRow: TypeAlias = dict[str, str]
+
+
+class UpdateRows(TypedDict):
+    """Expected before and after values for an update scenario."""
+
+    before: ContractRow
+    after: ContractRow
+
+
+class MutationRows(TypedDict):
+    """Rows used by the shared mutation scenarios."""
+
+    insert: ContractRow
+    update: UpdateRows
+    delete: ContractRow
+
+
+class ContractFixture(TypedDict):
+    """Fields provisioned by Hosting for the Python contract runner."""
+
+    api_url: str
+    project_id: str
+    anon_key: str
+    service_key: str
+    platform_token: str
+    user_id: str
+    user_email: str
+    user_password: str
+    database_name: str
+    table_name: str
+    query_table_name: str
+    fixture_row: ContractRow
+    mutation_rows: MutationRows
+    bucket_name: str
+    storage_path: str
+    realtime_channel: str
+    realtime_table_name: str
+    lock_key: str
+    function_name: str
+    function_id: str
+    durable_function_name: str
+    logs_access_token: str
+
+
+STRING_FIELDS = (
+    "api_url",
+    "project_id",
+    "anon_key",
+    "service_key",
+    "platform_token",
+    "user_id",
+    "user_email",
+    "user_password",
+    "database_name",
+    "table_name",
+    "query_table_name",
+    "bucket_name",
+    "storage_path",
+    "realtime_channel",
+    "realtime_table_name",
+    "lock_key",
+    "function_name",
+    "function_id",
+    "durable_function_name",
+    "logs_access_token",
+)
+
+
+def is_object_dict(value: object) -> TypeGuard[dict[object, object]]:
+    """Narrow a decoded dictionary without trusting its keys or values.
+
+    Returns:
+        Whether the value is a dictionary.
+    """
+    return isinstance(value, dict)
+
+
+def is_contract_row(value: object) -> TypeGuard[ContractRow]:
+    """Check the fields read by the database scenarios.
+
+    Returns:
+        Whether the value contains the required row fields.
+    """
+    if not is_object_dict(value):
+        return False
+    return (
+        all(
+            isinstance(key, str) and isinstance(item, str)
+            for key, item in value.items()
+        )
+        and "slug" in value
+        and "value" in value
+    )
+
+
+def is_update_rows(value: object) -> TypeGuard[UpdateRows]:
+    """Check both states of the update scenario.
+
+    Returns:
+        Whether both update states contain valid rows.
+    """
+    if not is_object_dict(value):
+        return False
+    return is_contract_row(value.get("before")) and is_contract_row(value.get("after"))
+
+
+def is_mutation_rows(value: object) -> TypeGuard[MutationRows]:
+    """Check the three mutation fixtures.
+
+    Returns:
+        Whether the insert, update, and delete rows are valid.
+    """
+    if not is_object_dict(value):
+        return False
+    return (
+        is_contract_row(value.get("insert"))
+        and is_update_rows(value.get("update"))
+        and is_contract_row(value.get("delete"))
+    )
+
+
+def is_contract_fixture(value: object) -> TypeGuard[ContractFixture]:
+    """Validate every field consumed by the shared scenarios.
+
+    Returns:
+        Whether the fixture has every required field and row.
+    """
+    if not is_object_dict(value):
+        return False
+    if any(not isinstance(value.get(key), str) for key in STRING_FIELDS):
+        return False
+    return is_contract_row(value.get("fixture_row")) and is_mutation_rows(
+        value.get("mutation_rows")
+    )

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.2}/features/contract_support.py

@@ -5,7 +5,7 @@ import os
 import secrets
 import time
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, TypeVar
 
 from volcano_sdk import (
     AuthenticationError,
@@ -24,6 +24,8 @@ from volcano_sdk.realtime import CENTRIFUGE_ERROR
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
 
+    from contract_fixture import ContractFixture
+
     from volcano_sdk.models import (
         AuthChangeEvent,
         DurableExecution,
@@ -59,11 +61,13 @@ CONTRACT_EXCEPTIONS = (
     VolcanoError,
 )
 
+_ResultT = TypeVar("_ResultT")
+
 
 @dataclass(frozen=True, slots=True)
 class Outcome:
     ok: bool
-    value: Any = None
+    value: object = None
     category: str | None = None
     error: Exception | None = None
 
@@ -111,7 +115,7 @@ def classify_status(status: int | None) -> str:
 
 
 class ContractWorld:
-    def __init__(self, fixture: dict[str, Any]) -> None:
+    def __init__(self, fixture: ContractFixture) -> None:
         self.fixture = fixture
         self.client = VolcanoClient(
             api_url=fixture["api_url"],
@@ -165,7 +169,7 @@ class ContractWorld:
             password=self.fixture["user_password"],
         )
 
-    def run(self, operation: Awaitable[Any]) -> Any:
+    def run(self, operation: Awaitable[_ResultT]) -> _ResultT:
         return self.loop.run_until_complete(operation)
 
     def start_durable_execution(self) -> DurableExecution:
@@ -212,7 +216,7 @@ class ContractWorld:
             self.fixture["durable_function_name"],
         )
 
-    def record(self, operation: Callable[[], Any]) -> Outcome:
+    def record(self, operation: Callable[[], object]) -> Outcome:
         try:
             self.last_outcome = Outcome(ok=True, value=operation())
         except CONTRACT_EXCEPTIONS as error:

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.2}/features/environment.py

@@ -4,42 +4,47 @@ import json
 import os
 import stat
 from pathlib import Path
-from typing import Any, cast
+from typing import TYPE_CHECKING
 
+from contract_fixture import ContractFixture, is_contract_fixture
 from contract_support import ContractWorld
 
+if TYPE_CHECKING:
+    from behave.runner import Context
+
 FIXTURE_MODE = 0o600
 FIXTURE_ABSOLUTE_PATH_ERROR = "VOLCANO_SDK_CONTRACT_FIXTURE must be an absolute path"
 FIXTURE_MODE_ERROR = "VOLCANO_SDK_CONTRACT_FIXTURE must have mode 0600"
-FIXTURE_OBJECT_ERROR = "VOLCANO_SDK_CONTRACT_FIXTURE must contain a JSON object"
+FIXTURE_SHAPE_ERROR = (
+    "VOLCANO_SDK_CONTRACT_FIXTURE must contain a complete contract fixture"
+)
 FIXTURE_REQUIRED_ERROR = "VOLCANO_SDK_CONTRACT_FIXTURE is required"
 
 
-def load_fixture(path: Path) -> dict[str, object]:
+def load_fixture(path: Path) -> ContractFixture:
     if not path.is_absolute():
         raise ValueError(FIXTURE_ABSOLUTE_PATH_ERROR)
     mode = stat.S_IMODE(path.stat().st_mode)
     if mode != FIXTURE_MODE:
         raise PermissionError(FIXTURE_MODE_ERROR)
-    value = json.loads(path.read_text(encoding="utf-8"))
-    if not isinstance(value, dict):
-        raise TypeError(FIXTURE_OBJECT_ERROR)
-    # JSON objects have string keys; the shape check above rejects other values.
-    return cast("dict[str, object]", value)
+    value: object = json.loads(path.read_text(encoding="utf-8"))
+    if not is_contract_fixture(value):
+        raise TypeError(FIXTURE_SHAPE_ERROR)
+    return value
 
 
-def before_all(context: Any) -> None:
+def before_all(context: Context) -> None:
     fixture_path = os.environ.get("VOLCANO_SDK_CONTRACT_FIXTURE")
     if fixture_path is None:
         raise RuntimeError(FIXTURE_REQUIRED_ERROR)
     context.contract_fixture = load_fixture(Path(fixture_path))
 
 
-def before_scenario(context: Any, scenario: Any) -> None:
+def before_scenario(context: Context, scenario: object) -> None:
     del scenario
     context.contract = ContractWorld(context.contract_fixture)
 
 
-def after_scenario(context: Any, scenario: Any) -> None:
+def after_scenario(context: Context, scenario: object) -> None:
     del scenario
     context.contract.cleanup()

{volcano_sdk_python-0.11.0 → volcano_sdk_python-0.11.2}/features/logs_contract.py

@@ -1,16 +1,19 @@
 from __future__ import annotations
 
 import time
+from collections.abc import Mapping
 from datetime import UTC, datetime, timedelta
-from typing import TYPE_CHECKING, Any, TypeVar
+from typing import TYPE_CHECKING, TypeVar
 from uuid import uuid4
 
 from volcano_sdk import VolcanoClient
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Mapping
+    from collections.abc import Callable
 
-    from volcano_sdk.models import JSONValue
+    from contract_support import ContractWorld
+
+    from volcano_sdk.models import JSONValue, LogActivityResponse
 
 _ResultT = TypeVar("_ResultT")
 
@@ -41,8 +44,35 @@ def event_id(event: Mapping[str, JSONValue]) -> str:
     return identity
 
 
+def mapping_field(
+    value: Mapping[str, JSONValue], field: str
+) -> Mapping[str, JSONValue]:
+    nested = value[field]
+    assert isinstance(nested, Mapping)
+    return nested
+
+
+def event_ordinal(event: Mapping[str, JSONValue]) -> int:
+    ordinal = mapping_field(event, "body")["ordinal"]
+    assert isinstance(ordinal, int)
+    return ordinal
+
+
+def bucket_count(bucket: Mapping[str, JSONValue], category: str, key: str) -> int:
+    counts = mapping_field(bucket, "counts")
+    value = mapping_field(counts, category).get(key, 0)
+    assert isinstance(value, int)
+    return value
+
+
+def bucket_total(bucket: Mapping[str, JSONValue]) -> int:
+    total = bucket["total"]
+    assert isinstance(total, int)
+    return total
+
+
 class LogContract:
-    def __init__(self, world: Any) -> None:
+    def __init__(self, world: ContractWorld) -> None:
         self.world = world
         self.client = VolcanoClient(
             api_url=world.fixture["api_url"],
@@ -51,7 +81,7 @@ class LogContract:
             timeout=10,
         )
         self.marker = f"sdklogs{uuid4().hex}"
-        self.request: dict[str, Any] = {
+        self.request: dict[str, JSONValue] = {
             "resource": {"type": "function", "ids": [world.fixture["function_id"]]},
             "q": self.marker,
             "start_time": (datetime.now(UTC) - timedelta(minutes=5)).isoformat(),
@@ -73,7 +103,7 @@ class LogContract:
             datetime.now(UTC) + timedelta(minutes=5)
         ).isoformat()
 
-    def search(self) -> list[Any]:
+    def search(self) -> list[Mapping[str, JSONValue]]:
         project = self.world.fixture["project_id"]
         page = poll(
             lambda: self.client.logs.search(project, {**self.request, "limit": 100}),
@@ -82,7 +112,7 @@ class LogContract:
         )
         assert len(page.data) == LOG_EVENT_COUNT
         expected_ids = {event_id(event) for event in page.data}
-        events: list[Any] = []
+        events: list[Mapping[str, JSONValue]] = []
         request = {**self.request, "limit": 1}
         for _ in range(LOG_EVENT_COUNT):
             page = self.client.logs.search(project, request)
@@ -97,7 +127,7 @@ class LogContract:
         assert {event_id(event) for event in events} == expected_ids
         return events
 
-    def activity(self) -> Any:
+    def activity(self) -> LogActivityResponse:
         return poll(
             lambda: self.client.logs.activity(
                 self.world.fixture["project_id"], {**self.request, "bucket_count": 2}
@@ -106,37 +136,38 @@ class LogContract:
             120,
         )
 
-    def verify_events(self, events: Any) -> None:
+    def verify_events(self, events: list[Mapping[str, JSONValue]]) -> None:
         assert len(events) == LOG_EVENT_COUNT
-        assert len({event["id"] for event in events}) == LOG_EVENT_COUNT
-        assert sorted(event["body"]["ordinal"] for event in events) == [0, 1, 2]
+        assert len({event_id(event) for event in events}) == LOG_EVENT_COUNT
+        assert sorted(event_ordinal(event) for event in events) == [0, 1, 2]
         timestamps: list[datetime] = []
         for event in events:
             assert event["id"]
-            assert event["body"] == {
+            body = mapping_field(event, "body")
+            assert body == {
                 "marker": self.marker,
-                "ordinal": event["body"]["ordinal"],
+                "ordinal": event_ordinal(event),
             }
-            assert event["resource"]["type"] == "function"
-            assert event["resource"]["id"] == self.world.fixture["function_id"]
+            resource = mapping_field(event, "resource")
+            assert resource["type"] == "function"
+            assert resource["id"] == self.world.fixture["function_id"]
             assert event["level"] == "info"
-            timestamps.append(datetime.fromisoformat(event["timestamp"]))
+            timestamp = event["timestamp"]
+            assert isinstance(timestamp, str)
+            timestamps.append(datetime.fromisoformat(timestamp))
         assert timestamps == sorted(timestamps, reverse=True)
 
-    def verify_activity(self, response: Any) -> None:
+    def verify_activity(self, response: LogActivityResponse) -> None:
         assert response.total == 1
         assert len(response.data) == ACTIVITY_BUCKET_COUNT
-        assert sum(bucket["total"] for bucket in response.data) == 1
+        assert sum(bucket_total(bucket) for bucket in response.data) == 1
         assert (
             sum(
-                bucket["counts"]["resource_ids"].get(
-                    self.world.fixture["function_id"], 0
-                )
+                bucket_count(bucket, "resource_ids", self.world.fixture["function_id"])
                 for bucket in response.data
             )
             == 1
         )
         assert (
-            sum(bucket["counts"]["levels"].get("info", 0) for bucket in response.data)
-            == 1
+            sum(bucket_count(bucket, "levels", "info") for bucket in response.data) == 1
         )