Docs Fix cross references to abort signal and abort controller [skip ci] (pyodide#5275)

Author: hoodmane

docs/conf.py

@@ -26,7 +26,7 @@
 
 def ignore_typevars():
     """These are all intentionally broken. Disable the warnings about it."""
-    PY_TYPEVARS_TO_IGNORE = ("T", "T_co", "T_contra", "V_co", "KT", "VT", "VT_co")
+    PY_TYPEVARS_TO_IGNORE = ("T", "T_co", "T_contra", "V_co", "KT", "VT", "VT_co", "P")
     JS_TYPEVARS_TO_IGNORE = ("TResult", "TResult1", "TResult2", "U")
 
     nitpick_ignore.extend(
@@ -350,6 +350,7 @@ def typehints_formatter(annotation, config):
         module = get_annotation_module(annotation)
         class_name = get_annotation_class_name(annotation, module)
     except ValueError:
+        assert annotation == Ellipsis
         return None
     full_name = f"{module}.{class_name}"
     if full_name == "typing.TypeVar":
@@ -358,6 +359,11 @@ def typehints_formatter(annotation, config):
         return f"``{annotation.__name__}``"
     if full_name == "ast.Module":
         return "`Module <https://docs.python.org/3/library/ast.html#module-ast>`_"
+    # TODO: perhaps a more consistent way to handle JS xrefs / type annotations?
+    if full_name == "pyodide.http.AbortController":
+        return ":js:class:`AbortController`"
+    if full_name == "pyodide.http.AbortSignal":
+        return ":js:class:`AbortSignal`"
     return None
 
 

docs/sphinx_pyodide/sphinx_pyodide/mdn_xrefs.py

@@ -17,6 +17,8 @@
         "showDirectoryPicker": "API/Window/",
     },
     "js:class": {
+        "AbortController": "API/",
+        "AbortSignal": "API/",
         "Array": "$global/",
         "NodeList": "API/",
         "XMLHttpRequest": "API/",
@@ -41,6 +43,7 @@
         "Float32Array": "$global/",
         "Float64Array": "$global/",
         "Map": "$global/",
+        "Response": "API/",
         "Set": "$global/",
         # the JavaScript domain has no exception type for some reason...
         "Error": "$global/",

src/py/_pyodide/_core_docs.py

@@ -893,6 +893,12 @@ def aclose(self) -> Awaitable[None]:
 
 
 class JsCallable(JsProxy, Generic[P, T]):
+    """A JavaScript callable
+
+    A JavaScript object is treated as a callable if `typeof x` returns
+    `"function"`.
+    """
+
     _js_type_flags = ["IS_CALLABLE"]
 
     __call__: Callable[P, T]
@@ -1175,6 +1181,13 @@ def __delitem__(self, idx: KT) -> None:
 
 
 class JsOnceCallable(JsCallable[P, T], Generic[P, T]):
+    """A JavaScript handle for a Python function which can be called at most
+    once.
+
+    After it is called, the reference to the underlying Python object is
+    released and attempting to call it again will raise an `Error`.
+    """
+
     def destroy(self):
         pass
 
@@ -1603,6 +1616,7 @@ def can_run_sync() -> bool:
     "JsProxy",
     "JsDomElement",
     "JsCallable",
+    "JsOnceCallable",
     "JsTypedArray",
     "run_sync",
     "can_run_sync",

src/py/pyodide/ffi/__init__.py

@@ -46,6 +46,7 @@
     "JsIterator",
     "JsMap",
     "JsMutableMap",
+    "JsOnceCallable",
     "JsPromise",
     "JsProxy",
     "JsDomElement",

src/py/pyodide/http.py

@@ -19,15 +19,43 @@
         from js import XMLHttpRequest
     except ImportError:
         pass
+else:
+    # Hack for documentation xrefs, we replace these with links to mdn in the
+    # sphinx conf.py. TODO: Maybe come up with some better / more systematic way
+    # to handle this situation.
+    class AbortController:  # type:ignore[no-redef]
+        pass
+
+    class AbortSignal:  # type:ignore[no-redef]
+        pass
+
 
 __all__ = [
     "open_url",
     "pyfetch",
     "FetchResponse",
+    "HttpStatusError",
+    "BodyUsedError",
+    "AbortError",
 ]
 
 
 class HttpStatusError(OSError):
+    """A subclass of :py:exc:`OSError` raised by :py:meth:`FetchResponse.raise_for_status`
+    if the response status is 4XX or 5XX.
+
+    Parameters
+    ----------
+    status :
+       The http status code of the request
+
+    status_text :
+       The http status text of the request
+
+    url :
+        The url that was requested
+    """
+
     status: int
     status_text: str
     url: str
@@ -135,9 +163,13 @@ class FetchResponse:
     Parameters
     ----------
     url
-        URL to fetch
+        URL that was fetched
     js_response
-        A :py:class:`~pyodide.ffi.JsProxy` of the fetch response
+        A :py:class:`~pyodide.ffi.JsProxy` of the fetch :js:class:`Response`.
+    abort_controller
+        The abort controller that may be used to cancel the fetch request.
+    abort_signal
+        The abort signal that was used for the fetch request.
     """
 
     def __init__(
@@ -223,7 +255,7 @@ def _raise_if_failed(self) -> None:
             raise BodyUsedError
 
     def raise_for_status(self) -> None:
-        """Raise an :py:exc:`HttpStatusError` if the status of the response is an error (4xx or 5xx)"""
+        """Raise an :py:exc:`~pyodide.http.HttpStatusError` if the status of the response is an error (4xx or 5xx)"""
         if 400 <= self.status < 600:
             raise HttpStatusError(self.status, self.status_text, self.url)