GuideBeginner
Modern Python Tooling Guide
A Python project's toolchain — which interpreter runs it, where dependencies live, who checks style and types, who builds and publishes the package — gets decided once and paid for every day after. This guide takes you through operating that toolchain with the tools the industry settled on in 2026: `uv` for interpreters, environments, and reproducible-lockfile dependency management; Ruff as the single linter and formatter that replaces flake8, isort, pyupgrade, and black; a type checker (mypy, pyright, or ty) wired into `pyproject.toml`; automation with pre-commit hooks and GitHub Actions; and packaging and publishing to PyPI with trusted publishing. The differentiator isn't the list of commands — it's the judgment: every tool is presented with its strongest argument for and its most serious objection, including when NOT to adopt it and how to evaluate an open-source project's governance health before betting your stack on it. The whole path builds a single project — `pkgpeek`, a CLI that queries PyPI — that ends up published from CI with nine verifiable deliverables and a decisions document defending every choice.
- 48
- lessons
- 6
- modules
- English · Spanish
- available in
- Yes
- certificate
- Free
- access
Outcomes
What you'll be able to do
- Install and pin any Python version with `uv python install`, without pyenv or conda, and create a project with a `pyproject.toml` that's reproducible on another machine
- Manage the full dependency cycle with `uv`: add and remove packages, group dev/prod, resolve conflicts, and reproduce an identical environment with `uv sync --frozen` or `--locked`
- Configure Ruff as a single linter and formatter, justify the chosen rule set, and migrate a black + flake8 + isort repository without changing the code's behavior
- Annotate code with modern syntax (`list[str]`, `str | None`, `Protocol`, `TypedDict`) and bring a real module to strict mode with mypy, pyright, or ty
- Distinguish precisely between static verification and runtime validation, and know why a service receiving external data needs both
- Automate the toolchain with fast pre-commit hooks and a GitHub Actions workflow that runs lint, types, and tests across several Python versions
- Update dependencies under a defined policy, audit the supply chain, and build reproducible Docker images from the lockfile
- Build and publish a package to PyPI with `uv build` and `uv publish`, semantic versioning, and CI-automated publishing via OIDC (no long-lived tokens)
- Distribute a command-line tool installable with `uvx`, using entry points in `[project.scripts]`
- Read a tool's governance health before adopting it (license, bus factor, release cadence) and defend, with your own judgment, when NOT to use this stack
Before you start
What you need to bring
It's for you if...
- Intermediate-level Python developers who already write their own functions, classes, and modules, and want to move from "I use pip because someone told me to" to defending every tool in their stack
- Teams inheriting projects with `requirements.txt`, `setup.py`, poetry, or conda who need a clear framework for deciding whether to migrate to `uv` and Ruff
- Devs tired of arguing about code style in every pull request who want to automate that layer so review time goes to what matters
- People preparing technical interviews where they're asked about environment reproducibility, gradual typing, or how to evaluate a dependency's health
- Anyone who's never published their own package to PyPI and wants to do it end to end, with CI, versioning, and secure publishing
Requirements and materials
- Intermediate-level Python: writing your own functions, classes, and modules, understanding imports, and having installed packages with pip at some point
- Basic command-line skills (navigating, running commands, environment variables) and git (cloning, committing, opening a pull request)
- A GitHub account
- No prior experience with poetry, conda, pyenv, Docker, or publishing a package is required: everything is explained from scratch
Content
The syllabus, module by module
Open any of them to see its lessons.
- 1. Introduction: the toolchain is an engineering decision
- 2. What actually breaks in a Python project
- 3. Interpreters, environments, and dependencies: the three problems
- 4. The fragmented map: pip, venv, pyenv, pipx, poetry, conda
- 5. pyproject.toml: the standard that unified everything
- 6. Installing uv and managing Python versions
- 7. Your first uv project
- 8. Mini-project: rescuing a legacy project
- 1. Introduction: reproducible or it doesn't exist
- 2. Adding and removing dependencies
- 3. The lockfile and real reproducibility
- 4. How a dependency conflict gets resolved
- 5. Extras, groups, and multi-package projects
- 6. Running tools and scripts without installing anything
- 7. When uv is NOT the answer
- 8. Mini-project: a bit-for-bit reproducible environment
- 1. Introduction: stop arguing about style in PRs
- 2. Linting and formatting: two different jobs
- 3. The tool that replaced five
- 4. Formatting with ruff format
- 5. Choosing and understanding the rules
- 6. Autofix without breaking anything
- 7. Configuring Ruff and knowing its limits
- 8. Mini-project: migrating a repo to Ruff
- 1. Introduction: the errors the linter doesn't see
- 2. What a type checker buys you and what it doesn't
- 3. Annotating real code with modern syntax
- 4. mypy, pyright, and ty: an honest comparison
- 5. Running the checker with uv
- 6. Adopting types in a legacy codebase
- 7. Static types versus runtime validation
- 8. Mini-project: bringing a module to strict mode
- 1. Introduction: making the toolchain enforce itself
- 2. Running your test suite with uv
- 3. Testing across Python versions
- 4. Pre-commit hooks that do not get in the way
- 5. GitHub Actions with uv
- 6. Updating dependencies and guarding the supply chain
- 7. Reproducible builds in Docker
- 8. Mini-project: a complete CI pipeline
- 1. Introduction: from your own project to an installable package
- 2. What packaging actually means in Python
- 3. Building your package with uv build
- 4. Versioning and changelogs
- 5. Publishing to PyPI
- 6. Distributing command-line tools
- 7. Reading a tool's governance health
- 8. Mini-project: publish your first package
Common questions
What people usually ask
No limit. It's a free guide: come in whenever you like, as often as you like.
No. Modules run from easier to harder, but you can jump to the one you need. Progress is saved per lesson.
Whatever is needed is listed under “What you need to bring”, above. If nothing is listed there, you can start from zero.
In the Club's WhatsApp group, and every two weeks there's a live with an instructor where questions get worked through.
Yes. It's issued automatically once you finish every lesson, with a verifiable code you can share on LinkedIn.
Start whenever you like
What students say
These reviews are from enrolled students who completed at least 50% of the course. We moderate reviews only on content grounds (spam, offensive language, personal data), never for being critical or negative.
No approved reviews yet.
Be the first to share your experience!