Contributing MicroPython type stubs for Pyscript

[Josverl]

I created these stubs for the micropython-stub project,
but I think they are better at home in the pyscript org.

The stubs have been created using a combination of scripting, manual edits and and integration of snippets of documentation from the pyscript docs.

for the micropython version the docs are orginised in a parsable manner - I have not found the time to even attempt the same for pyscript as the documentation structure is significantly different.

Possibly the documentation or API reference could be created from the stubs, and integrated into the documentation. But that is a wider discussion.

Structure

@gregersn
As the incoming stubs or overlapping with, and I think more complete than the pre-existing stubs, I have moved them into a subfolder, as they may still be relevant to Pyscript + Cpython use.

what is your recommendation on this ?
Happy to adjust as needed.

Licensing

I publish all my stubs under the MIT License, but have no object to dual licensing under MIT and Apache

[Josverl]

As I have been informed that my contributions are not welcome, and there was no response to this, I'm not sure what to do.

@ntoll @WebReflection, feel free to let me know your interest.

[ntoll]

@Josverl I can only but apologise. These past few weeks have been manic. I'll engage with this first thing on Monday and we can figure out how to move forward. Thanks for your patience, and to be clear, your contributions ARE very much welcomed.

[Josverl]

No worry's, and no apologies or rush needed.

I'll switch over the authorities path for building the wasm stub packages once it is merged.

Likely some updates coming up with MicroPython v1.27.x , and may need to think how to clarify/integrate semver and Calver, and how to publish Calver to PiPI

[WebReflection]

@Josverl

As I have been informed that my contributions are not welcome

not sure what that refers to, but if it's about recent AI generated content and it wasn't AI but you then it's me that should apologies because I didn't follow any of that answer and it felt really automated ... unless I am misunderstanding all the things, in which case I'd like to understand where you have been informed about that but again, if it's my latest edit, I am sorry.

edit I've now read the other discussion indeed and expanded more in there ... please don't feel not welcomed, as that wasn't the purpose of my reply in there, rather a "please don't do this" 'cause it doesn't properly help us moving forward, thanks again for your understanding.

[ntoll]

@Josverl I've just (finally) taken a look through this. Thank you so much for this most valuable contribution and I see no reason why these shouldn't be merged.

Before merging I have just a couple of questions:

• I notice the stubs say they use PyScript version 2025.2.3 and we're already on 2025.11.1. I also intend to do some major refactoring of the pyscript.web namespace in the new year. Please tell me you have some sort of script to do the extraction of these files from our source code??? 😉 I know of tools like stubgen and others that do this.
• Assuming you have such a script, can we work together to figure out a way for such a script to be run when we cut a release of PyScript such that this repository gets a PR with all the updates (in much the same way the docs and homepage does)..?
• More a note-to-self: instructions for how to use these stubs is probably something that should be in the README of this repository and also in the official PyScript docs.

Any light you can shine on this would be most welcome! 🤗

[Josverl]

Please tell me you have some sort of script to do the extraction of these files from our source code??? 😉 I know of tools like stubgen and others that do this.

Yes, but not from source, but at runtime.
Mostly follows the same automation process as the rest of the stubs, but with some changes due to unique capabilities and inabilities due to the browser environment.
I did my best to design the tooling to be capable to be run in CI, but HIL , wasm in the loop, does have challenges to solve for each port.

• https://micropython-stubber.readthedocs.io/en/main/
• https://github.com/Josverl/micropython-stubber/blob/main/webassembly-stubber%2Freadme.md

Wrt to the integration of the documentation --> Docstrings. Im afraid that currently that is manual copy/paste+Edit. For micropyton i have hand coded a parser for rst to create Docstrings/ docstubs , but as you documentation is in .md, formatted differently that parser is no good for pyscript.
Any .py modules indeed get processed via stubgen, and a few postprocessing steps to undo some issues.

The .Js reflected modules required a seperate approach as they (mostly) don't surface as Python constructable classes, but as instances. With a lot of inheritance.
I wrote a one off script to create stubs from the instances, then used some vscode+regex-foo to simplify the classifieds and add inheritance.
This could be mostly scripted.

I think a relevant question before diving deeply into tooling is whether to:

• generate stubs from documentation
• or API documentation from stubs
• mix or separate functional and API Docs

Each has pros and cons, but I am in favor of maintaining the stubs, automated where possible, and maintain functional docs directly in the publishing format, with crossrefs between them.
But that is not the only way, and some of the tooling will differ based on the process you aim to implement

From the generating documentation from stubs there are several tools to either .MD or .RST

For pyscript.com --> .pyi you may need a custom built parser, or a decent LLM, a good print, and a human review.

[Josverl]

I have limited understanding of how you generate documentation, but it may be something that we can hook into to feed/build some of the stubs.

[ntoll]

@Josverl thanks for the comprehensive context setting, really appreciate it.

So there are two things going on here:

• The work in this PR (which is fine, I can see the stubs being picked up in my VSCode, so I'll approve and merge, and thank you!).
• A plan for how we move forward in some automated way so all the supporting assets (docs, stubs etc...) remain up to date. I'll create a new ticket in this repository with a summary of the story so far, and we can plan over there. I'll cc/ you for visibility.

[ntoll]

See #2