Python UV Monorepo Template

A modern Python monorepo template using uv for fast dependency management and workspace organization.

Project Structure

This project uses a uv workspace structure:

.
├── apps/
│   └── sample-app/                # Sample application package (rename this)
│       ├── src/                   # Source code
│       ├── tests/                 # Tests
│       └── pyproject.toml         # Package configuration
├── .github/
│   └── workflows/                 # GitHub Actions workflows
├── pyproject.toml                 # Workspace configuration
├── release-please-config.json     # Release Please configuration
├── .release-please-manifest.json  # Release Please manifest
└── README.md                      # This file

Getting Started

Prerequisites

• Python 3.11+
• uv package manager

Customizing the Template

Before using this template, you'll need to replace the following placeholder values:

1. Project Name: Replace sample-app throughout the codebase with your actual project name:

   • Directory name: apps/sample-app/ → apps/your-project-name/
   • Package name in apps/sample-app/pyproject.toml
   • Import statements in source code
   • Script entry points

2. Template Placeholders: Replace any remaining template placeholders:

   • {{project_name}} in configuration files
   • Author information in pyproject.toml files
   • Repository URLs and descriptions

3. Package Structure: Update the package structure in apps/sample-app/src/sample_app/ to match your project name

Installation

1. Clone the repository:

git clone <repository-url>
cd your-project-name

2. Install dependencies using uv:

uv sync

3. Install pre-commit hooks:

uv run pre-commit install

Usage

Running the Application

# Run the sample app (update command after renaming)
uv run python -m sample_app

# Or use the script entry point
uv run sample-app

Running Tests

# Run all tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=src --cov-report=html

# Run tests for a specific app
uv run pytest apps/sample-app/tests/

Code Quality

# Format code
uv run ruff format

# Lint code
uv run ruff check

# Fix linting issues automatically
uv run ruff check --fix

# Run pre-commit hooks
uv run pre-commit run --all-files

Development Workflow

1. Create a new branch for your feature/fix
2. Make your changes
3. Run tests and ensure they pass
4. Run code quality checks
5. Commit your changes (pre-commit hooks will run automatically)
6. Push your branch and create a pull request

Adding New Apps

To add a new application to the workspace:

1. Create a new directory under apps/:

mkdir apps/new-app

2. Create a pyproject.toml file following the pattern in apps/sample-app/pyproject.toml

3. Set up the source structure:

mkdir -p apps/new-app/src/new_app
mkdir -p apps/new-app/tests

4. The workspace will automatically detect the new app after running uv sync

Release Management

This project uses Release Please for automated releases. The workflow requires a PERSONAL_GITHUB_ACCESS_TOKEN secret with contents: write and pull-requests: write permissions.

Setting up the token

Prompt for your coding agent:

"Please set up the Release Please GitHub Actions secret for this repository. Go to the repository Settings → Secrets and variables → Actions and create a new repository secret named PERSONAL_GITHUB_ACCESS_TOKEN. The token needs contents: write and pull-requests: write permissions on this repository. If I already have a personal access token with these scopes, use that. Otherwise, guide me to create one at https://github.com/settings/tokens."

Conventional Commits

Use conventional commit messages for automatic version bumping:

• feat: - New features (minor version bump)
• fix: - Bug fixes (patch version bump)
• feat!: or fix!: - Breaking changes (major version bump)
• docs:, style:, refactor:, test:, chore: - No version bump

Features

• Fast dependency management with uv
• Monorepo structure for multiple related packages
• Pre-commit hooks for code quality
• Automated testing with pytest and coverage
• Code formatting with ruff
• Automated releases with Release Please
• GitHub Actions workflows for CI/CD

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass and code quality checks pass
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.