DOC Add docstrings for open_url, CodeRunner, JsProxy (#4007)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

conftest.py

@@ -1,6 +1,7 @@
 """
 Various common utilities for testing.
 """
+import os
 import pathlib
 import re
 import sys
@@ -16,6 +17,8 @@ sys.path.append(str(ROOT_PATH / "src" / "py"))
 import pytest_pyodide.runner
 from pytest_pyodide.utils import package_is_built as _package_is_built
 
+os.environ["IN_PYTEST"] = "1"
+
 # There are a bunch of global objects that occasionally enter the hiwire cache
 # but never leave. The refcount checks get angry about them if they aren't preloaded.
 # We need to go through and touch them all once to keep everything okay.
@@ -136,7 +139,15 @@ def pytest_collection_modifyitems(config, items):
         cache = config.cache
         prev_test_result = cache.get("cache/lasttestresult", {})
 
+    skipped_docstrings = [
+        "_pyodide._base.CodeRunner",
+        "pyodide.http.open_url",
+    ]
+
     for item in items:
+        if isinstance(item, pytest.DoctestItem) and item.name in skipped_docstrings:
+            item.add_marker(pytest.mark.skip(reason="skipped docstring"))
+            continue
         if prev_test_result.get(item.nodeid) in ("passed", "warnings", "skip_passed"):
             item.add_marker(pytest.mark.skip(reason="previously passed"))
             continue

src/py/_pyodide/_base.py

@@ -211,6 +211,24 @@ class CodeRunner:
 
         The flags to compile with. See the documentation for the built-in
         :external:py:func:`compile` function.
+
+    Examples
+    --------
+    >>> from pyodide.code import CodeRunner
+    >>> source = "1 + 1"
+    >>> code_runner = CodeRunner(source)
+    >>> code_runner.compile()
+    <_pyodide._base.CodeRunner object at 0x113de58>
+    >>> code_runner.run()
+    2
+    >>> my_globals = {"x": 20}
+    >>> my_locals = {"y": 5}
+    >>> source = "x + y"
+    >>> code_runner = CodeRunner(source)
+    >>> code_runner.compile()
+    <_pyodide._base.CodeRunner object at 0x1166bb0>
+    >>> code_runner.run(globals=my_globals, locals=my_locals)
+    25
     """
 
     ast: ast.Module

src/py/_pyodide/_core_docs.py

@@ -1,3 +1,4 @@
+import os
 import sys
 from collections.abc import (
     AsyncIterator,
@@ -38,7 +39,8 @@ Vco = TypeVar("Vco", covariant=True)  # Any type covariant containers.
 VTco = TypeVar("VTco", covariant=True)  # Value type covariant containers.
 Tcontra = TypeVar("Tcontra", contravariant=True)  # Ditto contravariant.
 
-__name__ = "pyodide.ffi"
+if "IN_PYTEST" not in os.environ:
+    __name__ = "pyodide.ffi"
 
 _js_flags: dict[str, int] = {}
 
@@ -125,15 +127,46 @@ class JsProxy(metaclass=_JsProxyMetaClass):
         return "object"
 
     def object_entries(self) -> "JsProxy":
-        "The JavaScript API ``Object.entries(object)``"
+        """
+        The JavaScript API ``Object.entries(object)``
+
+        Examples
+        --------
+        >>> from pyodide.code import run_js
+        >>> js_obj = run_js("({first: 'aa', second: 22})")
+        >>> entries = js_obj.object_entries()
+        >>> [(key, val) for key, val in entries]
+        [('first', 'aa'), ('second', 22)]
+        """
+
         raise NotImplementedError
 
     def object_keys(self) -> "JsProxy":
-        "The JavaScript API ``Object.keys(object)``"
+        """
+        The JavaScript API ``Object.keys(object)``
+
+        Examples
+        --------
+        >>> from pyodide.code import run_js
+        >>> js_obj = run_js("({first: 1, second: 2, third: 3})") # doctest: +SKIP
+        >>> keys = js_obj.object_keys() # doctest: +SKIP
+        >>> list(keys) # doctest: +SKIP
+        ['first', 'second', 'third']
+        """
         raise NotImplementedError
 
     def object_values(self) -> "JsProxy":
-        "The JavaScript API ``Object.values(object)``"
+        """
+        The JavaScript API ``Object.values(object)``
+
+        Examples
+        --------
+        >>> from pyodide.code import run_js
+        >>> js_obj = run_js("({first: 1, second: 2, third: 3})") # doctest: +SKIP
+        >>> values = js_obj.object_values() # doctest: +SKIP
+        >>> list(values) # doctest: +SKIP
+        [1, 2, 3]
+        """
         raise NotImplementedError
 
     def as_object_map(self, *, hereditary: bool = False) -> "JsMutableMap[str, Any]":

src/py/pyodide/http.py

@@ -38,6 +38,18 @@ def open_url(url: str) -> StringIO:
     Returns
     -------
         The contents of the URL.
+
+    Examples
+    --------
+    >>> from pyodide.http import open_url
+    >>> url = "https://cdn.jsdelivr.net/pyodide/v0.23.4/full/repodata.json"
+    >>> url_contents = open_url(url)
+    >>> url_contents.read()
+    {
+      "info": {
+          ... # long output truncated
+        }
+    }
     """
 
     req = XMLHttpRequest.new()