pyodide/webtypy

Python type definitions for web APIs

Pyodide is a Python distribution for the browser and Node.js based on WebAssembly.

What is Pyodide?

Pyodide is a port of CPython to WebAssembly/Emscripten.

Pyodide makes it possible to install and run Python packages in the browser with micropip. Any pure Python package with a wheel available on PyPi is supported. Many packages with C extensions have also been ported for use with Pyodide. These include many general-purpose packages such as regex, PyYAML, lxml and scientific Python packages including NumPy, pandas, SciPy, Matplotlib, and scikit-learn.

Pyodide comes with a robust Javascript ⟺ Python foreign function interface so that you can freely mix these two languages in your code with minimal friction. This includes full support for error handling, async/await, and much more.

When used inside a browser, Python has full access to the Web APIs.

Try Pyodide (no installation needed)

Try Pyodide in a REPL directly in your browser. For further information, see the documentation.

Getting Started

Pyodide offers three different ways to get started depending on your needs and technical resources. These include:

• Use a hosted distribution of Pyodide: see the Getting Started documentation.
• Download a version of Pyodide from the releases page and serve it with a web server.
• Build Pyodide from source
  • Build natively with make: primarily for Linux users who want to experiment or contribute back to the project.
  • Use a Docker image: recommended for Windows and macOS users and for Linux users who prefer a Debian-based Docker image with the dependencies already installed.

History

Pyodide was created in 2018 by Michael Droettboom at Mozilla as part of the Iodide project. Iodide is an experimental web-based notebook environment for literate scientific computing and communication.

Iodide is no longer maintained. If you want to use Pyodide in an interactive client-side notebook, see Pyodide notebook environments.

Contributing

Please view the contributing guide for tips on filing issues, making changes, and submitting pull requests. Pyodide is an independent and community-driven open-source project. The decision-making process is outlined in the Project governance.

Communication

• Blog: blog.pyodide.org
• Mailing list: mail.python.org/mailman3/lists/pyodide.python.org/
• Twitter: twitter.com/pyodide
• Stack Overflow: stackoverflow.com/questions/tagged/pyodide
• Discord: Pyodide Discord

License

Pyodide uses the Mozilla Public License Version 2.0.

webtypy's Issues

Add api Docstrings from some source (e.g., MDN)

Primary goal: provide minimal docstrings on the Apis.
Secondary goals:

• open up and pave the road to adding compatibility informations aka supported platforms (see issue
• add a link to mdn docs when available

---

The MDN content markup may be a good source of structured data to harvest (and its html counterpart).

Also notice some comments in a json file from TypeScript-DOM-lib-generator; probably used to fuel Typescript stubs comments (don't know how this json is made).

Another source to investigate probably generated from Typescript stubs.

Consider splitting __init__.pyi into several files

Right now __init__.pyi is 14k lines of code which is massive, and doesn't even load in GitHub properly for me.

If possible it could be good to split it into submodules (all of which are imported from __init__.pyi). PEP 561 doesn't say anything about it, but in practice for instance the typeshed package does this so it probably works fine. Though there might be something about using from a import b as b for it to work.

CSSStyleDeclaration.display is missing

Project name (continued)

A fair number of users in Pyodide are coming from Python and have relatively little knowledge of the JS world. So a name like web-idl wouldn't really tell them much, and actually, there is a very similar-sounding stdlib module https://docs.python.org/3/library/idle.html. So personally, when seeing this package name in emails I thought this was a web version of that :)

Sorry I missed the pings in the parent issues about naming. If it's not too late, and if the target audience is Python developers who are going to use this from Python, I would suggest something that would be more familiar to them.

Here are some (filtered) "free associations" by GPT4 for the name,

1. pyodide-webtypes: This name suggests that the package contains type annotations specific to the web platform within the Pyodide ecosystem.
2. webtypy: A playful combination of "web," "type," and "Python" that reflects the package's goal of providing type annotations for web platform native objects in Python.
3. pywebidl: Drawing inspiration from Web IDL, this name suggests that the package serves a similar purpose in the context of Python and Pyodide.
4. webpytypes: Combining "web," "Python," and "types," this name signifies that the package provides Python type annotations for the web platform. [the issue is that web.py is an existing web framework (rth)]
5. pybrowserdefs: Combining "Python," "browser," and "definitions," this name highlights that the package offers type definitions for browser components and web platform native objects in Python.

another thing to keep in mind is that it's better for the project name to be searchable. Even once this project exists with documentation people will never end up on this page by searching "web idl", they would probably have to search "python web idl" but then they would end up on all the Python parsers for web IDL (such as widlparser and pywebidl2. They would end up here searching "pyodide web idl" but that's very specific, and as far as I understand the project could potentially for any Python in the browser distribution.

I was going to suggest pywebidl, but then it would feel like pywebidl2 is the next version.
Maybe webtypy could be cute, and relatively searchable.

"python web idl" -> 4M google search results
webtypy -> "17k "

I also like a vague association with with mypy with lots of "y".

But anyway @simonegiacomelli it's your project, so you should choose the name :) We can also keep the current name.

Write a how-to guide for building .pyi files locally from the repository

It would be nice if there is a guide on how users (potential contributors) can build .pyi file locally from this repository.

Originally posted by @ryanking13 in #7 (comment)

Improving readme

I just had a look at the readme, and I think it could use some updates keeping in mind the target audience.

Correct me if I'm wrong, but I think users would be mostly interested in,

1. what this is: the first paragraph is OK
2. how to use it: right now it's not clear to me how to use this from the readme

As to the detailed generation process, well it's interesting but pretty technical and so maybe not something users need to be aware at first.

Also, some CI with a badge in the readme would really add confidence that this is a maintained project that can be relied on (speaking as a user).

Thanks for working on this project :)

DocumentOrShadowRoot is empty

First steps and planning

@hoodmane @rth @ryanking13

These are the first steps where I could focus my energies for now:

• Copy the source code of the generator in this repo (the linked repository contains more than that, so I will not bring in the history of everything there. Just that folder in the current state.
• Organize the project with the src layout.
• Run the tests of the generator on every push through GitHub Actions
• Write some documentation
• Create some script/automation to generate the js.pyi artifact and push it to pypi
• Bring in the existing open issues from the other repo
• Plan something to join manual webidls (sadly I noticed that no one webidl source is enough...) now the best webidl source I know is from w3c/webref/curated

And then these points are for adding comments to the api:

• Investigate how to gather the information about api platform availability (probably from the webidl files)
• Gather/harvest comments from MDN (maybe there is some structured information about the previous point?)

What do you think?