Python package template

A template repository for Python packages with pre-configured tooling:

• UV for dependency management
• GitHub Actions for CI/CD
• Semantic-release for automated versioning and PyPI publishing
• REUSE 3.3 for machine-readable license compliance
• Optional Starlight documentation site

Repository: opencitations/python-package-template

Quick start

1. Create repository from template

1. Go to python-package-template
2. Click “Use this template” > “Create a new repository”
3. Choose owner and repository name
4. Click “Create repository”

2. Clone and run setup

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO
uv run python setup.py

3. Answer setup prompts

The script asks for:

• Package name: e.g., my-awesome-lib (hyphens allowed)
• Description: brief package description
• Author name: your name
• Author email: your email
• GitHub username: your username or organization
• Include Starlight documentation?: requires Node.js/npm

The script automatically:

• Renames directories and updates all configuration files
• Runs uv sync to create the lock file (if UV is installed)
• Sets up Starlight documentation (if selected)
• Removes itself when done

4. Configure GitHub repository

Add the PyPI token for automated publishing:

1. Create a token at https://pypi.org/manage/account/token/
2. Go to repository Settings > Secrets and variables > Actions
3. Add a new secret named PYPI_TOKEN

If you included documentation:

1. Go to Settings > Pages
2. Set Source to “GitHub Actions”

5. Start developing

# Run tests
uv run pytest tests/

# Make changes and commit
git add .
git commit -m "feat: add new feature"
git push

To trigger a release, include [release] in your commit message:

git commit -m "feat: add new feature [release]"

---

Under the hood

Project structure

your-package/
├── .github/
│   └── workflows/
│       ├── tests.yml           # Runs tests on push/PR
│       ├── release.yml         # Handles versioning and PyPI publishing
│       ├── reuse.yml           # REUSE license compliance check
│       └── deploy-docs.yml     # Deploys documentation (optional)
├── LICENSES/
│   └── ISC.txt
├── src/
│   └── your_package/
│       └── __init__.py
├── tests/
│   └── test_example.py
├── docs/                       # Created if Starlight selected
├── .gitignore
├── .python-version
├── .releaserc.json
├── CHANGELOG.md
├── LICENSE.md
├── REUSE.toml
├── pyproject.toml
└── README.md

Configuration files

pyproject.toml

Project metadata and dependencies using the pyproject.toml standard:

• Build backend: hatchling
• Python version: >= 3.10
• Development dependencies in [dependency-groups]

See the UV setup guide for details on dependency management.

.releaserc.json

Configuration for semantic-release:

• Analyzes commits following the conventional commits specification
• Updates version in pyproject.toml using uv version
• Generates changelog and creates GitHub releases

Commit conventions

The template uses semantic commits for automated versioning:

Commit type	Version bump	Example
fix:	Patch (0.0.x)	fix: handle empty input
feat:	Minor (0.x.0)	feat: add export function
feat!: or BREAKING CHANGE:	Major (x.0.0)	feat!: change API

GitHub Actions workflows

tests.yml

Runs on every push and pull request to main:

• Matrix testing across Python 3.10, 3.11, 3.12, and 3.13
• Uses UV with caching for fast dependency installation
• Executes pytest

See the automated testing guide for details.

release.yml

Triggered after tests pass when the commit message contains [release]:

• Determines version bump from commit messages (feat = minor, fix = patch)
• Updates pyproject.toml and CHANGELOG.md
• Creates a GitHub release
• Publishes to PyPI

See the releases guide for details.

reuse.yml

Runs the REUSE linter on every push and pull request to verify that all files carry license and copyright information.

deploy-docs.yml

Created only if you selected Starlight documentation:

• Triggered on pushes to main that modify files in docs/
• Builds and deploys to GitHub Pages

See the Starlight setup guide for details.

Learn more

• UV setup - dependency management
• Semantic commits - commit message conventions
• GitHub Actions basics - workflow fundamentals
• Automated testing - pytest with GitHub Actions
• Releases - semantic-release and PyPI publishing
• REUSE 3.3 compliance - machine-readable licensing
• Starlight setup - documentation sites