A practical, beginner-friendly guide to building a clean Python project with
uv, pytest, Ruff, mypy, rumdl, MkDocs, 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.
- 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.
- Browse the published guide: open the documentation site.
- Find a command or solve a problem: jump to the reference material.
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, - preview and validate a documentation site with MkDocs,
- publish documentation safely with GitHub Pages,
- automate fast checks with
pre-commithooks, - 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.
The chapters form one step-by-step path. Start from the beginning if you want to understand why each tool and file is introduced.
- Why this guide exists
- Project structure
- uv and dependency management
- pyproject.toml
- Testing with pytest
- Code quality with Ruff
- GitHub Actions and CI
- Git, commits, branches, and pull requests
- Common beginner mistakes
- Building distributions
- Static type checking with mypy
- Test coverage with pytest-cov
pre-commithooks- Markdown linting with rumdl
- Documentation site with MkDocs
- Publishing with GitHub Pages
- Project checklist
Use these guides when you need a focused answer rather than the complete learning path.
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/
│ ├── ISSUE_TEMPLATE/
│ └── workflows/
├── .pre-commit-config.yaml
├── docs/
│ ├── index.md
│ └── ...
├── src/
│ └── text_toolkit/
├── tests/
├── CONTRIBUTING.md
├── README.md
├── mkdocs.yml
├── pyproject.toml
└── uv.lock
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 syncRun the same quality checks used by CI:
uv run ruff check .
uv run ruff format --check .
uv run rumdl check .
uv run mkdocs build --strict
uv run pytest --cov=text_toolkit --cov-report=term-missing
uv run mypy
uv build --no-sourcesPreview the documentation site separately with:
uv run mkdocs serveFor explanations and expected results, use the clone and CI quickstart.
This guide is ready to be tested with students and other learners. You do not need to propose a solution or write code to help improve it.
- Share your learning experience with the learning feedback form.
- Report an incorrect instruction, broken command, or site problem with the problem report form.
- Browse existing issues before reporting the same problem again.
Small, focused improvements are welcome. Read CONTRIBUTING.md before opening a pull request.
This project is available under the MIT License.