Add latest version of the pyscript namespace from which the API docs can be generated.

Author: ntoll

pyscript/__init__.py

@@ -0,0 +1,64 @@
+"""
+This is the main `pyscript` namespace. It provides the primary Pythonic API
+for users to interact with PyScript features sitting on top of the browser's
+own API (https://developer.mozilla.org/en-US/docs/Web/API). It includes
+utilities for common activities such as displaying content, handling events,
+fetching resources, managing local storage, and coordinating with web workers.
+
+Some notes about the naming conventions and the relationship between various
+similar-but-different names found within this code base.
+
+`import pyscript`
+
+This package contains the main user-facing API offered by pyscript. All
+the names which are supposed be used by end users should be made
+available in pyscript/__init__.py (i.e., this file).
+
+`import _pyscript`
+
+This is an internal module implemented in JS. It is used internally by
+the pyscript package, **end users should not use it directly**. For its
+implementation, grep for `interpreter.registerJsModule("_pyscript",
+...)` in `core.js`.
+
+`import js`
+
+This is the JS `globalThis`, as exported by Pyodide and/or Micropython's
+foreign function interface (FFI). As such, it contains different things in
+the main thread or in a worker, as defined by web standards.
+
+`import pyscript.context`
+
+This submodule abstracts away some of the differences between the main
+thread and a worker. In particular, it defines `window` and `document`
+in such a way that these names work in both cases: in the main thread,
+they are the "real" objects, in a worker they are proxies which work
+thanks to [coincident](https://github.com/WebReflection/coincident).
+
+`from pyscript import window, document`
+
+These are just the `window` and `document` objects as defined by
+`pyscript.context`. This is the blessed way to access them from `pyscript`,
+as it works transparently in both the main thread and worker cases.
+"""
+
+from polyscript import lazy_py_modules as py_import
+from pyscript.context import (
+    RUNNING_IN_WORKER,
+    PyWorker,
+    config,
+    current_target,
+    document,
+    js_import,
+    js_modules,
+    sync,
+    window,
+)
+from pyscript.display import HTML, display
+from pyscript.fetch import fetch
+from pyscript.storage import Storage, storage
+from pyscript.websocket import WebSocket
+from pyscript.events import when, Event
+
+if not RUNNING_IN_WORKER:
+    from pyscript.workers import create_named_worker, workers

pyscript/context.py

@@ -0,0 +1,175 @@
+"""
+Execution context management for PyScript.
+
+This module handles the differences between running in the main browser thread
+versus running in a Web Worker, providing a consistent API regardless of the
+execution context.
+
+Key features:
+- Detects whether code is running in a worker or main thread. Read this via
+  `pyscript.context.RUNNING_IN_WORKER`.
+- Parses and normalizes configuration from `polyscript.config` and adds the
+  Python interpreter type via the `type` key in `pyscript.context.config`.
+- Provides appropriate implementations of `window`, `document`, and `sync`.
+- Sets up JavaScript module import system, including a lazy `js_import`
+  function.
+- Manages `PyWorker` creation.
+- Provides access to the current display target via
+  `pyscript.context.display_target`.
+
+Main thread context:
+- `window` and `document` are available directly.
+- `PyWorker` can be created to spawn worker threads.
+- `sync` is not available (raises `NotSupported`).
+
+Worker context:
+- `window` and `document` are proxied from main thread (if SharedArrayBuffer
+  available).
+- `PyWorker` is not available (raises `NotSupported`).
+- `sync` utilities are available for main thread communication.
+"""
+
+import json
+import sys
+
+import js
+from polyscript import config as _polyscript_config
+from polyscript import js_modules
+from pyscript.util import NotSupported
+
+# Detect execution context: True if running in a worker, False if main thread.
+RUNNING_IN_WORKER = not hasattr(js, "document")
+
+# Parse and normalize configuration from polyscript.
+config = json.loads(js.JSON.stringify(_polyscript_config))
+if isinstance(config, str):
+    config = {}
+
+# Detect and add Python interpreter type to config.
+if "MicroPython" in sys.version:
+    config["type"] = "mpy"
+else:
+    config["type"] = "py"
+
+
+class _JSModuleProxy:
+    """
+    Proxy for JavaScript modules imported via js_modules.
+
+    This allows Python code to import JavaScript modules using Python's
+    import syntax:
+
+    ```python
+    from pyscript.js_modules lodash import debounce
+    ```
+
+    The proxy lazily retrieves the actual JavaScript module when accessed.
+    """
+
+    def __init__(self, name):
+        """
+        Create a proxy for the named JavaScript module.
+        """
+        self.name = name
+
+    def __getattr__(self, field):
+        """
+        Retrieve a JavaScript object/function from the proxied JavaScript
+        module via the given `field` name.
+        """
+        # Avoid Pyodide looking for non-existent special methods.
+        if not field.startswith("_"):
+            return getattr(getattr(js_modules, self.name), field)
+        return None
+
+
+# Register all available JavaScript modules in Python's module system.
+# This enables: from pyscript.js_modules.xxx import yyy
+for module_name in js.Reflect.ownKeys(js_modules):
+    sys.modules[f"pyscript.js_modules.{module_name}"] = _JSModuleProxy(module_name)
+sys.modules["pyscript.js_modules"] = js_modules
+
+
+# Context-specific setup: Worker vs Main Thread.
+if RUNNING_IN_WORKER:
+    import polyscript
+
+    # PyWorker cannot be created from within a worker.
+    PyWorker = NotSupported(
+        "pyscript.PyWorker",
+        "pyscript.PyWorker works only when running in the main thread",
+    )
+
+    # Attempt to access main thread's window and document via SharedArrayBuffer.
+    try:
+        window = polyscript.xworker.window
+        document = window.document
+        js.document = document
+
+        # Create js_import function that runs imports on the main thread.
+        js_import = window.Function(
+            "return (...urls) => Promise.all(urls.map((url) => import(url)))"
+        )()
+
+    except:
+        # SharedArrayBuffer not available - window/document cannot be proxied.
+        sab_error_message = (
+            "Unable to use `window` or `document` in worker. "
+            "This requires SharedArrayBuffer support. "
+            "See: https://docs.pyscript.net/latest/faq/#sharedarraybuffer"
+        )
+        js.console.warn(sab_error_message)
+        window = NotSupported("pyscript.window", sab_error_message)
+        document = NotSupported("pyscript.document", sab_error_message)
+        js_import = None
+
+    # Worker-specific utilities for main thread communication.
+    sync = polyscript.xworker.sync
+
+    def current_target():
+        """
+        Get the current output target in worker context.
+        """
+        return polyscript.target
+
+else:
+    # Main thread context setup.
+    import _pyscript
+    from _pyscript import PyWorker as _PyWorker, js_import
+    from pyscript.ffi import to_js
+
+    def PyWorker(url, **options):
+        """
+        Create a Web Worker running Python code.
+
+        This spawns a new worker thread that can execute Python code
+        found at the `url`, independently of the main thread. The
+        `**options` can be used to configure the worker.
+
+        ```python
+        from pyscript import PyWorker
+
+        # Create a worker to run background tasks.
+        # (`type` MUST be either `micropython` or `pyodide`)
+        worker = PyWorker("./worker.py", type="micropython")
+        ```
+
+        PyWorker can only be created from the main thread, not from
+        within another worker.
+        """
+        return _PyWorker(url, to_js(options))
+
+    # Main thread has direct access to window and document.
+    window = js
+    document = js.document
+
+    # sync is not available in main thread (only in workers).
+    sync = NotSupported(
+        "pyscript.sync", "pyscript.sync works only when running in a worker"
+    )
+
+    def current_target():
+        """
+        Get the current output target in main thread context.
+        """
+        return _pyscript.target