Updated API source.

Author: ntoll

pyscript/__init__.py

@@ -1,7 +1,7 @@
 """
 This is the main `pyscript` namespace. It provides the primary Pythonic API
 for users to interact with the
-[browser's own API](https://developer.mozilla.org/en-US/docs/Web/API). It 
+[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.
@@ -47,7 +47,7 @@
 
 
 !!! Note
-    Some notes about the naming conventions and the relationship between 
+    Some notes about the naming conventions and the relationship between
     various similar-but-different names found within this code base.
 
     ```python
@@ -63,17 +63,18 @@
     ```
 
     The `_pyscript` module is an internal API implemented in JS. **End users
-    should not use it directly**. For its implementation, grep for 
+    should not use it directly**. For its implementation, grep for
     `interpreter.registerJsModule("_pyscript",...)` in `core.js`.
 
     ```python
     import js
     ```
 
-    The `js` object 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.
+    The `js` object is
+    [the JS `globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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.
 
     ```python
     import pyscript.context
@@ -85,7 +86,7 @@
     mostly for internal PyScript use or advanced users. 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 
+    they are proxies which work thanks to
     [coincident](https://github.com/WebReflection/coincident).
 
     ```python

pyscript/context.py

@@ -3,7 +3,7 @@
 
 This module handles the differences between running in the
 [main browser thread](https://developer.mozilla.org/en-US/docs/Glossary/Main_thread)
-versus running in a 
+versus running in a
 [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers),
 providing a consistent API regardless of the execution context.
 

pyscript/events.py

@@ -49,7 +49,7 @@ def __init__(self):
 
     def trigger(self, result):
         """
-        Trigger the event and notify all listeners with the given result.
+        Trigger the event and notify all listeners with the given `result`.
         """
         for listener in self._listeners:
             if is_awaitable(listener):
@@ -61,7 +61,7 @@ def add_listener(self, listener):
         """
         Add a function to be called when this event is triggered.
 
-        The listener must be callable. It can be either a regular function
+        The `listener` must be callable. It can be either a regular function
         or an async function. Duplicate listeners are ignored.
         """
         if not callable(listener):
@@ -72,7 +72,7 @@ def add_listener(self, listener):
 
     def remove_listener(self, *listeners):
         """
-        Remove specified listeners. If none specified, remove all listeners.
+        Remove specified `listeners`. If none specified, remove all listeners.
         """
         if listeners:
             for listener in listeners:
@@ -166,7 +166,7 @@ def decorator(func):
 
 def _get_elements(selector):
     """
-    Convert various selector types into a list of DOM elements.
+    Convert various `selector` types into a list of DOM elements.
     """
     from pyscript.web import Element, ElementCollection
 
@@ -184,7 +184,7 @@ def _get_elements(selector):
 
 def _create_wrapper(func):
     """
-    Create an appropriate wrapper for the given function.
+    Create an appropriate wrapper for the given function, `func`.
 
     The wrapper handles both sync and async functions, and respects whether
     the function expects to receive event arguments.

pyscript/fetch.py

@@ -1,5 +1,5 @@
 """
-This module provides a Python-friendly interface to the 
+This module provides a Python-friendly interface to the
 [browser's fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API),
 returning native Python data types and supporting directly awaiting the promise
 and chaining method calls directly on the promise.
@@ -156,15 +156,13 @@ def fetch(url, **options):
 
     The function takes a `url` and optional fetch `options` as keyword
     arguments. The `options` correspond to the JavaScript fetch API's
-    RequestInit dictionary, and commonly include:
+    [RequestInit dictionary](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit),
+    and commonly include:
 
     - `method`: HTTP method (e.g., `"GET"`, `"POST"`, `"PUT"` etc.)
     - `headers`: Dict of request headers.
     - `body`: Request body (string, dict for JSON, etc.)
 
-    See [this documentation](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
-    for more details of these web standards.
-
     The function returns a promise that resolves to a Response-like object
     with Pythonic methods to extract data:
 

pyscript/ffi.py

@@ -1,8 +1,9 @@
 """
-This module provides a unified Foreign Function Interface (FFI) layer that
-works consistently across both Pyodide and MicroPython, and in worker or main
-thread contexts, abstracting away the differences in their JavaScript interop
-APIs.
+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:
 
@@ -74,7 +75,7 @@ def to_js(value, **kw):
     """
     Convert Python objects to JavaScript objects.
 
-    This ensures a Python `dict` becomes a 
+    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.
@@ -86,7 +87,7 @@ def to_js(value, **kw):
     from pyscript import ffi
     import js
 
-    
+
     note = {
         "body": "This is a notification",
         "icon": "icon.png"
@@ -111,7 +112,7 @@ def is_none(value):
     from pyscript import ffi
     import js
 
-    
+
     val1 = None
     val2 = js.null
     val3 = 42

pyscript/flatted.py

@@ -1,5 +1,5 @@
 """
-This module is a Python implementation of the 
+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.
@@ -157,7 +157,7 @@ def parse(value, *args, **kwargs):
     ```python
     from pyscript import flatted
 
-    
+
     # Parse a Flatted JSON string.
     json_string = '[{"name": "1", "self": "0"}, "parent"]'
     obj = flatted.parse(json_string)
@@ -202,7 +202,7 @@ def stringify(value, *args, **kwargs):
     ```python
     from pyscript import flatted
 
-    
+
     # Create an object with a circular reference.
     parent = {"name": "parent", "children": []}
     child = {"name": "child", "parent": parent}

pyscript/fs.py

@@ -5,7 +5,7 @@
 
 !!! warning
     **This API only works in Chromium-based browsers** (Chrome, Edge,
-    Opera, Brave, etc.) that support the 
+    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
@@ -78,7 +78,7 @@ async def mount(path, mode="readwrite", root="", id="pyscript"):
     ```python
     from pyscript import fs
 
-    
+
     # Basic mount with default settings.
     await fs.mount("/local")
 
@@ -162,7 +162,7 @@ async def sync(path):
     ```python
     from pyscript import fs
 
-    
+
     await fs.mount("/local")
 
     # Make changes to files.
@@ -194,7 +194,7 @@ async def unmount(path):
     ```python
     from pyscript import fs
 
-    
+
     await fs.mount("/local")
     # ... work with files ...
     await fs.unmount("/local")
@@ -227,7 +227,7 @@ async def revoke(path, id="pyscript"):
     ```python
     from pyscript import fs
 
-    
+
     await fs.mount("/local", id="my-app")
     # ... work with files ...
 

pyscript/media.py

@@ -41,7 +41,7 @@ class Device:
     """
     Represents a media input or output device.
 
-    This class wraps a browser 
+    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).
@@ -52,7 +52,7 @@ class Device:
     ```python
     from pyscript.media import list_devices
 
-    
+
     # Get all available devices.
     devices = await list_devices()
 
@@ -135,7 +135,7 @@ async def request_stream(cls, audio=False, video=True):
         from pyscript import document
         from pyscript.media import Device
 
-        
+
         # Get default video stream.
         stream = await Device.request_stream()
 
@@ -185,7 +185,7 @@ async def get_stream(self):
         ```python
         from pyscript.media import list_devices
 
-        
+
         # List all devices.
         devices = await list_devices()
 
@@ -219,7 +219,7 @@ async def list_devices():
     ```python
     from pyscript.media import list_devices
 
-    
+
     # Get all devices.
     devices = await list_devices()
 

pyscript/storage.py

@@ -109,7 +109,7 @@ class Storage(dict):
     ```python
     from pyscript import storage
 
-    
+
     # Open a storage.
     prefs = await storage("preferences")
 
@@ -130,7 +130,7 @@ class Storage(dict):
     ```python
     from pyscript import storage, Storage, window
 
-    
+
     class LoggingStorage(Storage):
         def __setitem__(self, key, value):
             window.console.log(f"Setting {key} = {value}")
@@ -220,7 +220,7 @@ async def storage(name="", storage_class=Storage):
     ```python
     from pyscript import storage
 
-    
+
     # Basic usage.
     user_data = await storage("user-profile")
     user_data["name"] = "Alice"

pyscript/util.py

@@ -56,8 +56,8 @@ def is_awaitable(obj):
     """
     Returns a boolean indication if the passed in obj is an awaitable
     function. This is interpreter agnostic.
-    
-    !!! info 
+
+    !!! 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.