Skip to content

Development Environment

Git repository

We use GitHub for pysmo development. If you're new to git and/or GitHub, we recommend reviewing their documentation. You can clone the pysmo repository in two ways:

  1. Clone the pysmo repository directly to your desktop.
  2. Fork the repository on GitHub, and then clone it to your desktop (recommended if you plan on submitting your changes to be included in pysmo).

Clone directly

If you want to get started quickly, simply clone the pysmo git repository directly:

$ git clone https://github.com/pysmo/pysmo.git
Cloning into 'pysmo'...
$ cd pysmo

That's it! Now skip ahead to project layout.

Create your own fork

Creating your own fork allows you to push your changes back to your fork on GitHub, which in turn makes submitting a pull request straightforward. Once you forked pysmo, you can clone your repository to your desktop:

$ git clone [email protected]:<github-username>/pysmo.git
Cloning into 'pysmo'...
$ cd pysmo

Note

We used ssh to clone the repository this time round. With an ssh-agent running, this will save you from having to constantly enter your credentials when pushing changes back to GitHub.

In order to pull in changes in the upstream pysmo repository, we suggest adding it as an additional remote:

git remote add upstream https://github.com/pysmo/pysmo.git

Project layout

Inside the pysmo folder you will find a relatively simple layout. The four most important items are:

  1. src: this directory contains the pysmo source code. There are README.md files in all relevant sub-directories here to help you find your way around.
  2. docs: anything to do with documentation happens here.
  3. tests: we use this directory to hold unit tests.
  4. Makefile: Most things can be managed with this makefile.

Tip

The pysmo repository also contains files to create a development container, which performs the necessary setup tasks (all the steps below) for you automatically.

Requirements

Setting up Windows

To set up the development environment on Windows a few additional steps may be needed:

  • Install Chocolatey, a package manager for Windows which greatly simplifies installing additional dependencies correctly.
  • Once Chocolatey is installed, run the following commands (as administrator) using either PowerShell or the Command Prompt to install the dependencies:
PS > choco install make
PS > choco install awk

uv

To develop pysmo in a consistent and isolated environment, we use uv. Uv creates a Python virtual environment and manages Python packages installed in that environment. This allows you to develop and test pysmo while keeping the stable version installed separately.

Note

uv can also be used to install Python itself.

Makefile

Pysmo provides a Makefile that helps with common tasks. Running the make command without arguments (or with help) will list available commands:

$ make help

This makefile executes mostly uv commands. To view all uv commands available
run 'uv help'.

AVAILABLE COMMANDS
  build                Build distribution.
  check-uv             Check if uv is installed.
  clean                Remove existing builds.
  docs                 Build html docs.
...

To get you started run

$ make sync
...

in a shell. This will first create a Python virtual environment for development of pysmo (unless the environment already exists), then install pysmo and its dependencies.