@pyscript/core 0.7.11 → 0.7.12

package/src/stdlib/pyscript/websocket.py

@@ -1,88 +1,295 @@
+"""
+This module provides a Pythonic wrapper around the browser's
+[WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket),
+enabling two-way communication with WebSocket servers.
+
+Use this for real-time applications:
+
+- Pythonic interface to browser WebSockets.
+- Automatic handling of async event handlers.
+- Support for receiving text (`str`) and binary (`memoryview`) data.
+- Support for sending text (`str`) and binary (`bytes` and `bytearray`) data.
+- Compatible with Pyodide and MicroPython.
+- Works in webworker contexts.
+- Naming deliberately follows the JavaScript WebSocket API closely for
+  familiarity.
+
+See the Python docs for
+[an explanation of memoryview](https://docs.python.org/3/library/stdtypes.html#memoryview).
+
+
+```python
+from pyscript import WebSocket
+
+
+def on_open(event):
+    print("Connected!")
+    ws.send("Hello server")
+
+def on_message(event):
+    print(f"Received: {event.data}")
+
+def on_close(event):
+    print("Connection closed")
+
+ws = WebSocket(url="ws://localhost:8080/")
+ws.onopen = on_open
+ws.onmessage = on_message
+ws.onclose = on_close
+```
+"""
+
 import js
 from pyscript.ffi import create_proxy
 from pyscript.util import as_bytearray, is_awaitable
 
-code = "code"
-protocols = "protocols"
-reason = "reason"
-methods = ["onclose", "onerror", "onmessage", "onopen"]
 
+def _attach_event_handler(websocket, handler_name, handler_function):
+    """
+    Given a `websocket`, and `handler_name`, attach the `handler_function`
+    to the `WebSocket` instance, handling both synchronous and asynchronous
+    handler functions.
 
-def add_listener(socket, onevent, listener):
-    p = create_proxy(listener)
+    Creates a JavaScript proxy for the handler and wraps async handlers
+    appropriately. Handles the `WebSocketEvent` wrapping for all handlers.
+    """
+    if is_awaitable(handler_function):
 
-    if is_awaitable(listener):
+        async def async_wrapper(event):
+            await handler_function(WebSocketEvent(event))
 
-        async def wrapper(e):
-            await p(EventMessage(e))
+        wrapped_handler = create_proxy(async_wrapper)
+    else:
+        wrapped_handler = create_proxy(
+            lambda event: handler_function(WebSocketEvent(event))
+        )
+    # Note: Direct assignment (websocket[handler_name]) fails in Pyodide.
+    setattr(websocket, handler_name, wrapped_handler)
 
-        m = wrapper
 
-    else:
-        m = lambda e: p(EventMessage(e))
+class WebSocketEvent:
+    """
+    A read-only wrapper for
+    [WebSocket event objects](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent).
 
-    # Pyodide fails at setting socket[onevent] directly
-    setattr(socket, onevent, m)
+    This class wraps browser WebSocket events and provides convenient access
+    to event properties. It handles the conversion of binary data from
+    JavaScript typed arrays to Python bytes-like objects.
 
+    The most commonly used property is `event.data`, which contains the
+    message data for "message" events.
+
+    ```python
+    def on_message(event):  # The event is a WebSocketEvent instance.
+        # For text messages.
+        if isinstance(event.data, str):
+            print(f"Text: {event.data}")
+        else:
+            # For binary messages.
+            print(f"Binary: {len(event.data)} bytes")
+    ```
+    """
 
-class EventMessage:
     def __init__(self, event):
+        """
+        Create a WebSocketEvent wrapper from an underlying JavaScript
+        `event`.
+        """
         self._event = event
 
     def __getattr__(self, attr):
-        value = getattr(self._event, attr)
+        """
+        Get an attribute `attr` from the underlying event object.
 
+        Handles special conversion of binary data from JavaScript typed
+        arrays to Python `memoryview` objects.
+        """
+        value = getattr(self._event, attr)
         if attr == "data" and not isinstance(value, str):
             if hasattr(value, "to_py"):
+                # Pyodide - convert JavaScript typed array to Python.
                 return value.to_py()
-            # shims in MicroPython
-            return memoryview(as_bytearray(value))
-
+            else:
+                # MicroPython - manually convert JS ArrayBuffer.
+                return memoryview(as_bytearray(value))
         return value
 
 
 class WebSocket:
+    """
+    This class provides a Python-friendly interface to WebSocket connections,
+    handling communication with WebSocket servers. It supports both text and
+    binary data transmission.
+
+    Access the underlying WebSocket methods and properties directly if needed.
+    However, the wrapper provides a more Pythonic API. If you need to work
+    with the raw JavaScript WebSocket instance, you can access it via the
+    `_js_websocket` attribute.
+
+    Using textual (`str`) data:
+
+    ```python
+    from pyscript import WebSocket
+
+
+    # Create WebSocket with handlers as arguments.
+    def handle_message(event):
+        print(f"Got: {event.data}")
+
+    ws = WebSocket(
+        url="ws://echo.websocket.org/",
+        onmessage=handle_message
+    )
+
+    # Or assign handlers after creation.
+    def handle_open(event):
+        ws.send("Hello!")
+
+    ws.onopen = handle_open
+    ```
+
+    Using binary (`memoryview`) data:
+
+    ```python
+    def handle_message(event):
+        if isinstance(event.data, str):
+            print(f"Text: {event.data}")
+        else:
+            # Binary data as memoryview.
+            print(f"Binary: {len(event.data)} bytes")
+
+    ws = WebSocket(url="ws://example.com/", onmessage=handle_message)
+
+    # Send binary data.
+    data = bytearray([0x01, 0x02, 0x03])
+    ws.send(data)
+    ```
+
+    Read more about Python's
+    [`memoryview` here](https://docs.python.org/3/library/stdtypes.html#memoryview).
+    """
+
+    # WebSocket ready state constants.
     CONNECTING = 0
     OPEN = 1
     CLOSING = 2
     CLOSED = 3
 
-    def __init__(self, **kw):
-        url = kw["url"]
-        if protocols in kw:
-            socket = js.WebSocket.new(url, kw[protocols])
-        else:
-            socket = js.WebSocket.new(url)
+    def __init__(self, url, protocols=None, **handlers):
+        """
+        Create a new WebSocket connection from the given `url` (`ws://` or
+        `wss://`). Optionally specify `protocols` (a string or a list of
+        protocol strings) and event handlers (`onopen`, `onmessage`, etc.) as
+        keyword arguments.
+
+        These arguments and naming conventions mirror those of the
+        [underlying JavaScript WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+        for familiarity.
 
-        socket.binaryType = "arraybuffer"
-        object.__setattr__(self, "_ws", socket)
+        If you need access to the underlying JavaScript WebSocket instance,
+        you can get it via the `_js_websocket` attribute.
 
-        for t in methods:
-            if t in kw:
-                add_listener(socket, t, kw[t])
+        ```python
+        # Basic connection.
+        ws = WebSocket(url="ws://localhost:8080/")
+
+        # With protocol.
+        ws = WebSocket(
+            url="wss://example.com/socket",
+            protocols="chat"
+        )
+
+        # With handlers.
+        ws = WebSocket(
+            url="ws://localhost:8080/",
+            onopen=lambda e: print("Connected"),
+            onmessage=lambda e: print(e.data)
+        )
+        ```
+        """
+        # Create underlying JavaScript WebSocket.
+        if protocols:
+            js_websocket = js.WebSocket.new(url, protocols)
+        else:
+            js_websocket = js.WebSocket.new(url)
+        # Set binary type to arraybuffer for easier Python handling.
+        js_websocket.binaryType = "arraybuffer"
+        # Store the underlying WebSocket.
+        # Use object.__setattr__ to bypass our custom __setattr__.
+        object.__setattr__(self, "_js_websocket", js_websocket)
+        # Attach any event handlers passed as keyword arguments.
+        for handler_name, handler in handlers.items():
+            setattr(self, handler_name, handler)
 
     def __getattr__(self, attr):
-        return getattr(self._ws, attr)
+        """
+        Get an attribute `attr` from the underlying WebSocket.
+
+        This allows transparent access to WebSocket properties like
+        `readyState`, `url`, `bufferedAmount`, etc.
+        """
+        return getattr(self._js_websocket, attr)
 
     def __setattr__(self, attr, value):
-        if attr in methods:
-            add_listener(self._ws, attr, value)
-        else:
-            setattr(self._ws, attr, value)
+        """
+        Set an attribute `attr` on the WebSocket to the given `value`.
 
-    def close(self, **kw):
-        if code in kw and reason in kw:
-            self._ws.close(kw[code], kw[reason])
-        elif code in kw:
-            self._ws.close(kw[code])
+        Event handler attributes (`onopen`, `onmessage`, etc.) are specially
+        handled to create proper proxies. Other attributes are set on the
+        underlying WebSocket directly.
+        """
+        if attr in ["onclose", "onerror", "onmessage", "onopen"]:
+            _attach_event_handler(self._js_websocket, attr, value)
         else:
-            self._ws.close()
+            setattr(self._js_websocket, attr, value)
 
     def send(self, data):
+        """
+        Send `data` through the WebSocket.
+
+        Accepts both text (`str`) and binary data (`bytes`, `bytearray`, etc.).
+        Binary data is automatically converted to a JavaScript `Uint8Array`.
+
+        ```python
+        # Send text.
+        ws.send("Hello server!")
+
+        # Send binary.
+        ws.send(bytes([1, 2, 3, 4]))
+        ws.send(bytearray([5, 6, 7, 8]))
+        ```
+
+        !!! warning
+
+            The WebSocket **must be in the OPEN state to send data**.
+        """
         if isinstance(data, str):
-            self._ws.send(data)
+            self._js_websocket.send(data)
         else:
             buffer = js.Uint8Array.new(len(data))
-            for pos, b in enumerate(data):
-                buffer[pos] = b
-            self._ws.send(buffer)
+            for index, byte_value in enumerate(data):
+                buffer[index] = byte_value
+            self._js_websocket.send(buffer)
+
+    def close(self, code=None, reason=None):
+        """
+        Close the WebSocket connection. Optionally specify a `code` (`int`)
+        and a `reason` (`str`) for closing the connection.
+
+        ```python
+        # Normal close.
+        ws.close()
+
+        # Close with code and reason.
+        ws.close(code=1000, reason="Task completed")
+        ```
+
+        Usage and values for `code` and `reasons`
+        [are explained here](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close).
+        """
+        if code and reason:
+            self._js_websocket.close(code, reason)
+        elif code:
+            self._js_websocket.close(code)
+        else:
+            self._js_websocket.close()

package/src/stdlib/pyscript/workers.py

@@ -1,45 +1,194 @@
-import js as _js
-from polyscript import workers as _workers
+"""
+This module provides access to named
+[web workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)
+defined in `<script>` tags, and utilities for dynamically creating workers
+from Python code.
 
-_get = _js.Reflect.get
+Named workers are Python web workers defined in HTML with a `name` attribute
+that can be referenced from the main thread or other workers. This module
+provides the `workers` object for accessing named workers and the
+`create_named_worker()` function for dynamically creating them.
 
+Accessing named workers:
 
-def _set(script, name, value=""):
-    script.setAttribute(name, value)
+```html
+<!-- Define a named worker -->
+<script type="py" worker name="calculator">
+def add(a, b):
+    return a + b
 
+__export__ = ["add"]
+</script>
+
+<!-- Access from main thread -->
+<script type="mpy">
+from pyscript import workers
+
+
+calc = await workers["calculator"]
+result = await calc.add(5, 3)
+print(result)  # 8
+</script>
+```
+
+Dynamically creating named workers:
+
+```python
+from pyscript import create_named_worker
+
+
+# Create a worker from a Python file.
+worker = await create_named_worker(
+    src="./background_tasks.py",
+    name="task-processor"
+)
+
+# Use the worker's exported functions.
+result = await worker.process_data([1, 2, 3, 4, 5])
+print(result)
+```
+
+Key features:
+- Access (`await`) named workers via dictionary-like syntax.
+- Dynamically create workers from Python.
+- Cross-interpreter support (Pyodide and MicroPython).
+
+Worker access is asynchronous - you must `await workers[name]` to get
+a reference to the worker. This is because workers may not be ready
+immediately at startup.
+"""
+
+import js
+import json
+from polyscript import workers as _polyscript_workers
+
+
+class _ReadOnlyWorkersProxy:
+    """
+    A read-only proxy for accessing named web workers. Use
+    `create_named_worker()` to create new workers found in this proxy.
+
+    This provides dictionary-like access to named workers defined in
+    the page. It handles differences between Pyodide and MicroPython
+    implementations transparently.
+
+    (See: https://github.com/pyscript/pyscript/issues/2106 for context.)
+
+    The proxy is read-only to prevent accidental modification of the
+    underlying workers registry. Both item access and attribute access are
+    supported for convenience (especially since HTML attribute names may
+    not be valid Python identifiers).
+
+    ```python
+    from pyscript import workers
+
+    # Access a named worker.
+    my_worker = await workers["worker-name"]
+    result = await my_worker.some_function()
+
+    # Alternatively, if the name works, access via attribute notation.
+    my_worker = await workers.worker_name
+    result = await my_worker.some_function()
+    ```
+
+    **This is a proxy object, not a dict**. You cannot iterate over it or
+    get a list of worker names. This is intentional because worker
+    startup timing is non-deterministic.
+    """
 
-# this solves an inconsistency between Pyodide and MicroPython
-# @see https://github.com/pyscript/pyscript/issues/2106
-class _ReadOnlyProxy:
     def __getitem__(self, name):
-        return _get(_workers, name)
+        """
+        Get a named worker by `name`. It returns a promise that resolves to
+        the worker reference when ready.
+
+        This is useful if the underlying worker name is not a valid Python
+        identifier.
+
+        ```python
+        worker = await workers["my-worker"]
+        ```
+        """
+        return js.Reflect.get(_polyscript_workers, name)
 
     def __getattr__(self, name):
-        return _get(_workers, name)
+        """
+        Get a named worker as an attribute. It returns a promise that resolves
+        to the worker reference when ready.
 
+        This allows accessing workers via dot notation as an alternative
+        to bracket notation.
 
-workers = _ReadOnlyProxy()
+        ```python
+        worker = await workers.my_worker
+        ```
+        """
+        return js.Reflect.get(_polyscript_workers, name)
 
 
-async def create_named_worker(src="", name="", config=None, type="py"):
-    from json import dumps
+# Global workers proxy for accessing named workers.
+workers = _ReadOnlyWorkersProxy()
+"""Global proxy for accessing named web workers."""
 
-    if not src:
-        msg = "Named workers require src"
-        raise ValueError(msg)
 
-    if not name:
-        msg = "Named workers require a name"
-        raise ValueError(msg)
+async def create_named_worker(src, name, config=None, type="py"):
+    """
+    Dynamically create a web worker with a `src` Python file, a unique
+    `name` and optional `config` (dict or JSON string) and `type` (`py`
+    for Pyodide or `mpy` for MicroPython, the default is `py`).
 
-    s = _js.document.createElement("script")
-    s.type = type
-    s.src = src
-    _set(s, "worker")
-    _set(s, "name", name)
+    This function creates a new web worker by injecting a `<script>` tag into
+    the document. The worker will be accessible via the `workers` proxy once
+    it's ready.
 
-    if config:
-        _set(s, "config", (isinstance(config, str) and config) or dumps(config))
+    It returns a promise that resolves to the worker reference when ready.
+
+    ```python
+    from pyscript import create_named_worker
 
-    _js.document.body.append(s)
+
+    # Create a Pyodide worker.
+    worker = await create_named_worker(
+        src="./my_worker.py",
+        name="background-worker"
+    )
+
+    # Use the worker.
+    result = await worker.process_data()
+
+    # Create with standard PyScript configuration.
+    worker = await create_named_worker(
+        src="./processor.py",
+        name="data-processor",
+        config={"packages": ["numpy", "pandas"]}
+    )
+
+    # Use MicroPython instead.
+    worker = await create_named_worker(
+        src="./lightweight_worker.py",
+        name="micro-worker",
+        type="mpy"
+    )
+    ```
+
+    !!! info
+
+        **The worker script should define** `__export__` to specify which
+        functions or objects are accessible from the main thread.
+    """
+    # Create script element for the worker.
+    script = js.document.createElement("script")
+    script.type = type
+    script.src = src
+    # Mark as a worker with a name.
+    script.setAttribute("worker", "")
+    script.setAttribute("name", name)
+    # Add configuration if provided.
+    if config:
+        if isinstance(config, str):
+            config_str = config
+        else:
+            config_str = json.dumps(config)
+        script.setAttribute("config", config_str)
+    # Inject the script into the document and await the result.
+    js.document.body.append(script)
     return await workers[name]