feat: auto-convert Python objects that are passed to/from Queue Binding

[ryanking13]

Wrap Cloudflare Queue with our bindings wrapper so that users can see the native Python objects not JSProxies. By doing this, we can eliminate to_js and to_py when using Queue in Python workers.

While Queue is not our top priority, this is to remove to_js from our Python workers doc (https://developers.cloudflare.com/workers/languages/python/examples/#publish-to-a-queue)

[ask-bonk]

Python 3.12+ -- the str | set[str] syntax is fine.

Now let me think about whether there are any actual bugs or issues:

6. Potential issue with _convert_result and memoization: When batch.messages is accessed, _getattr_helper is called, and the result is memoized via setattr(self, "messages", result). Since messages is non-callable, _convert_result returns a list. On second access, the memoized list is returned. This is fine for the queue handler use case where messages are read once.

7. Looking at _convert_result list handling more carefully: If python_from_rpc returns a list where items are still JsProxy, each gets wrapped in self.__class__(item). But self.__class__ is _BindingWrapper, so each message becomes a _BindingWrapper. Accessing message.body will then go through _getattr_helper, which calls python_from_rpc on the body value. This should correctly convert primitive values. Good.

8. One potential concern: In _convert_result, the list handling wraps JsProxy items but passes through non-JsProxy items. But what about nested structures? If a list contains dicts that contain JsProxy values? Actually, python_from_rpc handles the .to_py() conversion first, so nested structures should already be converted. The list handling only catches cases where .to_py() leaves some items as JsProxy (which happens for complex objects like queue messages that have methods like ack()).

Let me verify there are no issues I'm missing. One thing I want to verify is that the _convert_result list handling won't cause issues for existing bindings like KV/R2/D1. Existing code only had the JsProxy -> self.__class__ branch. The new list branch is additive and only triggers when converted is a list. This should be safe for existing bindings.

Overall, this PR looks well-structured and follows established patterns. The code is clean, tests are comprehensive, and the approach of reusing _BindingWrapper for queues is consistent with how other bindings work.

There is one thing I notice: the test file has a pytestmark that skips all tests on Python < 3.13 with a FIXME comment about segfaults in dev environment. This is pre-existing context for this test approach. Not an issue introduced by this PR.

Let me check one more thing -- whether the consolidation of _BINDING_TYPES into a set and the corresponding _is_js_instance change is a purely behavioral-equivalent refactor:

Looking at the original code:

if _is_js_instance(binding, "KvNamespace"):
    return _BindingWrapper(binding)
if _is_js_instance(binding, "R2Bucket"):
    return _BindingWrapper(binding)
if _is_js_instance(binding, "D1Database"):
    return _BindingWrapper(binding)

New code:

_BINDING_TYPES = {"KvNamespace", "R2Bucket", "D1Database", "WorkerQueue"}
if _is_js_instance(binding, self._BINDING_TYPES):
    return _BindingWrapper(binding)

This is equivalent for the existing three types, plus adds WorkerQueue. Good.

After thorough review, I don't find any actionable issues -- no logic bugs, no security concerns, no backward compatibility problems, no missing error handling. The code follows established patterns, the refactoring is correct, and test coverage is solid.

LGTM

github run

[dom96]

A few suggestions, but overall nice!