pyscript/core

@pyscript/core

We have moved and renamed previous core module as polyscript, which is the base module used in here to build up PyScript Next, now hosted in this folder.

Documentation

Please read core documentation to know more about this project.

Development

Clone this repository then run npm install within this folder.

Use npm run build to create all artifacts and dist files.

Use npm run server to test locally, via the http://localhost:8080/tests/ url, smoke tests or to test manually anything you'd like to check.

Artifacts

There are two main artifacts in this project:

• stdlib and its content, where src/stdlib/pyscript.js exposes as object literal all the Python content within the folder (recursively)
• plugins and its content, where src/plugins.js exposes all available dynamic imports, able to instrument the bundler to create files a part within 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 MODIFY

Running tests

Before running the tests, we need to create a tests environment first. To do so run the following command from the root folder of the project:

make setup

This will create a tests environment [in the root of the project, named ./env] and install all the dependencies needed to run the tests.

A lot of problems related to make setup are related to node and npm being outdated. Once npm and node are updated, make setup should work. You can follow the steps on the npm documentation to update npm (the update command for Linux should work for Mac as well). Once npm has been updated you can continue to the instructions to update node below.

To update Node run the following commands in order (most likely you'll be prompted for your user password, this is normal):

sudo npm cache clean -f
sudo npm install -g n
sudo n stable

After the make setup command has completed, you can run the automated tests with the following command:

make test

(This essentially runs the npm run test:integration command in the right place. This is defined in PyScript's package.json file.)

Tests are found in the tests directory. These are organised into three locations:

1. python - the Python based test suite to exercise Python code within PyScript.
2. javascript - JavaScript tests to exercise PyScript itself, in the browser.
3. manual - containing tests to run manually in a browser, due to the complex nature of the tests.

We use Playwright to automate the running of the Python and JavaScript test suites. We use uPyTest as a test framework for the Python test suite. uPyTest is a "PyTest inspired" framework for running tests in the browser on both MicroPython and Pyodide.

The automated (Playwright) tests are specified in the tests/integration.spec.js file.

pyscript python package

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.

It is core responsibility to ensure those files will be available through the Filesystem in either the main thread, or any worker.

JS plugins

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 you can define your 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 bring plugins by name as artifact so that the bundler can create ad-hoc files within the dist/ folder.