mirror of https://github.com/pyodide/pyodide.git
Update the main readme file to be more user-focused (#475)
* Edit README headings and navigation * Add minor edits and bottom nav * correct link and typo * Address review comments and fix another typo * remove unneeded link from nav
This commit is contained in:
Carol Willing
Michael Droettboom
parent
2cf8639973
commit
4c81899661
149
README.md
149
README.md
|
|
@ -1,30 +1,58 @@
|
|||
# Pyodide
|
||||
**[What is Pyodide?](#what-is-pyodide)** |
|
||||
**[Try Pyodide](#try-pyodide-no-installation-needed)** |
|
||||
**[Getting Started](#getting-started)** |
|
||||
**[Contributing](#contributing)** |
|
||||
**[License](#license)**
|
||||
|
||||
# [Pyodide](https://github.com/iodide-project/pyodide)
|
||||
|
||||
|
||||
[](https://circleci.com/gh/iodide-project/pyodide)
|
||||
|
||||
The Python scientific stack, compiled to WebAssembly.
|
||||
|
||||
It provides transparent conversion of objects between Javascript and Python.
|
||||
When inside a browser, this means Python has full access to the Web APIs.
|
||||
[**Try Pyodide and Iodide in your browser**](https://alpha.iodide.io/notebooks/300/)
|
||||
|
||||
**While closely related to the [iodide project](https://iodide.io), Pyodide may
|
||||
be used standalone in any context where you want to run Python inside a web
|
||||
browser.**
|
||||
## What is Pyodide?
|
||||
|
||||
For more information, see [the demo](https://alpha.iodide.io/notebooks/300/) and the
|
||||
**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](https://iodide.io), 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](https://alpha.iodide.io/notebooks/300/) and look through the
|
||||
[documentation](https://github.com/iodide-project/pyodide/tree/master/docs).
|
||||
|
||||
# Downloading pre-built versions
|
||||
## Getting Started
|
||||
|
||||
Pre-built versions of Pyodide are available
|
||||
[here](https://github.com/iodide-project/pyodide/releases/).
|
||||
Pyodide offers three different ways to get started depending on your needs and technical resources.
|
||||
These include:
|
||||
|
||||
# Building
|
||||
- [Download a pre-built version](#download-a-pre-built-version) (the quickest way to get started)
|
||||
- [Build Pyodide from source](#building-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](#using-docker) (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](https://github.com/iodide-project/pyodide/releases/).
|
||||
|
||||
|
||||
### Building from source
|
||||
|
||||
Building is easiest on Linux. For other platforms, we recommend using
|
||||
the Docker image (described below) to build Pyodide.
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
Make sure the prerequisites for [emsdk](https://github.com/juj/emsdk) are
|
||||
installed. Pyodide will build a custom, patched version of emsdk, so there is no
|
||||
need to build it yourself prior.
|
||||
|
|
@ -38,10 +66,15 @@ Additional build prerequisites are:
|
|||
- [uglifyjs](https://github.com/mishoo/UglifyJS) to minify Javascript builds.
|
||||
- [ccache](https://ccache.samba.org) (optional) recommended for much faster rebuilds.
|
||||
|
||||
#### Build using `make`
|
||||
|
||||
`make`
|
||||
After installing the build prerequisites, run from the command line:
|
||||
|
||||
## Using Docker
|
||||
```bash
|
||||
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.
|
||||
|
|
@ -61,49 +94,87 @@ be changed via Docker Preferences [See [here](https://stackoverflow.com/question
|
|||
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.
|
||||
|
||||
# Testing
|
||||
## Contributing
|
||||
|
||||
Please view the [CONTRIBUTING](CONTRIBUTING.md) 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`
|
||||
```bash
|
||||
pip install pytest selenium pytest-instafail
|
||||
```
|
||||
|
||||
Install [geckodriver](https://github.com/mozilla/geckodriver/releases) and
|
||||
[chromedriver](https://sites.google.com/a/chromium.org/chromedriver/downloads) somewhere
|
||||
on your `PATH`.
|
||||
[chromedriver](https://sites.google.com/a/chromium.org/chromedriver/downloads)
|
||||
and check that they are in your `PATH`.
|
||||
|
||||
`pytest test/ packages/`
|
||||
### Automated testing
|
||||
|
||||
# Manual Testing
|
||||
To run the pytest suite of tests, type on the command line:
|
||||
|
||||
The port 8000 of the docker environment and the host system are automatically
|
||||
binded when ``./run_docker`` is run.
|
||||
```bash
|
||||
pytest test/ packages/
|
||||
```
|
||||
|
||||
This can be used to test the ``pyodide`` builds running within the docker
|
||||
environment using external browser programs on the host system.
|
||||
### Manual interactive testing
|
||||
|
||||
To do this, simply run ``./bin/pyodide serve``
|
||||
To run manual interactive tests, a docker environment and a webserver will be
|
||||
used.
|
||||
|
||||
This serves the ``build`` directory of the ``pyodide`` project on port 8000.
|
||||
1. Bind port 8000 for testing. To automatically bind port 8000 of the docker
|
||||
environment and the host system, run: `./run_docker`
|
||||
|
||||
* 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
|
||||
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`
|
||||
|
||||
Make sure that the port passed in ``--port`` argument is same as the one
|
||||
defined as ``DOCKER_PORT`` in the ``run_docker`` script.
|
||||
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.
|
||||
|
||||
Once the webserver is running, for simple interactive testing, visit the URL
|
||||
[http://localhost:8000/console.html](http://localhost:8000/console.html)
|
||||
|
||||
# Benchmarking
|
||||
4. Once the webserver is running, simple interactive testing can be run by
|
||||
visiting this URL:
|
||||
[http://localhost:8000/console.html](http://localhost:8000/console.html)
|
||||
|
||||
Install the same dependencies as for testing.
|
||||
### Benchmarking
|
||||
|
||||
`make benchmark`
|
||||
To run common benchmarks to understand Pyodide's performance, begin by
|
||||
installing the same prerequisites as for testing. Then run:
|
||||
|
||||
# Linting
|
||||
```bash
|
||||
make benchmark
|
||||
```
|
||||
|
||||
Python is linted with `flake8`. C and Javascript are linted with `clang-format`.
|
||||
### Linting
|
||||
|
||||
`make lint`
|
||||
Python is linted with `flake8`. C and Javascript are linted with
|
||||
`clang-format`.
|
||||
|
||||
To lint the code, run:
|
||||
|
||||
```bash
|
||||
make lint
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Pyodide uses the Mozilla Public License Version 2.0. See the
|
||||
[LICENSE file](LICENSE) for more details.
|
||||
|
||||
---
|
||||
|
||||
**[What is Pyodide?](#what-is-pyodide)** |
|
||||
**[Try Pyodide](try-pyodide-no-installation-needed)** |
|
||||
**[Getting Started](#getting-started)** |
|
||||
**[Contributing](#contributing)** |
|
||||
**[License](#license)** |
|
||||
**[Back to top](#pyodide)**
|
||||
|
|
|
|||
Loading…
Reference in New Issue