Skip to content

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:

    python3 -m venv my_pyscript_dev_venv
    

    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:

    source my_pyscript_dev_venv/bin/activate
    
  • 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:

    deactivate
    

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:

    git clone https://github.com/<YOUR USERNAME>/pyscript
    

    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:

    cd pyscript
    
  • Add the original PyScript repository as your upstream to allow you to keep your own fork up-to-date with the latest changes:

    git remote add upstream https://github.com/pyscript/pyscript.git
    
  • If the above fails, try this alternative:

    git remote remove upstream
    git remote add upstream git@github.com:pyscript/pyscript.git
    
  • Pull in the latest changes from the main upstream PyScript repository:

    git pull upstream main
    
  • Pyscript uses a Makefile to automate the most common development tasks. In your terminal, type make 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:

    make setup
    
  • Updates from npm and then pip 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:

    make fmt
    
  • To check your code is formatted correctly:

    make fmt-check
    
  • 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):

    make precommit-check
    

    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:

    make build
    

    The resulting assets will be in the pyscript.core/dist directory.

Run the tests

  • The integration tests for PyScript are started with:

    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 core/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.

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