@pyscript/core
v0.6.20
Published
PyScript
Downloads
37,813
Readme
@pyscript/core
PyScript 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):
- polyscript - used to bootstrap WASM compiled interpreters in a browser.
- 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 in
tests/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.
Developer Guide
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 buildto build PyScript.- As dependencies change over time,
make updateto 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 <head> of the document):
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Pure Python PyScript tests</title>
<link rel="stylesheet" href="../../dist/core.css" />
<script type="module" src="../../dist/core.js"></script>
</head>
<body>
<script type="mpy" src="./main.py" config="./conf.toml"></script>
</body>
</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.Artifacts
There are two main artifacts in this project:
- stdlib and its content:
src/stdlib/pyscript.jsexposes, as a JavaScript object literal, all the Python content within the folder (recursively). - plugins and its content:
src/plugins.jsexposes all available dynamic imports, and is able to instrument the bundler to create files apart from the_dist/_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:
// ⚠️ This file is an artifact: DO NOT MODIFYPlugins
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.
Python
The pyscript package available in Python lives in the folder
src/stdlib/pyscript/.
All Python files will be embedded automatically whenever npm run build
happens and reflected into the src/stdlib/pyscript.js file.
Its core responsibility is to ensure those files will be available through the filesystem in either the main thread, or any worker.
Release
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.jsonfile in the root of the directory and thennode version-update.js. - Homepage - Ensure the version
referenced in
index.htmlis the latest version. - 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.