Important

From your browser, you can try Pyodide in an Iodide notebook. The Iodide documentation site provides additional user and developer documentation.

Pyodide

Build Status

The Python scientific stack, compiled to WebAssembly.

**Try Pyodide and Iodide in your browser**

What is Pyodide?

Pyodide brings the Python runtime to the browser via WebAssembly, along with the Python scientific stack including NumPy, Pandas, Matplotlib, parts of SciPy, and NetworkX. The ``packages` directory <https://github.com/iodide-project/pyodide/tree/master/packages>`_ lists over 35 packages which are currently available.

Pyodide provides transparent conversion of objects between Javascript and Python. When used inside a browser, Python has full access to the Web APIs.

While closely related to the iodide project, a tool for literate scientific computing and communication for the web, Pyodide goes beyond running in a notebook environment. To maximize the flexibility of the modern web, Pyodide may be used standalone in any context where you want to run Python inside a web browser.

Try Pyodide (no installation needed)

For more information, try the demo and look through the documentation.

Getting Started

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

  • Download a pre-built version (the quickest way to get started)
  • Build Pyodide from source (this method requires installing prerequistes and using 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 on Docker Hub with the dependencies already installed)

Download a pre-built version

Pre-built versions of Pyodide may be downloaded from this repository’s releases page.

Building from source

Building is easiest on Linux. For other platforms, we recommend using the Docker image (described below) to build Pyodide.

Make sure the prerequisites for emsdk are installed. Pyodide will build a custom, patched version of emsdk, so there is no need to build it yourself prior.

Additional build prerequisites are:

  • A working native compiler toolchain, enough to build CPython.
  • A native Python 3.7 to run the build scripts.
  • PyYAML
  • lessc to compile less to css.
  • uglifyjs to minify Javascript builds.
  • ccache (optional) recommended for much faster rebuilds.

Build using make

After installing the build prerequisites, run from the command line:

make

Using Docker

We provide a Debian-based Docker image on Docker Hub with the dependencies already installed to make it easier to build Pyodide.

  1. Install Docker
  2. From a git checkout of Pyodide, run ./run_docker
  3. Run make to build.

If running make deterministically stops at one point in each subsequent try, increasing the maximum RAM usage available to the docker container might help [This is different from the physical RAM capacity inside the system]. Ideally, at least 3 GB of RAM should be available to the docker container to build pyodide smoothly. These settings can be changed via Docker Preferences [See here].

You can edit the files in your source checkout on your host machine, and then repeatedly run make inside the Docker environment to test your changes.

Contributing

Please view the CONTRIBUTING document for tips on filing issues, making changes, and submitting pull requests. The following sections describe how to run tests, run Pyodide benchmarks, and lint the source code.

Testing

Install the following dependencies into the default Python installation:

pip install pytest selenium pytest-instafail

Install geckodriver and chromedriver and check that they are in your PATH.

Automated testing

To run the pytest suite of tests, type on the command line:

pytest test/ packages/

Manual interactive testing

To run manual interactive tests, a docker environment and a webserver will be used.

  1. Bind port 8000 for testing. To automatically bind port 8000 of the docker environment and the host system, run: ./run_docker
  2. Now, this can be used to test the pyodide builds running within the docker environment using external browser programs on the host system. To do this, run: ./bin/pyodide serve
  3. This serves the build directory of the pyodide project on port 8000.
    • To serve a different directory, use the --build_dir argument followed by the path of the directory.
    • To serve on a different port, use the --port argument followed by the desired port number. Make sure that the port passed in --port argument is same as the one defined as DOCKER_PORT in the run_docker script.
  4. Once the webserver is running, simple interactive testing can be run by visiting this URL: http://localhost:8000/console.html

Benchmarking

To run common benchmarks to understand Pyodide’s performance, begin by installing the same prerequisites as for testing. Then run:

make benchmark

Linting

Python is linted with flake8. C and Javascript are linted with clang-format.

To lint the code, run:

make lint

License

Pyodide uses the Mozilla Public License Version 2.0. See the LICENSE file for more details.

**What is Pyodide?** | **Try Pyodide** | **Getting Started** | **Contributing** | **License** | **Back to top**

How to Contribute

Thank you for your interest in contributing to PYODIDE! There are many ways to contribute, and we appreciate all of them. Here are some guidelines & pointers for diving into it.

Code of Conduct

PYODIDE has adopted a Code of Conduct that we expect all contributors and core members to adhere to.

Development

Work on PYODIDE happens on Github. Core members and contributors can make Pull Requests to fix issues and add features, which all go through the same review process. We’ll detail how you can start making PRs below.

We’ll do our best to keep master in a non-breaking state, ideally with tests always passing. The unfortunate reality of software development is sometimes things break. As such, master cannot be expected to remain reliable at all times. We recommend using the latest stable version of PYODIDE.

PYODIDE follows semantic versioning (http://semver.org/) - major versions for breaking changes (x.0.0), minor versions for new features (0.x.0), and patches for bug fixes (0.0.x).

We keep a file, CHANGELOG.md, outlining changes to PYODIDE in each release. We like to think of the audience for changelogs as non-developers who primarily run the latest stable. So the change log will primarily outline user-visible changes such as new features and deprecations, and will exclude things that might otherwise be inconsequential to the end user experience, such as infrastructure or refactoring.

Bugs & Issues

We use Github Issues for announcing and discussing bugs and features. Use this link to report an bug or issue. We provide a template to give you a guide for how to file optimally. If you have the chance, please search the existing issues before reporting a bug. It’s possible that someone else has already reported your error. This doesn’t always work, and sometimes it’s hard to know what to search for, so consider this extra credit. We won’t mind if you accidentally file a duplicate report.

Core contributors are monitoring new issues & comments all the time, and will label & organize issues to align with development priorities.

How to Contribute

Pull requests are the primary mechanism we use to change PYODIDE. GitHub itself has some great documentation on using the Pull Request feature. We use the “fork and pull” model described here, where contributors push changes to their personal fork and create pull requests to bring those changes into the source repository.

Please make pull requests against the master branch.

If you’re looking for a way to jump in and contribute, our list of ``good first issues` <https://github.com/iodide-project/pyodide/labels/good%20first%20issue>`_ is a great place to start.

If you’d like to fix a currently-filed issue, please take a look at the comment thread on the issue to ensure no one is already working on it. If no one has claimed the issue, make a comment stating you’d like to tackle it in a PR. If someone has claimed the issue but has not worked on it in a few weeks, make a comment asking if you can take over, and we’ll figure it out from there.

We use py.test, driving Selenium as our testing framework. Every PR will automatically run through our tests, and our test framework will alert you on Github if your PR doesn’t pass all of them. If your PR fails a test, try to figure out whether or not you can update your code to make the test pass again, or ask for help. As a policy we will not accept a PR that fails any of our tests, and will likely ask you to add tests if your PR adds new functionality. Writing tests can be scary, but they make open-source contributions easier for everyone to assess. Take a moment and look through how we’ve written our tests, and try to make your tests match. If you are having trouble, we can help you get started on our test-writing journey.

All code submissions should pass make lint. Python is checked with the default settings of flake8. C and Javascript are checked against the Mozilla style in clang-format.

Development Workflow

See README.md.

License

All contributions to PYODIDE will be licensed under the Mozilla Public License 2.0 (MPL 2.0). This is considered a “weak copyleft” license. Check out the tl;drLegal entry for more information, as well as Mozilla’s MPL 2.0 FAQ if you need further clarification on what is and isn’t permitted.

Get in Touch

  • Gitter: Pyodide currently shares the #iodide channel over at gitter.im

IODIDE CODE of CONDUCT

CONDUCT

We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other similar characteristic.

  • Please be kind and courteous. There’s no need to be mean or rude.
  • On IRC & any other IODIDE communication venue, please avoid using overtly sexual nicknames or other nicknames that might detract from a friendly, safe and welcoming environment for all.
  • Respect that people have differences of opinion and that every design or implementation choice carries a trade-off and numerous costs. There is seldom a right answer.
  • There are many unproductive habits that should be avoided in communication. We borrow the Recurse Center’s “social rules”: no feigning surprise, no well-actually’s, no backseat driving, and no subtle -isms. Read the preceding link for further discussion.
  • Please keep unstructured critique to a minimum. If you have solid ideas you want to experiment with, make a fork and see how it works. All feedback should be constructive in nature. If you need more detailed guidance around giving feedback, consult Digital Ocean’s Code of Conduct.
  • We will exclude you from interaction if you insult, demean or harass anyone. That is not welcome behavior. We interpret the term “harassment” as including the definition in the Citizen Code of Conduct; if you have any lack of clarity about what might be included in that concept, please read their definition. In particular, we don’t tolerate behavior that excludes people in socially marginalized groups.
  • Private harassment is also unacceptable. No matter who you are, if you feel you have been or are being harassed or made uncomfortable by a community member, please contact one of the channel ops or any of the IODIDE core team members immediately. Whether you’re a regular contributor or a newcomer, we care about making this community a safe place for you and we’ve got your back.
  • Likewise any spamming, trolling, flaming, baiting or other attention-stealing behavior is not welcome.

MODERATION

These are the policies for upholding our community’s standards of conduct. If you feel that a thread needs moderation, please contact the IODIDE core team.

  1. Remarks that violate the IODIDE standards of conduct, including hateful, hurtful, oppressive, or exclusionary remarks, are not allowed. (Cursing is allowed, but never targeting another user, and never in a hateful manner.)
  2. Remarks that moderators find inappropriate, whether listed in the code of conduct or not, are also not allowed.
  3. Moderators will first respond to such remarks with a warning.
  4. If the warning is unheeded, the user will be “kicked,” i.e., kicked out of the communication channel to cool off.
  5. If the user comes back and continues to make trouble, they will be banned, i.e., indefinitely excluded.
  6. Moderators may choose at their discretion to un-ban the user if it was a first offense and they offer the offended party a genuine apology.
  7. If a moderator bans someone and you think it was unjustified, please take it up with that moderator, or with a different moderator, in private. Complaints about bans in-channel are not allowed.
  8. Moderators are held to a higher standard than other community members. If a moderator creates an inappropriate situation, they should expect less leeway than others.
  9. In the IODIDE community we strive to go the extra step to look out for each other. Don’t just aim to be technically unimpeachable, try to be your best self. In particular, avoid flirting with offensive or sensitive issues, particularly if they’re off-topic; this all too often leads to unnecessary fights, hurt feelings, and damaged trust; worse, it can drive people away from the community entirely.
  10. And if someone takes issue with something you said or did, resist the urge to be defensive. Just stop doing what it was they complained about and apologize. Even if you feel you were misinterpreted or unfairly accused, chances are good there was something you could’ve communicated better — remember that it’s your responsibility to make your fellow IODIDE community members comfortable. Everyone wants to get along and we are all here first and foremost because we want to talk about science and cool technology. You will find that people will be eager to assume good intent and forgive as long as you earn their trust.
  11. The enforcement policies listed above apply to all official IODIDE venues. If you wish to use this code of conduct for your own project, consider explicitly mentioning your moderation policy or making a copy with your own moderation policy so as to avoid confusion.

Adapted from the the `Rust Code of Conduct <https://www.rust-lang.org/en-US/conduct.html>`_, with further reference from `Digital Ocean Code of Conduct <https://github.com/digitalocean/engineering-code-of-conduct#giving-and-receiving-feedback>`_, the `Recurse Center <https://www.recurse.com/code-of-conduct>`_, the `Citizen Code of Conduct <http://citizencodeofconduct.org/>`_, and the `Contributor Covenant <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>`_.