PyScript
npm install @pyscript/corePyScript brings two Python interpreters to the browser:
- MicroPython - a lean and efficient implementation
of the Python 3 programming language that includes a small subset of the
Python standard library and is optimised to run on microcontrollers and in
constrained environments (like the browser).
- Pyodide) - a port of all CPython to WebAssembly.
These interpreters are compiled to WebAssembly
(shortened to WASM). The browser provides a secure WASM computing sandbox. Both
interpreters are compiled to web assembly with
Emscripten. PyScript core maintainers work closely
with the core maintainers of both MicroPython and Pyodide (and CPython). We
work hard to ensure PyScript works efficiently in browsers on all platforms:
desktop, mobile, or elsewhere.
Our technical documentation for using this project can be
found here.
PyScript sits on two further projects (both written in JavaScript):
1. polyscript - used to
bootstrap WASM compiled interpreters in a browser.
2. coincident - used to simplify
worker based tasks.
PyScript itself is mostly written in JavaScript. The test suite for JavaScript
is in two parts: automated tests run in playwright,
and manual tests you have to run in a browser and check yourself. PyScript also
has a plugin system so third parties can extend its capabilities with
JavaScript. Our built-in core plugins can be found in the src/plugins
directory. We describe how to write third party plugins in our
developer documentation.
We provide a pyscript namespace containing Python modules for common browser
based APIs and features (i.e. you can import pyscript in Python code running
inside PyScript, to access these features). The Python code for the pyscript
namespace is in src/stdlib/pyscript with the associated test suite intests/python. The tests use the browser friendly
uPyTest test framework for checking Python
code running _within_ PyScript. All the Python tests are run in each each
available interpreter in both the main thread and a web worker (i.e. the
test suite is run four times, accounting for each combination of interpreter
and main/worker context).
When you create a local build all the automated tests (JavaScript and Python)
are run.
Full instructions for setting up a working development environment, how to
build PyScript and how to test it can be
found in our official docs.
The short version is:
- Ensure you have Python, node and npm installed.
- Create a Python virtual environment.
- In the root of this repository make setup.
- make build to build PyScript.
- As dependencies change over time, make update to keep in sync.
To start using the locally built version of PyScript, you'll need an HTML
page something like this (note the relative paths to assets in the dist
directory, in the of the document):
``html`
Once set up, you should be able to run the most common activities via the
make command:
`
$ make
There is no default Makefile target right now. Try:
make setup - check your environment and install the dependencies.
make update - update dependencies.
make clean - clean up auto-generated assets.
make build - build PyScript.
make precommit-check - run the precommit checks (run eslint).
make test - run all automated tests in playwright.
make fmt - format the code.
make fmt-check - check the code formatting.
`
There are two main artifacts in this project:
- stdlib and its content: src/stdlib/pyscript.js exposes, as asrc/plugins.js
JavaScript object literal, all the _Python_ content within the folder
(recursively).
- plugins and its content: exposes all available_dist/_
_dynamic imports_, and is able to instrument the bundler to create files
apart from the folder, so that by default _core_ remains as small
as possible.
Accordingly, whenever a file contains this warning at its first line, **please
do not change such file directly before submitting a merge request**, as that
file will be overwritten at the next npm run build command, either here or
in _CI_:
`js`
// ⚠️ This file is an artifact: DO NOT MODIFY
While community or third party plugins don't need to be part of this repository
and can be added just importing @pyscript/core as module, there are a few
plugins that we would like to make available by default and these are
considered _core plugins_.
To add a _core plugin_ to this project define the plugin entry-point and name
in the src/plugins folder (see the error.js example) and create, if
necessary, a folder with the same name where extra files or dependencies can be
added.
The _build_ command will include plugins by name as artifacts so that the
bundler can create ad-hoc files within the dist/ folder.
The pyscript package available in _Python_ lives in the foldersrc/stdlib/pyscript/.
All _Python_ files will be embedded automatically whenever npm run build
happens and reflected into the file.
Its _core_ responsibility is to ensure those files will be available through
the filesystem in either the _main_ thread, or any _worker_.
To cut a new release of PyScript simply
add a new release while
remembering to write a comprehensive changelog. A
GitHub action
will kick in and ensure the release is described and deployed to a URL with the
pattern: https://pyscript.net/releases/YYYY.M.v/ (year/month/version - as per
our CalVer versioning scheme).
Then, the following three separate repositories need updating:
- Documentation - Change the version.json
file in the root of the directory and then .index.html` is the latest version.
- Homepage - Ensure the version
referenced in
- PSDC - Use discord or Anaconda Slack (if you work at
Anaconda) to let the PSDC team know there's a new version, so they can update
their project templates.