@pyscript/core 0.7.11 → 0.7.13

package/src/stdlib/pyscript/media.py

@@ -1,87 +1,247 @@
+"""
+This module provides classes and functions for interacting with
+[media devices and streams](https://developer.mozilla.org/en-US/docs/Web/API/Media_Capture_and_Streams_API)
+in the browser, enabling you to work with cameras, microphones,
+and other media input/output devices directly from Python.
+
+Use this module for:
+
+- Accessing webcams for video capture.
+- Recording audio from microphones.
+- Enumerating available media devices.
+- Applying constraints to media streams (resolution, frame rate, etc.).
+
+```python
+from pyscript import document
+from pyscript.media import Device, list_devices
+
+
+# Get a video stream from the default camera.
+stream = await Device.request_stream(video=True)
+
+# Display in a video element.
+video = document.getElementById("my-video")
+video.srcObject = stream
+
+# Or list all available devices.
+devices = await list_devices()
+for device in devices:
+    print(f"{device.kind}: {device.label}")
+```
+
+Using media devices requires user permission. Browsers will show a
+permission dialog when accessing devices for the first time.
+"""
+
 from pyscript import window
 from pyscript.ffi import to_js
 
 
 class Device:
-    """Device represents a media input or output device, such as a microphone,
-    camera, or headset.
+    """
+    Represents a media input or output device.
+
+    This class wraps a browser
+    [MediaDeviceInfo object](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo),
+    providing Pythonic access to device properties like `ID`, `label`, and
+    `kind` (audio/video, input/output).
+
+    Devices are typically obtained via the `list_devices()` function in this
+    module, rather than constructed directly.
+
+    ```python
+    from pyscript.media import list_devices
+
+
+    # Get all available devices.
+    devices = await list_devices()
+
+    # Find video input devices (cameras).
+    cameras = [d for d in devices if d.kind == "videoinput"]
+
+    # Get a stream from a specific camera.
+    if cameras:
+        stream = await cameras[0].get_stream()
+    ```
     """
 
     def __init__(self, device):
-        self._dom_element = device
+        """
+        Create a Device wrapper around a MediaDeviceInfo `device`.
+        """
+        self._device_info = device
 
     @property
     def id(self):
-        return self._dom_element.deviceId
+        """
+        Unique identifier for this device.
+
+        This `ID` persists across sessions but is reset when the user clears
+        cookies. It's unique to the origin of the calling application.
+        """
+        return self._device_info.deviceId
 
     @property
     def group(self):
-        return self._dom_element.groupId
+        """
+        Group identifier for related devices.
+
+        Devices belonging to the same physical device (e.g., a monitor with
+        both a camera and microphone) share the same `group ID`.
+        """
+        return self._device_info.groupId
 
     @property
     def kind(self):
-        return self._dom_element.kind
+        """
+        Device type: `"videoinput"`, `"audioinput"`, or `"audiooutput"`.
+        """
+        return self._device_info.kind
 
     @property
     def label(self):
-        return self._dom_element.label
+        """
+        Human-readable description of the device.
+
+        Example: `"External USB Webcam"` or `"Built-in Microphone"`.
+        """
+        return self._device_info.label
 
     def __getitem__(self, key):
+        """
+        Support bracket notation for JavaScript interop.
+
+        Allows accessing properties via `device["id"]` syntax. Necessary
+        when Device instances are proxied to JavaScript.
+        """
         return getattr(self, key)
 
     @classmethod
-    async def load(cls, audio=False, video=True):
+    async def request_stream(cls, audio=False, video=True):
         """
-        Load the device stream.
+        Request a media stream with the specified constraints.
+
+        This is a class method that requests access to media devices matching
+        the given `audio` and `video` constraints. The browser will prompt the
+        user for permission if needed and return a `MediaStream` object that
+        can be assigned to video/audio elements.
+
+        Simple boolean constraints for `audio` and `video` can be used to
+        request default devices. More complex constraints can be specified as
+        dictionaries conforming to
+        [the MediaTrackConstraints interface](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints).
+
+        ```python
+        from pyscript import document
+        from pyscript.media import Device
+
+
+        # Get default video stream.
+        stream = await Device.request_stream()
+
+        # Get stream with specific constraints.
+        stream = await Device.request_stream(
+            video={"width": 1920, "height": 1080}
+        )
+
+        # Get audio and video.
+        stream = await Device.request_stream(audio=True, video=True)
+
+        # Use the stream.
+        video_el = document.getElementById("camera")
+        video_el.srcObject = stream
+        ```
+
+        This method will trigger a browser permission dialog on first use.
         """
         options = {}
-        options["audio"] = audio
+        if isinstance(audio, bool):
+            options["audio"] = audio
+        elif isinstance(audio, dict):
+            # audio is a dict of constraints (sampleRate, echoCancellation etc...).
+            options["audio"] = audio
         if isinstance(video, bool):
             options["video"] = video
-        else:
-            options["video"] = {}
-            for k in video:
-                options["video"][k] = video[k]
+        elif isinstance(video, dict):
+            # video is a dict of constraints (width, height etc...).
+            options["video"] = video
         return await window.navigator.mediaDevices.getUserMedia(to_js(options))
 
+    @classmethod
+    async def load(cls, audio=False, video=True):
+        """
+        !!! warning
+            **Deprecated: Use `request_stream()` instead.**
+
+            This method is retained for backwards compatibility but will be
+            removed in a future release. Please use `request_stream()` instead.
+        """
+        return await cls.request_stream(audio=audio, video=video)
+
     async def get_stream(self):
-        key = self.kind.replace("input", "").replace("output", "")
-        options = {key: {"deviceId": {"exact": self.id}}}
-        return await self.load(**options)
+        """
+        Get a media stream from this specific device.
+
+        ```python
+        from pyscript.media import list_devices
+
+
+        # List all devices.
+        devices = await list_devices()
+
+        # Find a specific camera.
+        my_camera = None
+        for device in devices:
+            if device.kind == "videoinput" and "USB" in device.label:
+                my_camera = device
+                break
+
+        # Get a stream from that specific camera.
+        if my_camera:
+            stream = await my_camera.get_stream()
+        ```
+
+        This will trigger a permission dialog if the user hasn't already
+        granted permission for this device type.
+        """
+        # Extract media type from device kind (e.g., "videoinput" -> "video").
+        media_type = self.kind.replace("input", "").replace("output", "")
+        # Request stream with exact device ID constraint.
+        options = {media_type: {"deviceId": {"exact": self.id}}}
+        return await self.request_stream(**options)
 
 
-async def list_devices() -> list[dict]:
+async def list_devices():
     """
-    Return the list of the currently available media input and output devices,
-    such as microphones, cameras, headsets, and so forth.
-
-    Output:
-
-        list(dict) - list of dictionaries representing the available media devices.
-            Each dictionary has the following keys:
-            * deviceId: a string that is an identifier for the represented device
-                that is persisted across sessions. It is un-guessable by other
-                applications and unique to the origin of the calling application.
-                It is reset when the user clears cookies (for Private Browsing, a
-                different identifier is used that is not persisted across sessions).
-
-            * groupId: a string that is a group identifier. Two devices have the same
-                group identifier if they belong to the same physical device — for
-                example a monitor with both a built-in camera and a microphone.
-
-            * kind: an enumerated value that is either "videoinput", "audioinput"
-                or "audiooutput".
-
-            * label: a string describing this device (for example "External USB
-                Webcam").
-
-    Note: the returned list will omit any devices that are blocked by the document
-    Permission Policy: microphone, camera, speaker-selection (for output devices),
-    and so on. Access to particular non-default devices is also gated by the
-    Permissions API, and the list will omit devices for which the user has not
-    granted explicit permission.
+    Returns a list of all media devices currently available to the browser,
+    such as microphones, cameras, and speakers.
+
+    ```python
+    from pyscript.media import list_devices
+
+
+    # Get all devices.
+    devices = await list_devices()
+
+    # Print device information.
+    for device in devices:
+        print(f"{device.kind}: {device.label} (ID: {device.id})")
+
+    # Filter for specific device types.
+    cameras = [d for d in devices if d.kind == "videoinput"]
+    microphones = [d for d in devices if d.kind == "audioinput"]
+    speakers = [d for d in devices if d.kind == "audiooutput"]
+    ```
+
+    The returned list will omit devices that are blocked by the document
+    [Permission Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Permissions_Policy)
+    (microphone, camera, speaker-selection) or for
+    which the user has not granted explicit permission.
+
+    For security and privacy, device labels may be empty strings until
+    permission is granted. See
+    [this document](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices)
+    for more information about this web standard.
     """
-    # https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices
-    return [
-        Device(obj) for obj in await window.navigator.mediaDevices.enumerateDevices()
-    ]
+    device_infos = await window.navigator.mediaDevices.enumerateDevices()
+    return [Device(device_info) for device_info in device_infos]

package/src/stdlib/pyscript/storage.py

@@ -1,11 +1,69 @@
-from polyscript import storage as _storage
+"""
+This module wraps the browser's
+[IndexedDB persistent storage](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
+to provide a familiar Python dictionary API. Data is automatically
+serialized and persisted, surviving page reloads and browser restarts.
+
+Storage is persistent per origin (domain), isolated between different sites
+for security. Browsers typically allow each origin to store up to 10-60% of
+total disk space, depending on browser and configuration.
+
+What this module provides:
+
+- A `dict`-like API (get, set, delete, iterate).
+- Automatic serialization of common Python types.
+- Background persistence with optional explicit `sync()`.
+- Support for custom `Storage` subclasses.
+
+```python
+from pyscript import storage
+
+
+# Create or open a named storage.
+my_data = await storage("user-preferences")
+
+# Use like a regular dictionary.
+my_data["theme"] = "dark"
+my_data["font_size"] = 14
+my_data["settings"] = {"notifications": True, "sound": False}
+
+# Changes are queued automatically.
+# To ensure immediate write, sync explicitly.
+await my_data.sync()
+
+# Read values (survives page reload).
+theme = my_data.get("theme", "light")
+```
+
+Common types are automatically serialized: `bool`, `int`, `float`, `str`, `None`,
+`list`, `dict`, `tuple`. Binary data (`bytearray`, `memoryview`) can be stored as
+single values but not nested in structures.
+
+Tuples are deserialized as lists due to IndexedDB limitations.
+
+!!! info
+    Browsers typically allow 10-60% of total disk space per origin. Chrome
+    and Edge allow up to 60%, Firefox up to 10 GiB (or 10% of disk, whichever
+    is smaller). Safari varies by app type. These limits are unlikely to be
+    reached in typical usage.
+"""
+
+from polyscript import storage as _polyscript_storage
 from pyscript.flatted import parse as _parse
 from pyscript.flatted import stringify as _stringify
 from pyscript.ffi import is_none
 
 
-# convert a Python value into an IndexedDB compatible entry
-def _to_idb(value):
+def _convert_to_idb(value):
+    """
+    Convert a Python `value` to an IndexedDB-compatible format.
+
+    Values are serialized using Flatted (for circular reference support)
+    with type information to enable proper deserialization. It returns a
+    JSON string representing the serialized value.
+
+    Will raise a TypeError if the value type is not supported.
+    """
     if is_none(value):
         return _stringify(["null", 0])
     if isinstance(value, (bool, float, int, str, list, dict, tuple)):
@@ -14,50 +72,179 @@ def _to_idb(value):
         return _stringify(["bytearray", list(value)])
     if isinstance(value, memoryview):
         return _stringify(["memoryview", list(value)])
-    msg = f"Unexpected value: {value}"
-    raise TypeError(msg)
+    raise TypeError(f"Cannot serialize type {type(value).__name__} for storage.")
 
 
-# convert an IndexedDB compatible entry into a Python value
-def _from_idb(value):
-    (
-        kind,
-        result,
-    ) = _parse(value)
+def _convert_from_idb(value):
+    """
+    Convert an IndexedDB `value` back to its Python representation.
+
+    Uses type information stored during serialization to reconstruct the
+    original Python type.
+    """
+    kind, data = _parse(value)
+
     if kind == "null":
         return None
     if kind == "generic":
-        return result
+        return data
     if kind == "bytearray":
-        return bytearray(result)
+        return bytearray(data)
     if kind == "memoryview":
-        return memoryview(bytearray(result))
+        return memoryview(bytearray(data))
+    # Fallback for all other types.
     return value
 
 
 class Storage(dict):
+    """
+    A persistent dictionary backed by the browser's IndexedDB.
+
+    This class provides a dict-like interface with automatic persistence.
+    Changes are queued for background writing, with optional explicit
+    synchronization via `sync()`.
+
+    Inherits from `dict`, so all standard dictionary methods work as expected.
+
+    ```python
+    from pyscript import storage
+
+
+    # Open a storage.
+    prefs = await storage("preferences")
+
+    # Use as a dictionary.
+    prefs["color"] = "blue"
+    prefs["count"] = 42
+
+    # Iterate like a dict.
+    for key, value in prefs.items():
+        print(f"{key}: {value}")
+
+    # Ensure writes complete immediately.
+    await prefs.sync()
+    ```
+
+    Sometimes you may need to subclass `Storage` to add custom behavior:
+
+    ```python
+    from pyscript import storage, Storage, window
+
+
+    class LoggingStorage(Storage):
+        def __setitem__(self, key, value):
+            window.console.log(f"Setting {key} = {value}")
+            super().__setitem__(key, value)
+
+    my_store = await storage("app-data", storage_class=LoggingStorage)
+    my_store["test"] = 123  # Logs to console.
+    ```
+    """
+
     def __init__(self, store):
-        super().__init__({k: _from_idb(v) for k, v in store.entries()})
-        self.__store__ = store
+        """
+        Create a Storage instance wrapping an IndexedDB `store` (a JS
+        proxy).
+        """
+        super().__init__(
+            {key: _convert_from_idb(value) for key, value in store.entries()}
+        )
+        self._store = store
+
+    def __delitem__(self, key):
+        """
+        Delete an item from storage via its `key`.
+
+        The deletion is queued for persistence. Use `sync()` to ensure
+        immediate completion.
+        """
+        self._store.delete(key)
+        super().__delitem__(key)
 
-    def __delitem__(self, attr):
-        self.__store__.delete(attr)
-        super().__delitem__(attr)
+    def __setitem__(self, key, value):
+        """
+        Set a `key` to a `value` in storage.
 
-    def __setitem__(self, attr, value):
-        self.__store__.set(attr, _to_idb(value))
-        super().__setitem__(attr, value)
+        The change is queued for persistence. Use `sync()` to ensure
+        immediate completion. The `value` must be a supported type for
+        serialization.
+        """
+        self._store.set(key, _convert_to_idb(value))
+        super().__setitem__(key, value)
 
     def clear(self):
-        self.__store__.clear()
+        """
+        Remove all items from storage.
+
+        The `clear()` operation is queued for persistence. Use `sync()` to ensure
+        immediate completion.
+        """
+        self._store.clear()
         super().clear()
 
     async def sync(self):
-        await self.__store__.sync()
+        """
+        Force immediate synchronization to IndexedDB.
+
+        By default, storage operations are queued and written asynchronously.
+        Call `sync()` when you need to guarantee changes are persisted immediately,
+        such as before critical operations or page unload.
+
+        ```python
+        store = await storage("important-data")
+        store["critical_value"] = data
+
+        # Ensure it's written before proceeding.
+        await store.sync()
+        ```
+
+        This is a blocking operation that waits for IndexedDB to complete
+        the write.
+        """
+        await self._store.sync()
 
 
 async def storage(name="", storage_class=Storage):
+    """
+    Open or create persistent storage with a unique `name` and optional
+    `storage_class` (used to extend the default `Storage` based behavior).
+
+    Each storage is isolated by name within the current origin (domain).
+    If the storage doesn't exist, it will be created. If it does exist,
+    its current contents will be loaded.
+
+    This function returns a `Storage` instance (or custom subclass instance)
+    acting as a persistent dictionary. A `ValueError` is raised if `name` is
+    empty or not provided.
+
+    ```python
+    from pyscript import storage
+
+
+    # Basic usage.
+    user_data = await storage("user-profile")
+    user_data["name"] = "Alice"
+    user_data["age"] = 30
+
+    # Multiple independent storages.
+    settings = await storage("app-settings")
+    cache = await storage("api-cache")
+
+    # With custom Storage class.
+    class ValidatingStorage(Storage):
+        def __setitem__(self, key, value):
+            if not isinstance(key, str):
+                raise TypeError("Keys must be strings")
+            super().__setitem__(key, value)
+
+    validated = await storage("validated-data", ValidatingStorage)
+    ```
+
+    Storage names are automatically prefixed with `"@pyscript/"` to
+    namespace them within IndexedDB.
+    """
     if not name:
-        msg = "The storage name must be defined"
-        raise ValueError(msg)
-    return storage_class(await _storage(f"@pyscript/{name}"))
+        raise ValueError("Storage name must be a non-empty string")
+
+    underlying_store = await _polyscript_storage(f"@pyscript/{name}")
+    return storage_class(underlying_store)

package/src/stdlib/pyscript/util.py

@@ -1,11 +1,24 @@
+"""
+This module contains general-purpose utility functions that don't fit into
+more specific modules. These utilities handle cross-platform compatibility
+between Pyodide and MicroPython, feature detection, and common type
+conversions:
+
+- `as_bytearray`: Convert JavaScript `ArrayBuffer` to Python `bytearray`.
+- `NotSupported`: Placeholder for unavailable features in specific contexts.
+- `is_awaitable`: Detect `async` functions across Python implementations.
+
+These utilities are primarily used internally by PyScript but are available
+for use in application code when needed.
+"""
+
 import js
-import sys
 import inspect
 
 
 def as_bytearray(buffer):
     """
-    Given a JavaScript ArrayBuffer, convert it to a Python bytearray in a
+    Given a JavaScript `ArrayBuffer`, convert it to a Python `bytearray` in a
     MicroPython friendly manner.
     """
     ui8a = js.Uint8Array.new(buffer)
@@ -42,17 +55,25 @@ class NotSupported:
 def is_awaitable(obj):
     """
     Returns a boolean indication if the passed in obj is an awaitable
-    function. (MicroPython treats awaitables as generator functions, and if
-    the object is a closure containing an async function we need to work
-    carefully.)
+    function. This is interpreter agnostic.
+
+    !!! info
+        MicroPython treats awaitables as generator functions, and if
+        the object is a closure containing an async function or a bound method
+        we need to work carefully.
     """
     from pyscript import config
 
-    if config["type"] == "mpy":  # Is MicroPython?
+    if config["type"] == "mpy":
         # MicroPython doesn't appear to have a way to determine if a closure is
         # an async function except via the repr. This is a bit hacky.
-        if "<closure <generator>" in repr(obj):
+        r = repr(obj)
+        if "<closure <generator>" in r:
+            return True
+        # Same applies to bound methods.
+        if "<bound_method" in r and "<generator>" in r:
             return True
+        # In MicroPython, generator functions are awaitable.
         return inspect.isgeneratorfunction(obj)
 
     return inspect.iscoroutinefunction(obj)