Contributing MicroPython type stubs for Pyscript

.gitignore

@@ -1,2 +1,4 @@
 build/
 dist/
+.*
+*.egg-info

pyproject.toml

@@ -4,19 +4,29 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyscript_stubs"
-version = "0.0.1"
+version = "0.0.2"
 authors = [
   { name="Greger Stolt Nilsen", email="gregersn@gmail.com" },
+  { name="Jos Verlinde", email="jos_verlinde@hotmail.com" },
 ]
 description = "Typing stubs for Pyscript"
 readme = "README.md"
 requires-python = ">=3.8"
 classifiers = [
     "Programming Language :: Python :: 3",
     "Operating System :: OS Independent",
-    "License :: OSI Approved :: MIT License",
 ]
-
+license = "MIT AND Apache-2.0"
 [project.urls]
-Homepage = "https://github.com/gregersn/pyscript-stubs"
-Issues = "https://github.com/gregersn/pyscript-stubs/issues"
+Homepage = "https://github.com/pyscript/pyscript-stubs"
+Issues = "https://github.com/pyscript/pyscript-stubs/issues"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pyscript*"]
+
+[tool.setuptools.package-data]
+pyscript = ["**/*.pyi"]

readme.md

@@ -0,0 +1,10 @@
+# PyScript Stubs
+
+Because there is no `pyscript` package to install in the Python environment
+used by your IDE, there are no type hints for the IDE to use for code
+analysis while coding a PyScript project.
+
+This project contains [stub files](https://typing.python.org/en/latest/spec/distributing.html#stub-files)
+for PyScript and related projects (for example, MicroPython).
+
+It is a work in progress.

src/pyscript-stubs/base.pyi → src/pyscript-stubs/pre-existing/base.pyi

@@ -1,7 +1,7 @@
 class CSSStyleDeclaration:
     display: str
 
-class EventTarget():
+class EventTarget:
     def addEventListener(self): ...
     def removeEventListener(self): ...
     def dispatchEvent(self): ...

src/pyscript-stubs/element.pyi → src/pyscript-stubs/pre-existing/element.pyi

@@ -2,10 +2,8 @@ from . import CSSStyleDeclaration
 from node import Node
 
 class Element(Node):
-     classList: list[str]
-     onclick: callable
-
+    classList: list[str]
+    onclick: callable
 
 class HTMLElement(Element):
     style: CSSStyleDeclaration
-

src/pyscript-stubs/pre-existing/node.pyi

@@ -0,0 +1,23 @@
+from typing import Optional
+from .base import EventTarget
+from .document_class import Document
+from .element import Element
+
+class Node(EventTarget):
+    baseURI: str
+    childNodes: list["Node"]
+    firstChild: "Node"
+    isConnected: bool
+    lastChild: "Node"
+    nextSibling: "Node"
+    nodeName: str
+    nodeType: int
+    nodeValue: any
+    ownerDocument: "Document"
+    parentNode: Optional["Node"]
+    parentElement: Optional["Element"]
+    previousSibling: Optional["Node"]
+    textContent: str
+
+    def appendChild(self, childNode: "Node"): ...
+    def cloneNode(self) -> "Node": ...

src/pyscript-stubs/window_class.pyi → src/pyscript-stubs/pre-existing/window_class.pyi

@@ -13,4 +13,4 @@ class FileReader(EventTarget):
 class Window(EventTarget):
     console: Console
     FileReader: FileReader
-    location: Location
+    location: Location

src/pyscript-stubs/pyscript/__init__.pyi

@@ -0,0 +1,61 @@
+"""
+PyScript makes available convenience objects, functions and attributes.
+
+These APIs will work with both Pyodide and MicroPython in exactly the same way.
+
+PyScript can run in two contexts: the main browser thread, or on a web worker. T
+he following three categories of API functionality explain features that are common for:
+ - both main thread and worker, 
+ - main thread only, 
+ - and worker only. 
+
+ Most features work in both contexts in exactly the same manner, but please be aware that some are specific to either the main thread 
+ or a worker context.
+
+"""
+# Copyright (c) 2020-2025 Jos Verlinde
+# MIT Licensed
+
+__all__ = [
+    "PyWorker",
+    "config",
+    "current_target",
+    "display",
+    "document",
+    "fetch",
+    "js_import",
+    "js_modules",
+    "py_import",
+    "storage",
+    "sync",
+    "window",
+    "workers",
+    "HTML", 
+    "Event", 
+    "WebSocket", 
+    "create_named_worker"
+]
+
+
+from polyscript import lazy_py_modules as py_import  # type: ignore
+from pyscript.display import HTML as HTML, display as display
+from pyscript.events import Event as Event, when as when
+from pyscript.fetch import fetch as fetch
+from pyscript.magic_js import (
+    RUNNING_IN_WORKER as RUNNING_IN_WORKER,
+    PyWorker as PyWorker,
+    config as config,
+    current_target as current_target,
+    document as document,
+    js_import as js_import,
+    sync as sync,
+    window as window,
+    js_modules as js_modules
+)
+
+from pyscript.storage import Storage as Storage, storage as storage
+from pyscript.websocket import WebSocket as WebSocket
+from pyscript.workers import create_named_worker as create_named_worker, workers as workers
+
+if not RUNNING_IN_WORKER:
+    ...

src/pyscript-stubs/pyscript/_pyscript.pyi

@@ -0,0 +1,39 @@
+# Copyright (c) 2020-2025 Jos Verlinde
+# MIT Licensed
+
+from typing import Any, Callable
+from _typeshed import Incomplete
+
+def js_import(name: str) -> JSModule:
+    """Module level __getattr__ that returns an JSModule object for any requested attribute."""
+    ...
+
+class JSModule:
+    def __init__(self, name) -> None: ...
+    def __getattr__(self, field) -> Any | None: ...
+
+class Worker:
+    async def sync(self) -> Callable: ...
+
+class XWorker(Worker):
+    # https://pyscript.github.io/polyscript/#xworker-options
+
+    polyfill: bool = False
+    window: Incomplete = ...
+
+    def __init__(
+        self,
+        file: str,
+        a_sync: bool = True,
+        config: str = "",
+        type: str = "pyodide",  #  pyodide, micropython, ruby-wasm-wasi, wasmoon, webr
+        version: str = ...,
+        serviceWorker: str = ...,
+    ) -> None: ...
+
+    # def isWindowProxy(self, ref:Incomplete) -> bool: ...
+
+class PyWorker(XWorker):
+    def __init__(self, name) -> None: ...
+
+xworker: XWorker = ...

src/pyscript-stubs/pyscript/display.pyi

@@ -0,0 +1,34 @@
+"""
+Pyscript 2025.2.3 type-stub.
+see: https://docs.pyscript.net/2025.2.3/api/
+"""
+# Copyright (c) 2020-2025 Jos Verlinde
+# MIT Licensed
+
+_MIME_METHODS = ...
+_MIME_RENDERERS = ...
+
+class HTML:
+    """
+    Wrap a string so that display() can render it as plain HTML
+    """
+    def __init__(self, html) -> None: ...
+
+def display(*values, target=None, append: bool = True) -> None:
+    """
+    A function used to display content. The function is intelligent enough to introspect the object[s] it is passed and work out how to correctly
+    display the object[s] in the web page based on the following mime types::
+        - text/plain to show the content as text
+        - text/html to show the content as HTML
+        - image/png to show the content as <img>
+        - image/jpeg to show the content as <img>
+        - image/svg+xml to show the content as <svg>
+        - application/json to show the content as JSON
+        - application/javascript to put the content in <script> (discouraged)
+
+
+    The display function takes a list of *values as its first argument, and has two optional named arguments::
+        - target=None - the DOM element into which the content should be placed. If not specified, the target will use the current_script() returned id and populate the related dedicated node to show the content.
+        - append=True - a flag to indicate if the output is going to be appended to the target.
+    """
+    ...

src/pyscript-stubs/pyscript/events.pyi

@@ -0,0 +1,48 @@
+"""
+Pyscript 2025.2.3 type-stub.
+see: https://docs.pyscript.net/2025.2.3/api/
+"""
+# Copyright (c) 2020-2025 Jos Verlinde
+# MIT Licensed
+
+class Event:
+    """
+    Represents something that may happen at some point in the future.
+    """
+
+    def __init__(self) -> None: ...
+    def trigger(self, result) -> None:
+        """
+        Trigger the event with a result to pass into the handlers.
+        """
+        ...
+
+    def add_listener(self, listener) -> None:
+        """
+        Add a callable/awaitable to listen to when this event is triggered.
+        """
+        ...
+
+    def remove_listener(self, *args) -> None:
+        """
+        Clear the specified handler functions in *args. If no handlers
+        provided, clear all handlers.
+        """
+        ...
+
+def when(
+    target, *args, **kwargs
+):  #  -> _Wrapped[Callable[..., Any], Any, Callable[..., Any], CoroutineType[Any, Any, Any]] | Callable[..., _Wrapped[Callable[..., Any], Any, Callable[..., Any], CoroutineType[Any, Any, Any]]]:
+    """
+    Add an event listener to the target element(s) for the specified event type.
+
+    The target can be a string representing the event type, or an Event object.
+    If the target is an Event object, the event listener will be added to that
+    object. If the target is a string, the event listener will be added to the
+    element(s) that match the (second) selector argument.
+
+    If a (third) handler argument is provided, it will be called when the event
+    is triggered; thus allowing this to be used as both a function and a
+    decorator.
+    """
+    ...