emit a clear error message if you try to use pyscript.sync from the (#1715)

main thread or pyscript.PyWorker from a worker

pyscript.core/src/stdlib/pyscript/__init__.py

@@ -0,0 +1,34 @@
+# Some notes about the naming conventions and the relationship between various
+# similar-but-different names.
+#
+# 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
+#     FFIs. As such, it contains different things in the main thread or in a
+#     worker.
+#
+# import pyscript.magic_js
+#     this submodule abstracts away some of the differences between the main
+#     thread and the 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 the worker they are proxies which work
+#     thanks to coincident.
+#
+# from pyscript import window, document
+#     these are just the window and document objects as defined by
+#     pyscript.magic_js. This is the blessed way to access them from pyscript,
+#     as it works transparently in both the main thread and worker cases.
+
+from pyscript.magic_js import RUNNING_IN_WORKER, window, document, sync
+from pyscript.display import HTML, display
+from pyscript.event_handling import when

pyscript.core/src/stdlib/pyscript/magic_js.py

@@ -1,3 +1,4 @@
+from pyscript.util import NotSupported
 import js as globalThis
 
 RUNNING_IN_WORKER = not hasattr(globalThis, "document")
@@ -5,10 +6,9 @@ RUNNING_IN_WORKER = not hasattr(globalThis, "document")
 if RUNNING_IN_WORKER:
     import polyscript
 
-    # XXX we should use a "smarter" object which emits a clearer error message
-    # if you try to access it
-    PyWorker = None
-
+    PyWorker = NotSupported(
+        'pyscript.PyWorker',
+        'pyscript.PyWorker works only when running in the main thread')
     window = polyscript.xworker.window
     document = window.document
     sync = polyscript.xworker.sync
@@ -21,12 +21,11 @@ if RUNNING_IN_WORKER:
 else:
     import _pyscript
     from _pyscript import PyWorker
-
     window = globalThis
     document = globalThis.document
-    # XXX we should use a "smarter" object which emits a clearer error message
-    # if you try to access it
-    sync = None
+    sync = NotSupported(
+        'pyscript.sync',
+        'pyscript.sync works only when running in a worker')
 
     # in MAIN the current element target exist, just use it
     def current_target():

pyscript.core/src/stdlib/pyscript/util.py

@@ -0,0 +1,22 @@
+class NotSupported:
+    """
+    Small helper that raises exceptions if you try to get/set any attribute on
+    it.
+    """
+
+    def __init__(self, name, error):
+        # we set attributes using self.__dict__ to bypass the __setattr__
+        self.__dict__['name'] = name
+        self.__dict__['error'] = error
+
+    def __repr__(self):
+        return f'<NotSupported {self.name} [{self.error}]>'
+
+    def __getattr__(self, attr):
+        raise AttributeError(self.error)
+
+    def __setattr__(self, attr, value):
+        raise AttributeError(self.error)
+
+    def __call__(self, *args):
+        raise TypeError(self.error)

pyscript.core/types/stdlib/pyscript.d.ts

@@ -4,6 +4,7 @@ declare namespace _default {
         "display.py": string;
         "event_handling.py": string;
         "magic_js.py": string;
+        "util.py": string;
     };
     let pyweb: {
         "pydom.py": string;