This page explains the technical and practical requirements and processes needed to contribute to PyScript.
In the following instructions, we assume familiarity with
GitHub, the command line and other
common development concepts, tools and practices.
If you're unsure, or encounter problems, please ask for help on our discord server.
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.
The following steps create a working development environment for PyScript. It is through this environment that you contribute to PyScript.
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:
my_pyscript_dev_venvwith a meaningful name for the virtual environment, that works for you.
my_pyscript_dev_venvdirectory 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:
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:
In the URL for the forked PyScript repository, remember to replace
<YOUR USERNAME>with your actual GitHub username.
To help explain steps, we will use
gitcommands 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
Add the original PyScript repository as your
upstreamto 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
Pyscript uses a
Makefileto automate the most common development tasks. In your terminal, type
maketo 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.
To install the required software dependencies for working on PyScript, in your terminal type:
pipwill scroll past telling you about their progress installing the required packages.
setupprocess 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!
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-checkto ensure this is the case.
pyscript.coredirectory into a bundled up module ready for the browser, type:
The resulting assets will be in the
Run the tests
The integration tests for PyScript are started with:
Documentation for PyScript (i.e. what you're reading right now), is found in a separate repository: https://github.com/pyscript/docs
READMEfile contains instructions for setting up a development environment and 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.
Every Tusday is a community video call, the details of which are posted onto the discord server. Face to face technical discussions happen here.
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.