Modern Python Project Guide

A practical, beginner-friendly guide to building a clean Python project with uv, pytest, Ruff, mypy, rumdl, pyproject.toml, GitHub Actions, and a pull-request-based workflow with pre-commit hooks.

This repository is both a tutorial and a working example. It introduces each tool gradually and shows how the pieces fit together in a maintainable project.

Choose your path

• Create a new project: follow the uv quickstart.
• Run this repository locally: follow the clone and CI quickstart.
• Learn the complete workflow: start with Why This Guide Exists and follow the main learning path below.
• Find a command or solve a problem: jump to the reference material.

What you will learn

By following the guide, you will learn how to:

• structure a Python project with the src/ layout,
• manage Python and dependencies with uv,
• configure the project in pyproject.toml,
• install a package in editable mode and build distributions,
• test code with pytest,
• inspect statement and branch coverage with pytest-cov,
• lint and format code with Ruff,
• check type annotations with mypy,
• lint Markdown documentation with rumdl,
• automate fast checks with pre-commit hooks,
• run automated quality checks in GitHub Actions,
• work with branches, commits, and pull requests.

You should already know basic Python, terminal usage, Git, and GitHub. Packaging, continuous integration, and project structure are explained from the beginning.

Main learning path

The chapters form one step-by-step path. Start from the beginning if you want to understand why each tool and file is introduced.

1. Why this guide exists
2. Project structure
3. uv and dependency management
4. pyproject.toml
5. Testing with pytest
6. Code quality with Ruff
7. GitHub Actions and CI
8. Git, commits, branches, and pull requests
9. Common beginner mistakes
10. Building distributions
11. Static type checking with mypy
12. Test coverage with pytest-cov
13. pre-commit hooks
14. Markdown linting with rumdl
15. Project checklist

Reference material

Use these guides when you need a focused answer rather than the complete learning path.

Starting and adapting a project

• uv quickstart
• Clone and CI quickstart
• From script to project

Commands, concepts, and troubleshooting

• Command cheatsheet
• Glossary
• Common questions
• Troubleshooting
• Reading GitHub Actions logs

Collaboration and review

• Contributing guidelines
• Example pull request
• Reviewing Markdown changes

Project direction

• Project roadmap

The example project

The repository contains a deliberately small package in src/text_toolkit/. It keeps the domain simple so the guide can focus on project structure, tooling, tests, packaging, and CI.

modern-python-project-guide/
├── .github/
│   └── workflows/
├── .pre-commit-config.yaml
├── docs/
├── src/
│   └── text_toolkit/
├── tests/
├── CONTRIBUTING.md
├── README.md
├── pyproject.toml
└── uv.lock

Try it locally

Clone the repository and install the project environment:

git clone https://github.com/michalmaj/modern-python-project-guide.git
cd modern-python-project-guide
uv sync

Run the same quality checks used by CI:

uv run ruff check .
uv run ruff format --check .
uv run rumdl check .
uv run pytest --cov=text_toolkit --cov-report=term-missing
uv run mypy
uv build --no-sources

For explanations and expected results, use the clone and CI quickstart.

Contributing

Small, focused improvements are welcome. Read CONTRIBUTING.md before opening a pull request.

License

This project is available under the MIT License.