From e389f14969900cd5b28cd436b22c45f1283fc569 Mon Sep 17 00:00:00 2001
From: Hood Chatham <roberthoodchatham@gmail.com>
Date: Mon, 25 Dec 2023 22:23:31 -0800
Subject: [PATCH] DOCS: Clarify `registerJsModule` and submodules

---
 src/js/api.ts | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/src/js/api.ts b/src/js/api.ts
index c9b59ad6604..cb4769bf838 100644
--- a/src/js/api.ts
+++ b/src/js/api.ts
@@ -307,6 +307,28 @@ export class PyodideAPI {
    * module from :py:data:`sys.modules`. This calls
    * :func:`~pyodide.ffi.register_js_module`.
    *
+   * Any attributes of the JavaScript objects which are themselves objects will
+   * be treated as submodules:
+   * ```pyodide
+   * pyodide.registerJsModule("mymodule", { submodule: { value: 7 } });
+   * pyodide.runPython(`
+   *     from mymodule.submodule import value
+   *     assert value == 7
+   * `);
+   * ```
+   * If you wish to prevent this, try the following instead:
+   * ```pyodide
+   * const sys = pyodide.pyimport("sys");
+   * sys.modules.set("mymodule", { obj: { value: 7 } });
+   * pyodide.runPython(`
+   *     from mymodule import obj
+   *     assert obj.value == 7
+   *     # attempting to treat obj as a submodule raises ModuleNotFoundError:
+   *     # "No module named 'mymodule.obj'; 'mymodule' is not a package"
+   *     from mymodule.obj import value
+   * `);
+   * ```
+   *
    * @param name Name of the JavaScript module to add
    * @param module JavaScript object backing the module
    */