Developer’s Guide¶

Note

In this context, “developer” refers to anyone who wants to set up pylinac locally, contribute to the code base, create a fork for personal use, or otherwise modify the code. A “contributor” is a looser definition and could refer to someone who reports bugs, requests features, etc. A contributor is not necessarily a developer.

This section will describe how to set up pylinac locally for development, either for contribution to pylinac itself or for use as a customized version in your clinic.

Important

This assumes a basic understanding of Python, git, the command line, and virtual environments.

If you’re new to git, see the git guide.

Prerequisites¶

You should have a basic understanding of and install the following:

Git.
An IDE or text editor of your choice (e.g., VSCode, PyCharm, etc.)
uv - a Python tool for managing virtual environments and dependencies.

Important

Install uv globally via the Standalone installer. Do not use the uv pypi package. This will let you use uv outside a single virtual environment, install other versions of Python, etc.

nox - A scripting and test automation tool. You do not need to explicitly install this as it is a developer dependency installed automatically when setting up your virtual environment, but it is helpful to know what it is as it is used often for various tasks in pylinac and is an all-around extremely useful tool for Python development.

Setting Up Your Development Environment¶

Fork¶

Fork the pylinac repository and clone it to your local machine. You may use the command line or a GUI tool like GitHub Desktop, GitKraken, or your IDE’s built-in git support. I would recommend using a remote VCS like GitHub, Gitlab, etc which allows you to easily fork repositories as well as keep your fork safe (vs local-only git repositories).

Python¶

Python is an obvious prerequisite, but note that uv can install Python itself and manage multiple versions of it! This is extremely helpful to, say, test pylinac against multiple versions of Python.

# install Python 3.11
uv python install 3.11

# or install older versions of Python
uv python install 3.10

Virtual Environment¶

Set up a virtual environment and install the required dependencies using uv:

# in your cloned directory of pylinac
uv sync

Documentation¶

To render documentation locally run:

Tip

You don’t need to install the documentation dependencies as this is handled for you by nox which manages its own isolated virtual environments.

uv run nox -s serve_docs

This will build the documentation, start a local web server, and open the documentation in your default web browser. Any changes you make to the documentation files will be automatically reflected in the browser momentarily.

Running Tests¶

Warning

This section is still under construction. There is a PR open to allow for running public tests, but it is not yet merged.

To run tests you can directly use pytest, nox, or uv (they all use pytest under the hood, but can provide better isolation) to run the tests.

pytest

# run all tests
pytest

# run a specific test file
pytest tests_basic/test_starshot.py

nox

# run all tests
nox -s run_tests

# run all tests
uv run pytest

Building Wheels¶

Note

This section only applies to internal developers or developers who want to publish a fork to PyPI

To build a wheel:

uv run nox -s build_wheel

To upload your wheel to PyPI, you can use the following command:

uv run nox -s upload_wheel