Set up project

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @kraken-tech/open-source-maintainers

.github/workflows/test.yaml

@@ -0,0 +1,47 @@
+name: Python tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 5
+
+    steps:
+      - name: Clone the code
+        uses: actions/checkout@v4
+
+      - name: Set up Python versions
+        uses: actions/setup-python@v5
+        with:
+          python-version: |
+            3.12
+            3.11
+          cache: 'pip'
+          cache-dependency-path: |
+            pyproject.toml
+            requirements/*.txt
+            noxfile.py
+
+      - name: Make a virtualenv
+        run: python3 -m venv .venv
+
+      - name: Install requirements
+        run: |
+          source .venv/bin/activate
+          pip install uv==0.1.40
+          make install_python_packages
+
+      - name: Run linters
+        run: |
+          source .venv/bin/activate
+          make lint
+
+      - name: Run the tests
+        run: |
+          source .venv/bin/activate
+          nox

CONTRIBUTING.md

@@ -0,0 +1,188 @@
+# Contributing
+
+During development you will also need:
+
+- `uv` installed as a system package.
+
+## Local development
+
+When making changes please remember to update the `CHANGELOG.md`, which follows the guidelines at
+[keepachangelog]. Add your changes to the `[Unreleased]` section when you create your PR.
+
+[keepachangelog]: https://keepachangelog.com/
+
+### Installation
+
+Ensure one of the above Pythons is installed and used by the `python` executable:
+
+```sh
+python --version
+Python 3.11.9   # or any of the supported versions
+```
+
+Ensure `uv` is installed as a system package. This can be done with `pipx` or Homebrew.
+
+Then create and activate a virtual environment. If you don't have any other way of managing virtual
+environments this can be done by running:
+
+```sh
+uv venv
+source .venv/bin/activate
+```
+
+You could also use [virtualenvwrapper], [direnv] or any similar tool to help manage your virtual
+environments.
+
+Once you are in an active virtual environment run
+
+```sh
+make dev
+```
+
+This will set up your local development environment, installing all development dependencies.
+
+[virtualenvwrapper]: https://virtualenvwrapper.readthedocs.io/
+[direnv]: https://direnv.net
+
+### Testing (single Python version)
+
+To run the test suite using the Python version of your virtual environment, run:
+
+```sh
+make test
+```
+
+### Testing (all supported Python versions)
+
+To test against multiple Python (and package) versions, we need to:
+
+- Have [`nox`][nox] installed outside of the virtualenv. This is best done using `pipx`:
+
+  ```sh
+  pipx install nox
+  ```
+
+- Ensure that all supported Python versions are installed and available on your system (as e.g.
+  `python3.10`, `python3.11` etc). This can be done with `pyenv`.
+
+Then run `nox` with:
+
+```sh
+nox
+```
+
+Nox will create a separate virtual environment for each combination of Python and package versions
+defined in `noxfile.py`.
+
+To list the available sessions, run:
+
+```sh
+nox --list-sessions
+```
+
+To run the test suite in a specific Nox session, use:
+
+```sh
+nox -s $SESSION_NAME
+```
+
+[nox]: https://nox.thea.codes/en/stable/
+
+### Static analysis
+
+Run all static analysis tools with:
+
+```sh
+make lint
+```
+
+### Auto formatting
+
+Reformat code to conform with our conventions using:
+
+```sh
+make format
+```
+
+### Dependencies
+
+Package dependencies are declared in `pyproject.toml`.
+
+- _package_ dependencies in the `dependencies` array in the `[project]` section.
+- _development_ dependencies in the `dev` array in the `[project.optional-dependencies]` section.
+
+For local development, the dependencies declared in `pyproject.toml` are pinned to specific
+versions using the `requirements/development.txt` lock file.
+
+#### Adding a new dependency
+
+To install a new Python dependency add it to the appropriate section in `pyproject.toml` and then
+run:
+
+```sh
+make dev
+```
+
+This will:
+
+1. Build a new version of the `requirements/development.txt` lock file containing the newly added
+   package.
+2. Sync your installed packages with those pinned in `requirements/development.txt`.
+
+This will not change the pinned versions of any packages already in any requirements file unless
+needed by the new packages, even if there are updated versions of those packages available.
+
+Remember to commit your changed `requirements/development.txt` files alongside the changed
+`pyproject.toml`.
+
+#### Removing a dependency
+
+Removing Python dependencies works exactly the same way: edit `pyproject.toml` and then run
+`make dev`.
+
+#### Updating all Python packages
+
+To update the pinned versions of all packages simply run:
+
+```sh
+make update
+```
+
+This will update the pinned versions of every package in the `requirements/development.txt` lock
+file to the latest version which is compatible with the constraints in `pyproject.toml`.
+
+You can then run:
+
+```sh
+make dev
+```
+
+to sync your installed packages with the updated versions pinned in `requirements/development.txt`.
+
+#### Updating individual Python packages
+
+Upgrade a single development dependency with:
+
+```sh
+uv pip compile -P $PACKAGE==$VERSION pyproject.toml --extra=dev --output-file=requirements/development.txt
+```
+
+You can then run:
+
+```sh
+make dev
+```
+
+to sync your installed packages with the updated versions pinned in `requirements/development.txt`.
+
+## Versioning
+
+This project uses [SemVer] for versioning with no additional suffix after the version number. When
+it is time for a new release, run the command `make version_{type}` where `{type}` should be
+replaced with one of `major`, `minor`, `patch` depending on the type of changes in the release.
+
+The command will update the version in `pyproject.toml` and move the changes from the "Unreleased"
+section of the changelog to a versioned section and create a new "Unreleased" section for future
+improvements.
+
+[semver]: https://semver.org/

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Kraken Technologies Limited
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.