Template Checklist

• [ ] Rename module src/ab_core/template -> src/ab_core/your_package_name
• [ ] Rename tests module src/ab_core/template -> src/ab_core/your_package_name
• [ ] Update pyproject.toml: [project] section based on your package name / versioning etc.
• [ ] Update README.md references of python-package-template -> your-package-name
• [ ] Add your pypi credentials as HTTP_BASIC_PYPI_USERNAME & HTTP_BASIC_PYPI_PASSWORD repository variables / secrets respectively. These will be need for the pypi publish cd workflow to succeed.
• [ ] Remove this section

Table of Contents

• Introduction
• Quick Start
• Installation
• Usage
• Formatting and linting
• CICD

Introduction

This template repository aims to create a reusable package template which streamlines the creation and publishing of isolated python packages in auth-broker. This is aligned with the engineering vision @ auth-broker for better modularisation and reusability of code.

Quick Start

Since this is just a package, and not a service, there is no real "run" action. But you can run the tests immediately.

Here are a list of available commands via make.

Bare Metal (i.e. your machine)

1. make install - install the required dependencies.
2. make test - runs the tests.

Docker

1. make build-docker - build the docker image.
2. make run-docker - run the docker compose services.
3. make test-docker - run the tests in docker.
4. make clean-docker - remove all docker containers etc.

Installation

For Dev work on the repo

Install uv, (if you haven't already) https://docs.astral.sh/uv/getting-started/installation/#installation-methods

brew install uv

Initialise pre-commit (validates ruff on commit.)

uv run pre-commit install

Install dependencies (including dev dependencies)

uv sync

If you are adding a new dev dependency, please run:

uv add --dev {your-new-package}

Namespaces

Packages all share the same namespace ab_core. To import this package into your project:

from ab_core.template import placeholder_func

We encourage you to make your package available to all of ab via this ab_core namespace. The goal is to streamline development, POCs and overall collaboration.

Usage

Adding the dependency to your project

The library is available on PyPI. You can install it using the following command:

Using pip:

pip install python-package-template

Using UV

Note: there is currently no nice way like poetry, hence we still needd to provide the full url. https://github.com/astral-sh/uv/issues/10140

Add the dependency

uv add python-package-template

Using poetry:

Then run the following command to install the package:

poetry add python-package-template

How tos

Example Usage

# Please update this based on your package!

from ab_core.template import placeholder_func


if __name__ == "__main__":
    print("This is a placeholder: ", placeholdder_func())

Formatting and linting

We use Ruff as the formatter and linter. The pre-commit has hooks which runs checking and applies linting automatically. The CI validates the linting, ensuring main is always looking clean.

You can manually use these commands too:

1. make lint - check for linting issues.
2. make format - fix linting issues.

CICD

Publishing to PyPI

We publish to PyPI using Github releases. Steps are as follows:

1. Manually update the version in pyproject.toml file using a PR and merge to main. Use uv version --bump {patch/minor/major} to update the version.
2. Create a new release in Github with the tag name as the version number. This will trigger the publish workflow. In the Release window, type in the version number and it will prompt to create a new tag.
3. Verify the release in PyPI