Development Setup¶

Installing the package in development mode will allow you to make changes to the source code and have them immediately reflected in the installed package. This is useful for testing changes to the library, but is not necessary if you only want to use the library in your own projects. This guide assumes you want to develop on pax25 directly.

Note

All the commands in this guide are to be run from the repository root.

Installing the Package in Development Mode¶

Setting up for developing on pax25 directly requires a few more dependencies to be installed. For all platforms, we recommend the use of virtual environments. We will assume you've already cloned the repository using git. If you don't know how to clone a repository, we recommend following this tutorial for an introduction to git.

Linux¶

Before beginning, make sure you've installed Python 3.13. We recommend using Pyenv or uv to do this. You will also need the make command, which you have likely already installed.

You can install the package in an editable mode with all of its dependencies using:

make install

or, if using pip directly:

pip install -e '.[dev]'

macOS¶

You should be able to follow the Linux instructions, after making sure to install XCode and agreeing to its terms.

Windows¶

To install from Windows, use Powershell. Typing:

python

...Into the prompt will launch the Windows app store, prompting you to install the latest version of Python. Start a new command prompt in order to load the version with Python 3.13. This may not work if you've already installed a version of Python, in which case you'll need to create a virtual environment with the desired version. You should consider creating a virtual environment anyway, but if this is the only Python project you intend to work on, you can skip this step.

Once you've created a new Powershell window (and optionally activated your virtual environment), run this command from within the repository root:

pip install -e '.[dev]'

Building documentation¶

The dependencies for documentation are handled by make install on Linux and macOS as well, but for Windows you can also install them directly with:

pip install -e '.[docs]'

The documentation can be built and live-updated using the automated watcher. On Linux, this can be activated with:

make docs.run

...or, on Windows:

python -m mkdocs serve

This will start up a webserver with the documentation at http://127.0.0.1:8000. The documentation will be automatically rebuilt and updated as you make changes to the source files.

Sometimes this automated watcher does not automatically update reliably-- especially when generating documentation from Python code sources. Just kill the documentation server and start it back up again to force regeneration.

If you want to build the documentation without the watcher, you can do so with:

make docs

...or, on normal Windows,

python -m mkdocs build

Automated formatting¶

To keep the code style consistent and make patching easier, we use automated formatting tools. On Linux or WSL, these tools can be run in one go with:

make format

On Windows, you will need to run the formatter directly:

python -m ruff format pax25

Testing¶

To run tests, from the root directory of the repository, run:

make test.unit

Or, on Windows:

python -m pytest pax25

To perform quality checks, such as type checking and linting, run:

make test.quality

...Or, on Windows, you can run the individual commands:

python -m ruff format --check pax25
python -m mypy -p --strict pax25
python -m ruff check pax25

You can run all tests at once with:

make test

Alternatively, you may try creating a pull with your changes and letting the CI system run the tests for you. This may be simpler for most Windows users.

Publishing to PyPi¶

Publishing to PyPi should be handled automatically by GitLab's CI. Setting the variable TWINE_USERNAME to __token__ and TWINE_PASSWORD to an API key should allow you to publish via CI.

On Linux, you can install the relevant base requirements using:

make install.dist

Then, gather your PyPi credentials and run:

make publish

On Windows, you may try:

pip install -e '.[dist]'
python -m build
python -m twine upload --repository pypi dist\*