jprdonnelly/pyscript
1
0
Fork 0
mirror of https://github.com/pyscript/pyscript.git synced 2025-12-25 03:01:58 -05:00
Code Issues Projects Releases Wiki Activity

README update and code quality checks (#2202)

Browse Source 
* README updates.
* Ensure pre-commit black args match those in Makefile.
* Ensure pre-commit and requirements versions align, and the commands run are the same in pre-commit and Makefile.
* Update README files to reflect recent changes. Where possible, remove duplication and point to the official docs.
* Run format and pre-commit prettifier on code.
* Remove isort - it causes more trouble than is justified.
* Ensure usage examples in the README.
This commit is contained in:
Nicholas Tollervey
2024-10-02 13:48:48 +01:00
committed by GitHub
parent 6fab9a1c26
commit af06bc4826
6 changed files with 325 additions and 255 deletions
Download Patch File Download Diff File Expand all files Collapse all files

193
core/README.md
View File

@@ -1,83 +1,168 @@
# @pyscript/core
We have moved and renamed previous _core_ module as [polyscript](https://github.com/pyscript/polyscript/#readme), which is the base module used in here to build up _PyScript Next_, now hosted in this folder.
PyScript brings two Python interpreters to the browser:
## Documentation
- [MicroPython](https://micropython.org/) - 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](https://pyodide.org)) - a port of all CPython to WebAssembly.
Please read [core documentation](https://docs.pyscript.net/) to know more about this project.
These interpreters are compiled to [WebAssembly](https://webassembly.org/)
(shortened to WASM). The browser provides a secure WASM computing sandbox. Both
interpreters are compiled to web assembly with
[Emscripten](https://emscripten.org/). 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.
## Development
Our technical documentation for using this project can be
[found here](https://docs.pyscript.net/).
Clone this repository then run `npm install` within this folder.
PyScript sits on two further projects (both written in JavaScript):
Use `npm run build` to create all artifacts and _dist_ files.
1. [polyscript](https://github.com/pyscript/polyscript/#readme) - used to
bootstrap WASM compiled interpreters in a browser.
2. [coincident](https://github.com/WebReflection/coincident) - used to simplify
worker based tasks.
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.
PyScript itself is mostly written in JavaScript. The test suite for JavaScript
is in two parts: automated tests run in [playwright](https://playwright.dev/),
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](https://docs.pyscript.net/latest/user-guide/plugins/).
### Artifacts
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](https://github.com/ntoll/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](https://docs.pyscript.net/latest/developers/).
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 `<head>` of the document):
```html
<!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, 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
- **stdlib** and its content: `src/stdlib/pyscript.js` exposes, as a
JavaScript object literal, all the _Python_ content within the folder
(recursively).
- **plugins** and its content: `src/plugins.js` exposes 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_:
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
```
### Running tests
## Plugins
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:
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_.
```
make setup
```
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.
This will create a tests environment [in the root of the project, named `./env`] and install all the dependencies needed to run the tests.
The _build_ command will include plugins by name as artifacts so that the
bundler can create ad-hoc files within the `dist/` folder.
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](https://docs.npmjs.com/try-the-latest-stable-version-of-npm) 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.
## Python
To update Node run the following commands in order (most likely you'll be prompted for your user password, this is normal):
The `pyscript` package available in _Python_ lives in the folder
`src/stdlib/pyscript/`.
```
sudo npm cache clean -f
sudo npm install -g n
sudo n stable
```
All _Python_ files will be embedded automatically whenever `npm run build`
happens and reflected into the `src/stdlib/pyscript.js` file.
After the `make setup` command has completed, you can run the **automated tests** with
the following command:
Its _core_ responsibility is to ensure those files will be available through
the filesystem in either the _main_ thread, or any _worker_.
```
make test
```
## Release
(This essentially runs the `npm run test:integration` command in the right place. This is defined in PyScript's `package.json` file.)
To cut a new release of PyScript simply
[add a new release](https://github.com/pyscript/pyscript/releases) while
remembering to write a comprehensive changelog. A
[GitHub action](https://github.com/pyscript/pyscript/blob/main/.github/workflows/publish-release.yml)
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](https://calver.org/) versioning scheme).
Tests are found in the `tests` directory. These are organised into three locations:
Then, the following three separate repositories need updating:
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](https://playwright.dev/) to automate the running of the Python and JavaScript test suites. We use [uPyTest](https://github.com/ntoll/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.
- [Documentation](https://github.com/pyscript/docs) - Change the `version.json`
file in the root of the directory and then `node version-update.js`.
- [Homepage](https://github.com/pyscript/pyscript.net) - Ensure the version
referenced in `index.html` is the latest version.
- [PSDC](https://pyscript.com) - 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.