@pyscript/core 0.7.11 → 0.7.13

package/src/stdlib/pyscript/ffi.py

@@ -1,48 +1,164 @@
+"""
+This module provides a unified
+[Foreign Function Interface (FFI)](https://en.wikipedia.org/wiki/Foreign_function_interface)
+layer for Python/JavaScript interactions, that works consistently across both
+Pyodide and MicroPython, and in a worker or main thread context, abstracting
+away the differences in their JavaScript interop APIs.
+
+The following utilities work on both the main thread and in worker contexts:
+
+- `create_proxy`: Create a persistent JavaScript proxy of a Python function.
+- `to_js`: Convert Python objects to JavaScript objects.
+- `is_none`: Check if a value is Python `None` or JavaScript `null`.
+- `assign`: Merge objects (like JavaScript's `Object.assign`).
+
+The following utilities are specific to worker contexts:
+
+- `direct`: Mark objects for direct JavaScript access.
+- `gather`: Collect multiple values from worker contexts.
+- `query`: Query objects in worker contexts.
+
+More details of the `direct`, `gather`, and `query` utilities
+[can be found here](https://github.com/WebReflection/reflected-ffi?tab=readme-ov-file#remote-extra-utilities).
+"""
+
 try:
+    # Attempt to import Pyodide's FFI utilities.
     import js
     from pyodide.ffi import create_proxy as _cp
     from pyodide.ffi import to_js as _py_tjs
     from pyodide.ffi import jsnull
 
     from_entries = js.Object.fromEntries
-    is_none = lambda value: value is None or value is jsnull
 
-    def _tjs(value, **kw):
-        if not hasattr(kw, "dict_converter"):
+    def _to_js_wrapper(value, **kw):
+        if "dict_converter" not in kw:
             kw["dict_converter"] = from_entries
         return _py_tjs(value, **kw)
 
 except:
+    # Fallback to jsffi for MicroPython.
     from jsffi import create_proxy as _cp
-    from jsffi import to_js as _tjs
+    from jsffi import to_js as _to_js_wrapper
     import js
 
     jsnull = js.Object.getPrototypeOf(js.Object.prototype)
-    is_none = lambda value: value is None or value is jsnull
 
-create_proxy = _cp
-to_js = _tjs
+
+def create_proxy(func):
+    """
+    Create a persistent JavaScript proxy of a Python function.
+
+    This proxy allows JavaScript code to call the Python function
+    seamlessly, maintaining the correct context and argument handling.
+
+    This is especially useful when passing Python functions as callbacks
+    to JavaScript APIs (without `create_proxy`, the function would be
+    garbage collected after the declaration of the callback).
+
+    ```python
+    from pyscript import ffi
+    from pyscript import document
+
+    my_button = document.getElementById("my-button")
+
+    def py_callback(x):
+        print(f"Callback called with {x}")
+
+    my_button.addEventListener("click", ffi.create_proxy(py_callback))
+    ```
+    """
+    return _cp(func)
+
+
+def to_js(value, **kw):
+    """
+    Convert Python objects to JavaScript objects.
+
+    This ensures a Python `dict` becomes a
+    [proper JavaScript object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
+    rather a JavaScript [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map),
+    which is more intuitive for most use cases.
+
+    Where required, the underlying `to_js` uses `Object.fromEntries` for
+    `dict` conversion.
+
+    ```python
+    from pyscript import ffi
+    import js
+
+
+    note = {
+        "body": "This is a notification",
+        "icon": "icon.png"
+    }
+
+    js.Notification.new("Hello!", ffi.to_js(note))
+    ```
+    """
+    return _to_js_wrapper(value, **kw)
+
+
+def is_none(value):
+    """
+    Check if a value is `None` or JavaScript `null`.
+
+    In Pyodide, JavaScript `null` is represented by the `jsnull` object,
+    so we check for both Python `None` and `jsnull`. This function ensures
+    consistent behavior across Pyodide and MicroPython for null-like
+    values.
+
+    ```python
+    from pyscript import ffi
+    import js
+
+
+    val1 = None
+    val2 = js.null
+    val3 = 42
+
+    print(ffi.is_none(val1))  # True
+    print(ffi.is_none(val2))  # True
+    print(ffi.is_none(val3))  # False
+    ```
+    """
+    return value is None or value is jsnull
+
 
 try:
+    # Worker context utilities from reflected-ffi.
+    # See https://github.com/WebReflection/reflected-ffi for more details.
     from polyscript import ffi as _ffi
 
+    _assign = _ffi.assign
+
     direct = _ffi.direct
     gather = _ffi.gather
     query = _ffi.query
 
-    def assign(source, *args):
-        for arg in args:
-            _ffi.assign(source, to_js(arg))
-        return source
-
 except:
+    # Fallback implementations for main thread context.
     import js
 
     _assign = js.Object.assign
 
     direct = lambda source: source
 
-    def assign(source, *args):
-        for arg in args:
-            _assign(source, to_js(arg))
-        return source
+
+def assign(source, *args):
+    """
+    Merge JavaScript objects (like
+    [Object.assign](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign)).
+
+    Takes a target object and merges properties from one or more source
+    objects into it, returning the modified target.
+
+    ```python
+    obj = js.Object.new()
+    ffi.assign(obj, {"a": 1}, {"b": 2})
+    # obj now has properties a=1 and b=2
+    ```
+    """
+    for arg in args:
+        _assign(source, to_js(arg))
+    return source

package/src/stdlib/pyscript/flatted.py

@@ -1,4 +1,36 @@
-# https://www.npmjs.com/package/flatted
+"""
+This module is a Python implementation of the
+[Flatted JavaScript library](https://www.npmjs.com/package/flatted), which
+provides a light and fast way to serialize and deserialize JSON structures
+that contain circular references.
+
+Standard JSON cannot handle circular references - attempting to serialize an
+object that references itself will cause an error. Flatted solves this by
+transforming circular structures into a flat array format that can be safely
+serialized and later reconstructed.
+
+Common use cases:
+
+- Serializing complex object graphs with circular references.
+- Working with DOM-like structures that contain parent/child references.
+- Preserving object identity when serializing data structures.
+
+```python
+from pyscript import flatted
+
+
+# Create a circular structure.
+obj = {"name": "parent"}
+obj["self"] = obj  # Circular reference!
+
+# Standard json.dumps would fail here.
+serialized = flatted.stringify(obj)
+
+# Reconstruct the original structure.
+restored = flatted.parse(serialized)
+assert restored["self"] is restored  # Circular reference preserved!
+```
+"""
 
 import json as _json
 
@@ -114,6 +146,26 @@ def _wrap(value):
 
 
 def parse(value, *args, **kwargs):
+    """
+    Parse a Flatted JSON string and reconstruct the original structure.
+
+    This function takes a `value` containing a JSON string created by
+    Flatted's stringify() and reconstructs the original Python object,
+    including any circular references. The `*args` and `**kwargs` are passed
+    to json.loads() for additional customization.
+
+    ```python
+    from pyscript import flatted
+
+
+    # Parse a Flatted JSON string.
+    json_string = '[{"name": "1", "self": "0"}, "parent"]'
+    obj = flatted.parse(json_string)
+
+    # Circular references are preserved.
+    assert obj["self"] is obj
+    ```
+    """
     json = _json.loads(value, *args, **kwargs)
     wrapped = []
     for value in json:
@@ -138,6 +190,31 @@ def parse(value, *args, **kwargs):
 
 
 def stringify(value, *args, **kwargs):
+    """
+    Serialize a Python object to a Flatted JSON string.
+
+    This function converts `value`, a Python object (including those with
+    circular references), into a JSON string that can be safely transmitted
+    or stored. The resulting string can be reconstructed using Flatted's
+    parse(). The `*args` and `**kwargs` are passed to json.dumps() for
+    additional customization.
+
+    ```python
+    from pyscript import flatted
+
+
+    # Create an object with a circular reference.
+    parent = {"name": "parent", "children": []}
+    child = {"name": "child", "parent": parent}
+    parent["children"].append(child)
+
+    # Serialize it (standard json.dumps would fail here).
+    json_string = flatted.stringify(parent)
+
+    # Can optionally pretty-print via JSON indentation etc.
+    pretty = flatted.stringify(parent, indent=2)
+    ```
+    """
     known = _Known()
     input = []
     output = []

package/src/stdlib/pyscript/fs.py

@@ -1,7 +1,63 @@
+"""
+This module provides an API for mounting directories from the user's local
+filesystem into the browser's virtual filesystem. This means Python code,
+running in the browser, can read and write files on the user's local machine.
+
+!!! warning
+    **This API only works in Chromium-based browsers** (Chrome, Edge,
+    Vivaldi, Brave, etc.) that support the
+    [File System Access API](https://wicg.github.io/file-system-access/).
+
+The module maintains a `mounted` dictionary that tracks all currently mounted
+paths and their associated filesystem handles.
+
+```python
+from pyscript import fs, document, when
+
+
+# Mount a local directory to the `/local` mount point in the browser's
+# virtual filesystem (may prompt user for permission).
+await fs.mount("/local")
+
+# Alternatively, mount on a button click event. This is important because
+# if the call to `fs.mount` happens after a click or other transient event,
+# the confirmation dialog will not be shown.
+@when("click", "#mount-button")
+async def handler(event):
+    await fs.mount("/another_dir")
+
+# Work with files in the mounted directory as usual.
+with open("/local/example.txt", "w") as f:
+    f.write("Hello from PyScript!")
+
+# Ensure changes are written to local filesystem.
+await fs.sync("/local")
+
+# Clean up when done.
+await fs.unmount("/local")
+```
+"""
+
+import js
+from _pyscript import fs as _fs, interpreter
+from pyscript import window
+from pyscript.ffi import to_js
+from pyscript.context import RUNNING_IN_WORKER
+
+# Worker-specific imports.
+if RUNNING_IN_WORKER:
+    from pyscript.context import sync as sync_with_worker
+    from polyscript import IDBMap
+
 mounted = {}
+"""Global dictionary tracking mounted paths and their filesystem handles."""
 
 
-async def get_handler(details):
+async def _check_permission(details):
+    """
+    Check if permission has been granted for a filesystem handler. Returns
+    the handler if permission is granted, otherwise None.
+    """
     handler = details.handler
     options = details.options
     permission = await handler.queryPermission(options)
@@ -9,94 +65,194 @@ async def get_handler(details):
 
 
 async def mount(path, mode="readwrite", root="", id="pyscript"):
-    import js
-    from _pyscript import fs, interpreter
-    from pyscript.ffi import to_js
-    from pyscript.magic_js import (
-        RUNNING_IN_WORKER,
-        sync,
-    )
+    """
+    Mount a directory from the local filesystem to the virtual filesystem
+    at the specified `path` mount point. The `mode` can be "readwrite" or
+    "read" to specify access level. The `root` parameter provides a hint
+    for the file picker starting location. The `id` parameter allows multiple
+    distinct mounts at the same path.
+
+    On first use, the browser will prompt the user to select a directory
+    and grant permission.
 
+    ```python
+    from pyscript import fs
+
+
+    # Basic mount with default settings.
+    await fs.mount("/local")
+
+    # Mount with read-only access.
+    await fs.mount("/readonly", mode="read")
+
+    # Mount with a hint to start in Downloads folder.
+    await fs.mount("/downloads", root="downloads")
+
+    # Mount with a custom ID to track different directories.
+    await fs.mount("/project", id="my-project")
+    ```
+
+    If called during a user interaction (like a button click), the
+    permission dialog may be skipped if permission was previously granted.
+    """
     js.console.warn("experimental pyscript.fs ⚠️")
 
+    # Check if path is already mounted with a different ID.
+    mount_key = f"{path}@{id}"
+    if path in mounted:
+        # Path already mounted - check if it's the same ID.
+        for existing_key in mounted.keys():
+            if existing_key.startswith(f"{path}@") and existing_key != mount_key:
+                raise ValueError(
+                    f"Path '{path}' is already mounted with a different ID. "
+                    f"Unmount it first or use a different path."
+                )
+
     details = None
     handler = None
 
-    uid = f"{path}@{id}"
-
     options = {"id": id, "mode": mode}
     if root != "":
         options["startIn"] = root
 
     if RUNNING_IN_WORKER:
-        fsh = sync.storeFSHandler(uid, to_js(options))
+        fs_handler = sync_with_worker.storeFSHandler(mount_key, to_js(options))
 
-        # allow both async and/or SharedArrayBuffer use case
-        if isinstance(fsh, bool):
-            success = fsh
+        # Handle both async and SharedArrayBuffer use cases.
+        if isinstance(fs_handler, bool):
+            success = fs_handler
         else:
-            success = await fsh
+            success = await fs_handler
 
         if success:
-            from polyscript import IDBMap
-            from pyscript import window
-
-            idbm = IDBMap.new(fs.NAMESPACE)
-            details = await idbm.get(uid)
-            handler = await get_handler(details)
+            idbm = IDBMap.new(_fs.NAMESPACE)
+            details = await idbm.get(mount_key)
+            handler = await _check_permission(details)
             if handler is None:
-                # force await in either async or sync scenario
-                await js.Promise.resolve(sync.getFSHandler(details.options))
+                # Force await in either async or sync scenario.
+                await js.Promise.resolve(sync_with_worker.getFSHandler(details.options))
                 handler = details.handler
-
         else:
-            raise RuntimeError(fs.ERROR)
+            raise RuntimeError(_fs.ERROR)
 
     else:
-        success = await fs.idb.has(uid)
+        success = await _fs.idb.has(mount_key)
 
         if success:
-            details = await fs.idb.get(uid)
-            handler = await get_handler(details)
+            details = await _fs.idb.get(mount_key)
+            handler = await _check_permission(details)
             if handler is None:
-                handler = await fs.getFileSystemDirectoryHandle(details.options)
+                handler = await _fs.getFileSystemDirectoryHandle(details.options)
         else:
             js_options = to_js(options)
-            handler = await fs.getFileSystemDirectoryHandle(js_options)
+            handler = await _fs.getFileSystemDirectoryHandle(js_options)
             details = {"handler": handler, "options": js_options}
-            await fs.idb.set(uid, to_js(details))
+            await _fs.idb.set(mount_key, to_js(details))
 
     mounted[path] = await interpreter.mountNativeFS(path, handler)
 
 
-async def revoke(path, id="pyscript"):
-    from _pyscript import fs, interpreter
-    from pyscript.magic_js import (
-        RUNNING_IN_WORKER,
-        sync,
-    )
+async def sync(path):
+    """
+    Synchronise the virtual and local filesystems for a mounted `path`.
 
-    uid = f"{path}@{id}"
+    This ensures all changes made in the browser's virtual filesystem are
+    written to the user's local filesystem, and vice versa.
 
-    if RUNNING_IN_WORKER:
-        had = sync.deleteFSHandler(uid)
-    else:
-        had = await fs.idb.has(uid)
-        if had:
-            had = await fs.idb.delete(uid)
+    ```python
+    from pyscript import fs
 
-    if had:
-        interpreter._module.FS.unmount(path)
 
-    return had
+    await fs.mount("/local")
 
+    # Make changes to files.
+    with open("/local/data.txt", "w") as f:
+        f.write("Important data")
 
-async def sync(path):
+    # Ensure changes are written to local disk.
+    await fs.sync("/local")
+    ```
+
+    This is automatically called by unmount(), but you may want to call
+    it explicitly to ensure data persistence at specific points.
+    """
+    if path not in mounted:
+        raise KeyError(
+            f"Path '{path}' is not mounted. " f"Use fs.mount() to mount it first."
+        )
     await mounted[path].syncfs()
 
 
 async def unmount(path):
-    from _pyscript import interpreter
+    """
+    Unmount a directory, specified by `path`, from the virtual filesystem.
+
+    This synchronises any pending changes and then removes the mount point,
+    freeing up memory. The `path` can be reused for mounting a different
+    directory.
+
+    ```python
+    from pyscript import fs
+
+
+    await fs.mount("/local")
+    # ... work with files ...
+    await fs.unmount("/local")
+
+    # Path can now be reused.
+    await fs.mount("/local", id="different-folder")
+    ```
+
+    This automatically calls `sync()` before unmounting to ensure no data
+    is lost.
+    """
+    if path not in mounted:
+        raise KeyError(f"Path '{path}' is not mounted. Cannot unmount.")
 
     await sync(path)
     interpreter._module.FS.unmount(path)
+    del mounted[path]
+
+
+async def revoke(path, id="pyscript"):
+    """
+    Revoke filesystem access permission and unmount for a given
+    `path` and `id` combination.
+
+    This removes the stored permission for accessing the user's local
+    filesystem at the specified path and ID. Unlike `unmount()`, which only
+    removes the mount point, `revoke()` also clears the permission so the
+    user will be prompted again on next mount.
+
+    ```python
+    from pyscript import fs
+
+
+    await fs.mount("/local", id="my-app")
+    # ... work with files ...
+
+    # Revoke permission (user will be prompted again next time).
+    revoked = await fs.revoke("/local", id="my-app")
+
+    if revoked:
+        print("Permission revoked successfully")
+    ```
+
+    After revoking, the user will need to grant permission again and
+    select a directory when `mount()` is called next time.
+    """
+    mount_key = f"{path}@{id}"
+
+    if RUNNING_IN_WORKER:
+        handler_exists = sync_with_worker.deleteFSHandler(mount_key)
+    else:
+        handler_exists = await _fs.idb.has(mount_key)
+        if handler_exists:
+            handler_exists = await _fs.idb.delete(mount_key)
+
+    if handler_exists:
+        interpreter._module.FS.unmount(path)
+        if path in mounted:
+            del mounted[path]
+
+    return handler_exists