Developer Guide
This page explains the technical and practical requirements and processes needed to contribute to PyScript.
Info
In the following instructions, we assume familiarity with git
,
GitHub, the command line and other
common development concepts, tools and practices.
For those who come from a non-Pythonic technical background (for example, you're a JavaScript developer), we will explain Python-isms as we go along so you're contributing with confidence.
If you're unsure, or encounter problems, please ask for help on our discord server.
Welcome
We are a diverse, inclusive coding community and welcome contributions from anyone irrespective of their background. If you're thinking, "but they don't mean me", then we especially mean YOU. Our diversity means you will meet folks in our community who are different to yourself. Therefore, thoughtful contributions made in good faith, and engagement with respect, care and compassion wins every time.
- If you're from a background which isn't well-represented in most geeky groups, get involved - we want to help you make a difference.
- If you're from a background which is well-represented in most geeky groups, get involved - we want your help making a difference.
- If you're worried about not being technical enough, get involved - your fresh perspective will be invaluable.
- If you need help with anything, get involved - we welcome questions asked in good faith, and will move mountains to help.
- If you're unsure where to start, get involved - we have many ways to contribute.
All contributors are expected to follow our code of conduct.
Setup
You must have recent versions of Python, node.js and npm already installed on your system.
The following steps create a working development environment for PyScript. It is through this environment that you contribute to PyScript.
Danger
The following commands work on Unix like operating systems (like MacOS or Linux). If you are a Microsoft Windows user please use the Windows Subsystem for Linux with the following instructions.
Create a virtual environment
-
A Python virtual environment is a computing "sandbox" that safely isolates your work. PyScript's development makes use of various Python based tools, so both Python and a virtual environment is needed. There are many tools to help manage these environments, but the standard way to create a virtual environment is to use this command in your terminal:
Warning
Replace
my_pyscript_dev_venv
with a meaningful name for the virtual environment, that works for you. -
A
my_pyscript_dev_venv
directory containing the virtual environment's "stuff" is created as a subdirectory of your current directory. Next, activate the virtual environment to ensure your development activities happen within the context of the sandbox: -
The prompt in your terminal will change to include the name of your virtual environment indicating the sandbox is active. To deactivate the virtual environment just type the following into your terminal:
Info
The rest of the instructions on this page assume you are working in an activated virtual environment for developing PyScript.
Prepare your repository
- Create a fork of the PyScript github repository to your own GitHub account.
-
Clone your newly forked version of the PyScript repository onto your local development machine. For example, use this command in your terminal:
Warning
In the URL for the forked PyScript repository, remember to replace
<YOUR USERNAME>
with your actual GitHub username.Tip
To help explain steps, we will use
git
commands to be typed into your terminal / command line.The equivalent of these commands could be achieved through other means (such as GitHub's desktop client). How these alternatives work is beyond the scope of this document.
-
Change into the root directory of your newly cloned
pyscript
repository: -
Add the original PyScript repository as your
upstream
to allow you to keep your own fork up-to-date with the latest changes: -
If the above fails, try this alternative:
-
Pull in the latest changes from the main
upstream
PyScript repository: -
Pyscript uses a
Makefile
to automate the most common development tasks. In your terminal, typemake
to see what it can do. You should see something like this:There is no default Makefile target right now. Try: make setup - check your environment and install the dependencies. make clean - clean up auto-generated assets. make build - build PyScript. make precommit-check - run the precommit checks (run eslint). make test-integration - run all integration tests sequentially. make fmt - format the code. make fmt-check - check the code formatting.
Install dependencies
-
To install the required software dependencies for working on PyScript, in your terminal type:
-
Updates from
npm
and thenpip
will scroll past telling you about their progress installing the required packages.Warning
The
setup
process checks the versions of Python, node and npm. If you encounter a failure at this point, it's probably because one of these pre-requisits is out of date on your system. Please update!
Check code
-
To ensure consistency of code layout we use tools to both reformat and check the code.
-
To ensure your code is formatted correctly:
-
To check your code is formatted correctly:
-
Finally, as part of the automated workflow for contributing pull requests pre-commit checks the source code. If this fails revise your PR. To run pre-commit checks locally (before creating the PR):
This may also revise your code formatting. Re-run
make precommit-check
to ensure this is the case.
Build PyScript
-
To turn the JavaScript source code found in the
pyscript.core
directory into a bundled up module ready for the browser, type:The resulting assets will be in the
pyscript.core/dist
directory.
Run the tests
-
The integration tests for PyScript are started with:
(This essentially runs the
npm run test:integration
command in the right place. This is defined in PyScript'spackage.json
file.)Tests are found in the
core/tests
directory. These are organised into three locations:python
- the Python based test suite to exercise Python code within PyScript.javascript
- JavaScript tests to exercise PyScript itself, in the browser.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.
Documentation
-
Documentation for PyScript (i.e. what you're reading right now), is found in a separate repository: https://github.com/pyscript/docs
-
The documentation's
README
file contains instructions for setting up a development environment and contributing.
Contributing
-
We have suggestions for how to contribute to PyScript. Take a read and dive in.
-
Please make sure you discuss potential contributions before you put in work. We don#t want folks to waste their time or re-invent the wheel.
-
Technical discussions happen on our discord server and in the discussions section of our GitHub repository.
-
Every Tuesday is a technical community video call, the details of which are posted onto the discord server. Face to face technical discussions happen here.
-
Every Wednesday is a non-technical community engagement call, in which we organise how to engage with, grow and nourish our community.
-
Every two weeks, on a Thursday, is a PyScript FUN call, the details of which are also posted to discord. Project show-and-tells, cool hacks, new features and a generally humorous and creative time is had by all.