Hypermodern Python Projects

Episode Deep Dive

Guests Introduction and Background

Claudio Jolowicz is a seasoned Python developer and cybersecurity engineer with over a decade of experience. Originally coming from a law background, Claudio was drawn to the precision and formal systems of programming and later dived deep into Python, leveraging it for high-performance data, build, and release automation. He’s active in the Python open-source community, co-maintains the Nox test framework, and maintains the popular Hypermodern Python Cookiecutter template. Beyond software, Claudio is also a musician and composer, having toured and recorded extensively.

What to Know If You're New to Python

Here are a few key ideas that will help you get more out of this conversation if you’re newer to Python:

• Virtual Environments: Setting up a virtual environment (e.g., with venv or conda) ensures you don’t mix packages across projects.
• Package Management: Tools like Poetry and pip can install and manage dependencies automatically for you.
• Testing Basics: Even if you’re just starting, frameworks like pytest are straightforward to learn and will help you structure your projects.
• Automated Tooling: Tools such as pre-commit and black can save you time by enforcing code style and catching errors early.

Key Points and Takeaways

1. Hypermodern Python Projects (Cookiecutter Template)

Hypermodern Python is Claudio’s evolving approach to a cutting-edge, fully tooled Python project. It covers everything from packaging and testing to documentation and CI/CD. By using his Cookiecutter Hypermodern Python template, developers can bootstrap a new project with best practices baked in—think pinned dependencies, code style enforcement, automatic release notes, and more.

• Links and Tools
  • Cookiecutter Hypermodern Python Template (github.com)
  • Cookiecutter (cookiecutter.readthedocs.io)

2. Poetry for Dependency Management

Poetry is an all-in-one Python packaging and dependency management tool. It creates a predictable, locked set of packages via a poetry.lock file and handles publishing to PyPI or TestPyPI. Claudio highlighted how Poetry simplifies common problems like version conflicts, environment creation, and building distributable packages.

• Links and Tools
  • Poetry (python-poetry.org)

3. Nox for Test Automation

Nox is a test automation tool inspired by Tox but configured entirely in Python. Instead of an INI file, you use Python functions with decorators that define sessions (e.g., lint, tests, docs). Claudio helps maintain Nox, praising its clarity and flexibility.

• Links and Tools
  • Nox (github.com)

4. Pre-commit and Linting

Pre-commit hooks enforce checks (formatting, linting, security scans) on every commit, providing immediate feedback. Claudio originally hesitated to adopt pre-commit but found it valuable once he tried it. Tools like flake8, black, and iSort can all be bundled into pre-commit’s workflow, ensuring consistent code style across contributors.

• Links and Tools
  • Pre-commit (pre-commit.com)
  • Flake8 (flake8.pycqa.org)
  • Black (github.com)
  • iSort (pycqa.github.io)

5. Type Checking (mypy and Typeguard)

Python’s static type checker, mypy, helps ensure type correctness without running code, but Typeguard can add runtime checks for additional guarantees. Claudio recommends enabling type checks in CI to catch type mismatches early, especially when third-party libraries may have incomplete type hints.

• Links and Tools
  • mypy (github.com)
  • Typeguard (github.com)

6. Documentation with Sphinx and MyST

Writing good docs can be tough, but Sphinx and MyST (Markdown support) simplify it by auto-generating pages from docstrings (e.g., using autodoc) and letting you write expressive docs in Markdown. Claudio mentioned using Sphinx-click to create usage docs for command-line interfaces written with Click or Typer.

• Links and Tools
  • Sphinx (sphinx-doc.org)
  • MyST Parser (myst-parser.readthedocs.io)
  • Sphinx-click (github.com)

7. Continuous Integration with GitHub Actions

GitHub Actions can automate running tests, linters, security checks, and more across different Python versions and platforms (Linux, Windows, macOS). By pairing Nox with GitHub Actions, you can keep the automation pipeline logic in Python while leveraging GitHub’s infrastructure to execute tasks on pull requests and merges.

• Links and Tools
  • GitHub Actions (github.com)

8. Release Automation with Release Drafter

Release Drafter watches merged pull requests and auto-creates draft release notes on GitHub. With correct labeling, it can categorize new features, bug fixes, and more. Claudio emphasized how this saves time and ensures consistent release notes.

• Links and Tools
  • Release Drafter (github.com)

9. Security Audits (Bandit and Safety)

Two important checks Claudio recommends: Bandit scans Python code for common vulnerabilities and suspicious code; Safety checks your dependencies against known security databases. Both can run in pre-commit or in your CI pipeline.

• Links and Tools
  • Bandit (bandit.readthedocs.io)
  • Safety (github.com)

10. Upgrading Python Syntax with pyupgrade

If you’re dropping older Python versions, pyupgrade can automatically transform your code to use newer language features. This includes migrating to modern type hint syntax (X | None instead of Optional[X]) or rewriting set literals. Claudio described it as one of those under-the-radar but time-saving tools.

• Links and Tools
  • pyupgrade (github.com)

11. Managing Labels with GitHub Labeler

To keep your repository’s labels (like “bug” or “enhancement”) consistent, GitHub Labeler can define labels in a config file and apply them automatically or replicate them across repos. Especially helpful when multiple people contribute or if you maintain many projects.

• Links and Tools
  • GitHub Labeler (github.com)

Interesting Quotes and Stories

• Retro-Futuristic Inspiration: Claudio refers to “retrofuturistic images” from the 1920s, highlighting how quickly the Python ecosystem evolves and joking about how “hypermodern” might one day be “retro.”
• On Using Pre-commit: “I was really skeptical...I want my commits to be snappy. But once I tried it, it was so helpful!” — Claudio
• Cookiecutter Worries: Claudio noted seeing people fork an example repo with “Wikipedia references” and realized, “Oh no, I need a better way,” prompting him to build the Cookiecutter template.

Key Definitions and Terms

• Cookiecutter: A command-line utility that creates projects from project templates.
• Poetry: A tool to manage Python packaging, dependency resolution, and publishing via a single TOML-based config file.
• Nox: A Python-based session runner for testing and automation, similar in spirit to Tox but configured via Python code.
• Pre-commit: A framework for managing and maintaining multi-language pre-commit hooks to catch errors early.
• Black: An opinionated code formatter that enforces a consistent style automatically.
• Typeguard: A runtime type checker that complements static type checkers like mypy.
• Sphinx: A documentation generator that can convert docstrings (and more) into comprehensive docs.
• Release Drafter: GitHub Action that auto-drafts release notes based on pull requests.
• Bandit: A security linter that checks Python code for common security pitfalls.

Learning Resources

Here are a few courses that relate to the tools and topics from the episode. If you want to go further in your Python journey, these can help:

• Python for Absolute Beginners: A thorough introduction to coding and Python fundamentals.
• Using and Mastering Cookiecutter: Learn how to both consume and create Cookiecutter project templates.
• Rock Solid Python with Python Typing: Deepen your understanding of type hints, static typing, and frameworks leveraging type annotations.

Overall Takeaway

Hypermodern Python is a living blueprint for Python projects that want to adopt the latest and best toolchain. By using tools like Poetry for packaging, Nox for test automation, and Sphinx + MyST for documentation, you can drastically improve your project’s maintainability, consistency, and reliability. Claudio’s experience shows that adopting robust automation, strict type checking, and early security checks not only streamlines development but also fosters greater confidence in your project’s quality. Ultimately, “hypermodern” means continuing to explore and refine best practices as the Python ecosystem moves forward.