workers-runtime-sdk 1.2.0__tar.gz → 1.4.0__tar.gz

{workers_runtime_sdk-1.2.0 → workers_runtime_sdk-1.4.0}/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 <!-- version list -->
 
+## v1.4.0 (2026-06-17)
+
+### Features
+
+- Auto-convert Python objects that are passed to/from Queue
+  ([#123](https://github.com/cloudflare/workers-py/pull/123),
+  [`906a10a`](https://github.com/cloudflare/workers-py/commit/906a10a7392f9d823a1b6bba044300ece8763401))
+
+- Auto-convert Python objects that are passed to/from Queue Binding
+  ([#123](https://github.com/cloudflare/workers-py/pull/123),
+  [`906a10a`](https://github.com/cloudflare/workers-py/commit/906a10a7392f9d823a1b6bba044300ece8763401))
+
+
+## v1.3.0 (2026-06-15)
+
+### Features
+
+- **runtime-sdk**: Revise type conversion for Durable Object binding
+  ([#112](https://github.com/cloudflare/workers-py/pull/112),
+  [`b12650e`](https://github.com/cloudflare/workers-py/commit/b12650ef91bb71f4ebebd9827bad2d1f0946fd62))
+
+- **runtime-sdk**: Revise type conversion to support bindings more natively
+  ([#112](https://github.com/cloudflare/workers-py/pull/112),
+  [`b12650e`](https://github.com/cloudflare/workers-py/commit/b12650ef91bb71f4ebebd9827bad2d1f0946fd62))
+
+- **runtime-sdk**: Update js object conversion logic to support cloudflare bindings more natively.
+  ([#112](https://github.com/cloudflare/workers-py/pull/112),
+  [`b12650e`](https://github.com/cloudflare/workers-py/commit/b12650ef91bb71f4ebebd9827bad2d1f0946fd62))
+
+
 ## v1.2.0 (2026-06-12)
 
 ### Features

{workers_runtime_sdk-1.2.0 → workers_runtime_sdk-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workers-runtime-sdk
-Version: 1.2.0
+Version: 1.4.0
 Summary: Python SDK for Cloudflare Workers
 Project-URL: Homepage, https://github.com/cloudflare/workers-py
 Project-URL: Bug Tracker, https://github.com/cloudflare/workers-py/issues

{workers_runtime_sdk-1.2.0 → workers_runtime_sdk-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "workers-runtime-sdk"
-version = "1.2.0"
+version = "1.4.0"
 description = "Python SDK for Cloudflare Workers"
 readme = "README.md"
 requires-python = ">=3.12"

{workers_runtime_sdk-1.2.0 → workers_runtime_sdk-1.4.0}/src/workers/_workers.py

@@ -17,7 +17,6 @@ from collections.abc import (
 from contextlib import ExitStack, contextmanager
 from enum import StrEnum
 from http import HTTPMethod, HTTPStatus
-from types import LambdaType
 from typing import TYPE_CHECKING, Any, Never, Protocol, TypedDict, Unpack
 
 import _cloudflare_compat_flags
@@ -320,8 +319,13 @@ def _manage_pyproxies():
         destroy_proxies(proxies)
 
 
-def _is_js_instance(val, js_cls_name):
-    return hasattr(val, "constructor") and val.constructor.name == js_cls_name
+def _is_js_instance(val, js_cls_names: str | set[str]):
+    if not hasattr(val, "constructor"):
+        return False
+    name = val.constructor.name
+    if isinstance(js_cls_names, set):
+        return name in js_cls_names
+    return name == js_cls_names
 
 
 try:
@@ -916,6 +920,9 @@ class Request:
 
 
 def _python_from_rpc_default_converter(value, convert, cache):
+    if value is jsnull:
+        return None
+
     if not hasattr(value, "constructor"):
         # Assume that the object doesn't need conversion as it's not a JS object.
         return value
@@ -947,6 +954,41 @@ def _python_from_rpc_default_converter(value, convert, cache):
     return value
 
 
+class JsDict(dict):
+    """
+    Python dictionary that allows attribute access to keys.
+
+    This is used to convert JS objects to Python dictionaries while maintaining
+    the ability to access keys as attributes.
+    """
+
+    def __getattr__(self, name):
+        # The limitation of this approach is that if there is a key that conflicts with a built-in
+        # method or attribute of the dict class, it will not be accessible through attribute access.
+        # But that is a reasonable trade-off for the convenience of being able to access keys as
+        # attributes.
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(name) from None
+
+    def __setattr__(self, name, value):
+        self[name] = value
+
+
+def _replace_jsnull_with_none(obj):
+    """
+    Recursively converts JS objects to Python objects.
+    """
+    if obj is jsnull:
+        return None
+    if isinstance(obj, dict):
+        return JsDict({k: _replace_jsnull_with_none(v) for k, v in obj.items()})
+    if isinstance(obj, list):
+        return [_replace_jsnull_with_none(v) for v in obj]
+    return obj
+
+
 def python_from_rpc(obj: "JsProxy"):
     """
     Converts JS objects like Response, Request, Blob, etc. to equivalent Python objects defined in
@@ -956,6 +998,9 @@ def python_from_rpc(obj: "JsProxy"):
     it does not support serializing all JS object types.
     """
 
+    if obj is jsnull:
+        return None
+
     if not hasattr(obj, "constructor"):
         return obj
 
@@ -966,14 +1011,20 @@ def python_from_rpc(obj: "JsProxy"):
 
     result = obj.to_py(default_converter=_python_from_rpc_default_converter)
 
-    return result
+    return _replace_jsnull_with_none(result)
 
 
 def _raise_on_disabled_type(value):
+    if isinstance(value, _BindingWrapper):
+        return
+
+    if callable(value) and not isinstance(value, type):
+        return
+
     if _is_js_instance(value, "RegExp"):
         raise TypeError(f"{value.constructor.name} cannot be sent over RPC.")
 
-    if isinstance(value, (tuple, bytearray, LambdaType)):
+    if isinstance(value, (tuple, bytearray)):
         raise TypeError(f"{type(value)} cannot be sent over RPC.")
 
     if inspect.isawaitable(value):
@@ -991,7 +1042,10 @@ def _raise_on_disabled_type(value):
 
 def _python_to_rpc_default_converter(obj, convert, cache):
     if obj is None:
-        return obj
+        return jsnull
+
+    if isinstance(obj, _BindingWrapper):
+        return obj._binding
 
     if hasattr(obj, "js_object"):
         return obj.js_object
@@ -1003,11 +1057,26 @@ def _python_to_rpc_default_converter(obj, convert, cache):
     if isinstance(obj, Exception):
         return js.Error.new(str(obj))
 
+    if callable(obj) and not isinstance(obj, type):
+        # Wrap function with create_proxy so that
+        # it doesn't get garbage collected
+        return create_proxy(obj)
+
     _raise_on_disabled_type(obj)
 
     return obj
 
 
+def _replace_none_with_jsnull(value):
+    if value is None:
+        return jsnull
+    if isinstance(value, dict):
+        return {k: _replace_none_with_jsnull(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_replace_none_with_jsnull(v) for v in value]
+    return value
+
+
 def python_to_rpc(value) -> JsProxy:
     """
     Converts Python objects defined in this module (Response, Request, etc) and native Python types
@@ -1017,37 +1086,65 @@ def python_to_rpc(value) -> JsProxy:
     it does not support serializing all Python object types.
     """
 
+    if value is None:
+        return jsnull
+
+    if isinstance(value, _BindingWrapper):
+        return value._binding
+
+    value = _replace_none_with_jsnull(value)
+
     # `to_js` won't always call the default_converter, for example when a list of tuples is passed
     _raise_on_disabled_type(value)
 
     result = to_js(
         value,
         default_converter=_python_to_rpc_default_converter,
-        dict_converter=js.Map.new,
+        dict_converter=Object.fromEntries,
     )
 
     return result
 
 
-class _FetcherWrapper:
+class _BindingWrapper:
     def __init__(self, binding):
         self._binding = binding
 
+    def _convert_result(self, result):
+        converted = python_from_rpc(result)
+
+        # After python_from_rpc, some objects may still be JsProxy objects.
+        # For now, we wrap all of them with the _BindingWrapper (or a subclass of it)
+        # so that accessing attributes on them will be properly converted.
+
+        # TODO: This is a bit of a hack. We should revisit when there are more
+        # bindings to support with different return types.
+        if isinstance(converted, JsProxy):
+            return self.__class__(converted)
+        if isinstance(converted, list):
+            return [
+                self.__class__(item) if isinstance(item, JsProxy) else item
+                for item in converted
+            ]
+        return converted
+
     def _getattr_helper(self, name):
         attr = getattr(self._binding, name)
 
         if not callable(attr):
-            return attr
+            return self._convert_result(attr)
 
-        # Not using `@functools.wraps(attr)` here because `attr` is a JS proxy.
-        async def wrapper(*args, **kwargs):
+        def wrapper(*args, **kwargs):
             js_args = [python_to_rpc(arg) for arg in args]
             js_kwargs = {k: python_to_rpc(v) for k, v in kwargs.items()}
             result = attr(*js_args, **js_kwargs)
             if hasattr(result, "then") and callable(result.then):
-                return python_from_rpc(await result)
-            else:
-                return python_from_rpc(result)
+
+                async def await_and_convert():
+                    return self._convert_result(await result)
+
+                return await_and_convert()
+            return self._convert_result(result)
 
         return wrapper
 
@@ -1056,6 +1153,11 @@ class _FetcherWrapper:
         setattr(self, name, result)
         return result
 
+    def __getitem__(self, key):
+        return self._convert_result(getattr(self._binding, key))
+
+
+class _FetcherWrapper(_BindingWrapper):
     def fetch(self, *args, **kwargs):
         return fetch(*args, fetcher=self._binding.fetch, **kwargs)
 
@@ -1089,6 +1191,9 @@ class DurableObjectContext:
 
     def __getattr__(self, name: str):
         result = getattr(self._ctx, name)
+        if _is_js_instance(result, "DurableObjectStorage"):
+            # durable_object.ctx.storage
+            result = _BindingWrapper(result)
         setattr(self, name, result)
         return result
 
@@ -1159,6 +1264,13 @@ class _WorkflowBindingWrapper:
 
 
 class _EnvWrapper:
+    _BINDING_TYPES = {
+        "KvNamespace",
+        "R2Bucket",
+        "D1Database",
+        "WorkerQueue",
+    }
+
     def __init__(self, env: Any):
         self._env = env
 
@@ -1173,7 +1285,9 @@ class _EnvWrapper:
         if _is_js_instance(binding, "WorkflowImpl"):
             return _WorkflowBindingWrapper(binding)
 
-        # TODO: Implement APIs for bindings.
+        if _is_js_instance(binding, self._BINDING_TYPES):
+            return _BindingWrapper(binding)
+
         return binding
 
     def __getattr__(self, name):
@@ -1449,6 +1563,7 @@ class WorkerEntrypoint:
 
     def __init_subclass__(cls, **_kwargs: Any):
         _wrap_subclass(cls)
+        _wrap_queue_handler(cls)
 
 
 class WorkflowEntrypoint:
@@ -1466,3 +1581,19 @@ class WorkflowEntrypoint:
     def __init_subclass__(cls, **_kwargs: Any):
         _wrap_subclass(cls)
         _wrap_workflow_step(cls)
+
+
+def _wrap_queue_handler(cls):
+    queue_fn = getattr(cls, "queue", None)
+    if queue_fn is None:
+        return
+
+    @functools.wraps(queue_fn)
+    async def wrapped_queue(self, batch, *args, **kwargs):
+        wrapped_batch = _BindingWrapper(batch)
+        result = queue_fn(self, wrapped_batch, *args, **kwargs)
+        if inspect.iscoroutine(result):
+            result = await result
+        return result
+
+    cls.queue = wrapped_queue