DEV Community: Christian Ledermann

🎮 brkrs: A Brand New Take on Classic Brick-Breaking – Play It, Tweak It, Own It!

Christian Ledermann — Sun, 07 Dec 2025 20:33:55 +0000

Remember the pure, unadulterated joy (and occasional rage) of games like Breakout and Arkanoid? Dodging, bouncing, and strategically smashing bricks for that satisfying thwack?

Well, get ready for brkrs – a modern, full-featured brick-breaker that brings all that classic arcade action to a new generation, built with cutting-edge Rust 🦀 and the incredibly flexible Bevy game engine!

Want to jump straight into the action or peek under the hood? Find everything here: github.com/cleder/brkrs

brkrs isn't just another clone; it's a love letter to the genre, packed with modern physics, dynamic levels, and a secret weapon: it's entirely open-source, designed for you to play, tinker, and even contribute!

🚀 The Story: From Retro Dreams to Modern Reality

Many of us have dreamed of remaking our favorite classics. For me, that dream was to revive an old Arkanoid-style game, "YaAC 🐧", using today's best game development tools. What started as a manual journey quickly evolved into something much more: a real game that's also a living showcase of modern game dev practices.

It’s built on a philosophy of "Kaizen no michi" (改善の道) – making small, continuous improvements. This means the game is always evolving, and every change is carefully considered.

🕹️ Play It Now: Levels That Challenge, Physics That Impress

No downloads needed to get a taste of the action!

Hit up the web version and start smashing bricks here

Sorry at this time its only 2 levels (it is still early in the development process), but 70 more (lifted from YAAC) are coming soon, so stay tuned, or even better, help to make it come true ;-)

brkrs extends the classic formula with some seriously cool features:

Classic Gameplay, Modern Feel: Paddle, ball, and bricks, but with a polished, satisfying punch.
Rich Physics (Rapier3D): Experience accurate and engaging ball physics that make every bounce feel real.
Dynamic Levels: Human-readable and easy-to-modify level configurations mean endless possibilities for custom stages.
Paddle Rotation: Add a new layer of skill and strategy to your shots.
Cross-Platform Fun: Play it on your desktop or directly in your browser thanks to WebAssembly!

🛠️ Go Deeper: A Game for Builders, Too

For those who love to dive into the mechanics of their favourite games, brkrs is a treasure trove. It's not just playable; it's also a fantastic example of a well-structured Rust and Bevy project.

Want to try building it yourself? You'll need Rust, Cargo, and Git.

git clone https://github.com/cleder/brkrs.git
cd brkrs
cargo run --release

Controls: Move the paddle with your mouse, use the scroll wheel to rotate (if enabled), and hit ESC to pause.

This is your chance to not just play, but to truly tinker. Ever wanted to add a new power-up? Change how a brick explodes? Or even design your own crazy levels? brkrs makes it approachable.

🧠 Behind the Scenes: Spec-Driven Awesomeness

The game's development isn't just chaotic coding; it's built on spec-driven development (SDD). This means every feature starts with a clear, detailed plan, much like a game designer's blueprint. We even use GitHub's spec-kit to formalize these plans. It's a structured way to ensure every piece of the game works exactly as intended, minimizing bugs and maximizing fun.

And here's the kicker: this clear, step-by-step approach makes brkrs a perfect playground for experimenting with AI-assisted coding. Imagine using AI to help design a new brick type or tweak game logic – the structured specs make it surprisingly effective!

📣 Help Wanted: Your Skills Can Level Up brkrs!

While the code is solid, a great game needs more than just logic! We are actively looking for creative community members to join the effort and help turn brkrs into a visually and aurally stunning experience.

This is your chance to get your work into a real, playable, open-source game!

🎧 Sound & Music: We need satisfying sound effects (the thwack of a brick, the clink of a power-up) and engaging background music.
🎨 Art & Textures: Help us create unique brick textures, stylish paddle designs, backgrounds, and other necessary artwork.
📐 Level Design: Got an evil streak? Use the easy-to-modify level configuration files (RON) to create new, challenging, and fun level designs!
🧪 Testing & Feedback: Simply playing the game and reporting bugs or suggesting balance tweaks is incredibly valuable!

If you're a designer, artist, musician, or just a gamer with a great eye for detail, reach out or submit a Pull Request with your contributions!

🤝 Join the Fun: Learn, Contribute, Create!

brkrs is more than a game; it's a community project following "Seika no Ho" (清華の法), "the way of clear planning."

🎮️ Play the Game: Enjoy the current levels and discover new strategies.
🔭️ Explore the Code: See how modern Rust and Bevy work in a real project.
💡️ Suggest Ideas: What power-ups or brick types would YOU like to see?
🤝️ Contribute: Even small tweaks or new level designs are welcome!

Full documentation, quickstart 🚀️ guides, and developer resources are all available on brkrs.readthedocs.io.

Ready to break some bricks and make some waves in game development?

🚀 Breakout to Breakthrough: brkrs —The Rust Game Where Specs Become Code (and AI is Welcome!)

Christian Ledermann — Sun, 07 Dec 2025 19:55:11 +0000

Tired of tutorial code that stops working the moment the lesson ends? Meet brkrs—a fully playable, Arkanoid/Breakout-style game written in Rust 🦀 and built with the Bevy engine.

But this isn't just a game. It's an open-source learning playground dedicated to spec-first development and AI-assisted coding experiments.

Check out the full repository here: github.com/cleder/brkrs

As Linus Torvalds famously said: “Talk is cheap. Show me the code.” We say: "Show me the game, the spec, and the code all at once!"

💡 The Philosophy: Spec-First, Incremental, and AI-Ready

Game development, especially in a framework like Bevy, can be a steep climb. The brkrs project was born from the desire to take an old idea (an Arkanoid clone) and build it the modern way—a way that accelerates learning and embraces new tooling.

We follow a simple, yet powerful, development loop:

Spec-First: Every single feature, no matter how small, begins as a clear specification using GitHub's speckit.
Incremental PRs: The spec flows through a small, focused issue or Pull Request. This embodies the "Kaizen no michi" (改善の道) philosophy of small, positive, daily changes.
Code & Play: The result is working Rust code you can immediately see in the game.

This structured approach makes brkrs the perfect sandbox for the AI coding community:

Agentic Testing: Need a small, contained task for your coding agent? Point it at a spec and a pending issue.
AI-Assisted Feature Dev: Want to see how your favorite LLM handles adding a new brick behavior or adjusting physics? The clear specs provide the perfect prompt.
Workflow Learning: Every merged PR is a clean, documented example of how a real-world feature is implemented in Rust/Bevy.

What is Spec-Driven Development?

The core of our workflow is the use of GitHub's spec-kit. This is a framework for spec-driven development (SDD), an approach where detailed, human-readable specifications are written before any code. SDD serves as the single source of truth for the desired behavior of a feature. By providing clear inputs, outputs, and requirements upfront, it minimizes guesswork, aligns team expectations, and provides a perfect, structured input for any AI coding assistant or agent.

🕹️ Try It Now: Playable & Pluggable

You don't need to compile anything to get started!

Play the live web version right now!

The core experience extends the classic Breakout formula with:

Richer Physics (via Rapier3D) constrained to a flat 2D plane.
Paddle Rotation and customizable per-level settings.
Human-readable Levels that are easy to modify and extend using RON files.

🛠️ Quickstart: Play, Tweak, and Learn

Ready to dive into the code? You'll need Rust, Cargo, and Git.

git clone https://github.com/cleder/brkrs.git
cd brkrs
cargo run --release

Controls: Move the paddle with the mouse, use the scroll wheel to rotate, and ESC to pause.

Now, the fun begins. Want to change the gravity for Level 3? Want to create a new HyperBrick component? The entire architecture—from the Level Loader to the Brick System—is designed for easy modification.

Challenge: Following the Samurai principle of "Seika no Ho" (清華の法), "the way of clear planning," pick a small feature, write a mini-spec, and implement it.

🤝 Your Learning Path and Contribution

The goal is to make learning modern Rust/Bevy development as enjoyable as playing the game.

Here’s how you can engage:

Read a Spec: Check out the repo or wiki for a feature you'd like to see.
Pick an Issue: Find a small, contained task that aligns with a spec.
Experiment with AI: Use your favourite AI tool (e.g., GitHub Copilot, a local agent) to help draft the code for the task.
Submit a PR: Show the community how you turned a spec into working Rust code!

brkrs is more than just a Breakout clone—it’s a living textbook for best practices in modern, spec-driven, and AI-augmented software development.

🔗 Documentation

All the details you need to get started are right here:

Full Documentation
Quickstart Guide — Get up and running in 10 minutes.

Ready to break some bricks and code?

Game development with SpecKit, Rust and Bevy

Christian Ledermann — Tue, 02 Dec 2025 22:00:00 +0000

brkrs — a fun, playable brick-breaker game & learning playground

brkrs is a real, playable Breakout/Arkanoid-style game written in Rust 🦀 using the Bevy engine.
It’s also a hands-on learning project, letting you explore:

Spec-first development with GitHub speckit
Incremental feature development through issues & PRs
AI-assisted and agentic coding experiments

Every feature starts as a spec, flows through an issue or PR, and ends as working Rust code. You can play the game, explore the code, and learn modern Rust/Bevy workflows all at the same time.

Linus Torvalds said: “Talk is cheap. Show me the code.”

brkrs lets you play, tinker, and see the specs come alive in a real game.

The Story Behind brkrs

I always wanted to rewrite my old Arkanoid/Breakout-style game, YaAC 🐧, in a modern game framework.

I began by manually implementing the core gameplay foundations: reading documentation, following examples, and building a basic proof-of-concept with the essential mechanics (ball, paddle, bricks).

It quickly became clear that doing everything manually would involve a steep learning curve and a lot of time.

brkrs was born as a solution: a way to learn modern Rust game development, apply spec-first workflows, and experiment with AI-assisted coding, all while still having fun playing a real game.

Try it now

You can play a web version on GitHub Pages

Key Features

brkrs is a Breakout/Arkanoid style game implemented in Rust with the Bevy engine. It extends the classic formula with richer physics, paddle rotation, and per-level configuration.

Classic Breakout-style gameplay: paddle, ball, bricks, and levels
Levels are human-readable and easy to modify
Spec-first workflow: every feature begins as a spec and ends as working Rust code
Small, incremental PRs demonstrate the development workflow and learning path
Crate-ready and cross-platform (desktop + WebAssembly builds)
A fun, approachable way to learn Rust, Bevy, and modern coding practices

Quickstart (play & learn)

Prerequisites: Rust + Cargo + Git

git clone https://github.com/cleder/brkrs.git
cd brkrs
cargo run --release

Controls: move paddle with mouse, scroll wheel to rotate (if enabled), ESC to pause.

Play, tweak, and learn — modify levels, bricks, or mechanics to see specs turn into features.

Core Systems

Physics (Rapier3D) – 3D physics constrained to a flat play plane.
Game State – (planned) menu, playing, paused, game over, transitions.
Level Loader – RON file parsing, entity spawning, per-level gravity.
Brick System – Extensible brick behaviors via components & events.
Pause System – ESC to pause, click to resume, with window mode switching (native).

Learning Path & Contribution

This project is intended to be fun and educational. Suggested learning steps:

Read a spec in the repo or wiki
Pick a small issue to implement
Submit a PR that fulfills the spec
Experiment with AI-assisted features or gameplay tweaks

Documentation

Full documentation is available at brkrs.readthedocs.io:

Quickstart Guide — Get running in 10 minutes
Developer Guide — Set up a development environment
API Reference — Rust API documentation

Why You’ll Enjoy It

Play a real game while learning coding practices
Watch specs transform into working features
Experiment safely with Rust, Bevy, and AI-assisted workflows
Learn by doing in a hands-on, playful way

Scratching the Itch, Paying the Debt: How Community Keeps Legacy Open Source Projects Alive

Christian Ledermann — Tue, 28 Oct 2025 16:52:00 +0000

Introduction

Every developer has that one project that started as a personal solution and unexpectedly found a life of its own. For me, that was FastKML, a library I built in 2012 to “scratch my own itch.” I needed to embed maps into a website, and at the time, KML was the de facto standard for visualizing geospatial data on the web. GeoJSON existed but was still in its infancy and unsupported by OpenLayers, which was then the best tool for embedding maps.

Other Python libraries for KML existed, but most were either limited in scope, lacked Python 3 support, or didn’t meet my performance needs. Performance was crucial, so I built FastKML using lxml instead of the slower XML DOM used by many contemporaries.

As FastKML evolved, it depended on Shapely for geometry handling, an excellent library, but one that required C extensions and added installation complexity. That led to the birth of PyGeoIf, a pure Python implementation of basic geospatial objects. PyGeoIf aimed to serve as a lightweight, dependency-free substitute for Shapely when users didn’t need all of its advanced geometry operations. The API mirrored Shapely’s closely, making migration as simple as replacing

from pygeoif import ...

with

from shapely import ...

Over the years, both projects aged gracefully, but not without technical debt. They bore the marks of an earlier Python era: Python 2/3 compatibility hacks (at the very beginning Python 2.6 was still in use), missing type hints, and occasionally ambiguous function signatures.

Still, they worked. The test coverage exceeded 95%, bugs were rare, and they continued solving real problems for users long after I had moved on to other roles outside GIS. To my surprise, the packages remained popular; downloads were steady, and employers still asked about them. But I knew the code looked dated, and if I had to review it today, it wouldn’t pass.

Fast forward to 2020. The geospatial landscape had changed; GeoJSON had overtaken KML, Python’s ecosystem had matured, and I had learned a great deal about clean code and maintainability. It was time to modernize these legacy projects for the new decade.

The Need for Change

Modernization wasn’t just a matter of adding type hints or updating syntax, it was about bringing two long-lived projects in line with modern development practices. The original codebases had served well for years, but they were increasingly difficult to extend. Function signatures were ambiguous, internal logic was tangled, and adding new features often caused shotgun surgery, requiring edits across multiple unrelated files.

The Shapely API had evolved too, fully embracing PEP 8 naming conventions and adopting more expressive methods. To remain compatible, PyGeoIf needed to evolve alongside it. Meanwhile, Python itself had transformed: type hints, static analysis, and property-based testing were now standard practice rather than novelty.

Drivers of Change

The single most important motivator was the introduction of type hints in Python. Type annotations have revolutionized how Python code is written, reviewed, and maintained, enhancing readability and catching subtle bugs early through tools like mypy.
The first step was static analysis with tools like mypy, which immediately flagged legacy Python 2 compatibility hacks, ambiguous function signatures, and missing type hints. Extending the tests in tandem ensured that each refactor preserved correctness.

Beyond that, the desire for clearer APIs, more maintainable structures, and modern testing techniques pushed the modernization effort forward. I wanted code that not only worked but was readable, testable, and future-proof.

A Tale of Two Refactors

For PyGeoIf, version 0.7 had been released in 2017. Four years later, in September 2021, I published the first beta of the 1.0 series: fully type-annotated, statically checked with mypy, and tested using property-based testing with Hypothesis and improved tests with mutation testing with MutMut. By September 2022, version 1.0 was stable, and by October 2025, it had matured to version 1.5.

For FastKML, after a long silence since version 0.11 in 2015, I released version 0.12 in September 2021, incorporating long-neglected pull requests and minor improvements. A month later came FastKML 1.0 alpha 1 on PyPI. What I thought would be a quick release became an 18-iteration journey spanning three years, culminating in version 1.0 in November 2024; finally the library I had envisioned years earlier.

Reflecting on Contributions and Community Support

Over the past few years of developing PyGeoIf and FastKML, the journey has been shaped not only by personal effort but also by the support and engagement of the open-source community. One striking example of this has been Hacktoberfest contributions which consistently provided motivation and tangible progress.

These contributions may seem small individually, but collectively they have kept the momentum going. Seeing community members engage with the projects during Hacktoberfest has been a continuing source of encouragement, reminding me that every bit of contribution helps make the software more robust, maintainable, and welcoming to others.

The positive impact goes beyond the specific changes. Hacktoberfest contributions have:

Encouraged ongoing improvement by motivating incremental updates.
Highlighted the value of community participation in maintaining and modernizing open-source projects.
Reinforced a sense of shared purpose, showing that even small efforts can collectively advance a project.

This ongoing collaboration has made the development process more rewarding and sustainable, reinforcing a simple but powerful lesson: in open-source, community engagement isn’t just about code, it’s about inspiration and momentum.

Hacktoberfest contributions aren’t just code, they’re encouragement. They spark incremental improvements, highlight the value of shared effort, and inspire continued development. Seeing others invest their time and ideas in these projects has been a constant source of motivation to keep improving, testing, and refining.

Hacktoberfest and the Power of Community

Developing PyGeoIf and FastKML has been a journey of learning, coding, and refining, but it’s the community contributions, especially during Hacktoberfest, that have truly kept the momentum alive.

October has consistently brought a wave of engagement: pre-commit hooks, bug fixes, minor enhancements, and automated improvements. Each contribution, no matter how small, reinforced the sense of progress and reminded me that open-source thrives on collaboration.

Looking forward, this collaborative energy continues to fuel future features and refinements. Hacktoberfest has proven that even small contributions can make a big difference, both in the code and in the spirit of the community.

Python Code Quality Tools Beyond Linting

Christian Ledermann — Sun, 05 Oct 2025 14:07:05 +0000

The landscape of Python software quality tooling is currently defined by two contrasting forces: high-velocity convergence and deep specialization. The recent, rapid adoption of Ruff has solved the long-standing community problem of coordinating dozens of separate linters and formatters, establishing a unified, high-performance axis for standard code quality.

A second category of tools continues to operate in necessary, but isolated, silos. Tools dedicated to architectural enforcement and deep structural metrics, such as:

import-linter (Layered architecture enforcement)
tach (Dependency visualization and enforcement)
complexipy, radon, lizard (Metrics for overall and cognitive complexity)
module_coupling_metrics, lcom, and cohesion (Metrics for coupling and class cohesion)
pyscn - Python Code Quality Analyzer (Module dependencies, clone detection, complexity)

These projects address fundamental challenges of code maintainability, evolvability, and architectural debt that extend beyond the scope of fast, stylistic linting. The success of Ruff now presents the opportunity to foster a cross-tool discussion focused not just on syntax, but on structure.

Specialized quality tools are vital for long-term maintainability and risk assessment. Tools like import-linter and tach mitigate technical risk by enforcing architectural rules, preventing systemic decay, and reducing change costs. Complexity and cohesion metrics from tools such as complexipy, lcom, and cohesion quantitatively flag overly complex or highly coupled components, acting as early warning systems for technical debt. By analysing the combined outputs, risk assessment shifts to predictive modelling: integrating data from individual tools (e.g., import-linter violations, complexipy scores) creates a multi-dimensional risk score. Overlaying these results, such as identifying modules that are both low in cohesion and involved in tach-flagged dependency cycles, generates a "heat map" of technical debt. This unified approach, empirically validated against historical project data like bug frequency and commit rates can yield a predictive risk assessment. It identifies modules that are not just theoretically complex but empirically confirmed sources of instability, transforming abstract quality metrics into concrete, prioritized refactoring tasks for the riskiest codebase components.

Reasons to Connect

Bring the maintainers and core users of these diverse tools into a shared discussion.

Increasing Tool Visibility and Sustainability: Specialized tools often rely on small, dedicated contributor pools and suffer from knowledge isolation, confining technical debate to their specific GitHub repository. A broader discussion provides these projects with critical outreach, exposure to a wider user base, and a stronger pipeline of new contributors, ensuring their long-term sustainability.

Let's start the conversation on how to 'measure' maintainable, and architecturally sound Python code.
And keep Goodhart's law: "When a measure becomes a target, it ceases to be a good measure" in mind ;-)

Trusted publishing ‐ It has never been easier to publish your python packages

Christian Ledermann — Thu, 05 Dec 2024 18:52:07 +0000

Publishing Python packages used to be a daunting task, but not any more. Even better, it has become significantly more secure. Gone are the days of juggling usernames, passwords, or API tokens while relying on CLI tools. With trusted publishing, you simply provide PyPI with the details of your GitHub repository, and GitHub Actions takes care of the heavy lifting.

How to Publish Your Python Package with Trusted Publishing

I will introduce a workflow that will publish your package to TestPyPi when a tag is created (on the development branch), or to PyPi when you merge to the main branch.

Prepare Your Package for Publishing

Ensure your Python package follows PyPI’s packaging guidelines. At a minimum, you’ll need:

A ~~setup.py or~~ pyproject.toml file defining your package metadata.
Properly structured code with a clear directory layout.
A README file to showcase your project on PyPI.

For a detailed checklist, refer to the Python Packaging User Guide.

Configure GitHub Actions in Your Repository

Let's start by creating a new GitHub action .github/workflows/test-build-publish.yml.

name: test-build-publish

on: [push, pull_request]

permissions:
  contents: read

jobs:

  build-and-check-package:
    name: Build & inspect our package.
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: hynek/build-and-inspect-python-package@v2

This action will build your package and uploads the built wheel and the source distribution (SDist) as GitHub Actions artefacts.

Next, we add a step to publish to TestPyPI. This step will run whenever a tag is created, ensuring that the build from the previous step has completed successfully. Replace PROJECT_OWNER and PROJECT_NAME with the appropriate values for your repository.

  test-publish:
    if: >-
        github.event_name == 'push' &&
        github.repository == 'PROJECT_OWNER/PROJECT_NAME' &&
        startsWith(github.ref, 'refs/tags')
    needs: build-and-check-package
    name: Test publish on TestPyPI
    runs-on: ubuntu-latest
    environment: test-release
    permissions:
      id-token: write
    steps:
      - name: Download packages built by build-and-check-package
        uses: actions/download-artifact@v4
        with:
          name: Packages
          path: dist

      - name: Upload package to Test PyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          repository-url: https://test.pypi.org/legacy/

This step downloads the artefacts created during the build process and uploads them to TestPyPI for testing.

In the last step, we will upload the package to PyPI when a pull request is merged into the main branch.

  publish:
    if: >-
      github.event_name == 'push' &&
      github.repository == 'PROJECT_OWNER/PROJECT_NAME' &&
      github.ref == 'refs/heads/main'
    needs: build-and-check-package
    name: Publish to PyPI
    runs-on: ubuntu-latest
    environment: release
    permissions:
      id-token: write
    steps:
      - name: Download packages built by build-and-check-package
        uses: actions/download-artifact@v4
        with:
          name: Packages
          path: dist

      - name: Publish distribution 📦 to PyPI for push to main
        uses: pypa/gh-action-pypi-publish@release/v1

Configure GitHub Environments

To ensure that only specific tags trigger the publishing workflow and maintain control over your release process.
Create a new environment test-release by navigating to Settings -> Environments in your GitHub repository.

Set up the environment and add a deployment tag rule.

Limit which branches and tags can deploy to this environment based on rules or naming patterns.

Limit which branches and tags can deploy to this environment based on naming patterns.

Configure the target tags.

The pattern [0-9]*.[0-9]*.[0-9]* matches semantic versioning tags such as 1.2.3, 0.1.0, or 2.5.1b3, but it excludes arbitrary tags like bugfix-567 or feature-update.

Repeat this for the release environment to protect the main branch in the same way, but this time targeting the main branch.

Set Up a PyPI Project and Link Your GitHub Repository

Create an account on TestPyPI if you don’t have one.
Navigate to your account, Publishing and add a new pending publisher.
Link your GitHub repository to the PyPI project by providing its name, your GitHub username, the repository name, the workflow name (test-build-publish.yml) and the environment name (test-release).

Repeat the above on PyPI with the environment name set to release.

Test the Workflow

Now whenever you create a tag on your development branch, it will trigger a release to be uploaded to TestPyPI and merging the development branch into main will upload a release to PyPI.

What Wasn't Covered

While this guide provides an introduction to trusted publishing workflows, there are additional steps and best practices you might consider implementing. For example, setting up branch protection rules can ensure only authorized collaborators can push tags or merge to protected branches, like main or develop. You can also enforce status checks or require pull request reviews before merging, adding another layer of quality assurance.

Have a look at my python-repository-template that covers additional enhancement to this workflow, such as requiring unit and static tests to pass, checking the package with pyroma and ensuring that your tag matches the version of your package with vercheck.

Summary

If you've been holding back on sharing your work, now is the perfect time to try trusted publishing.

Introducing 'Trusted Publishers' The Python Package Index Blog highlights a more secure publishing method that does not require long-lived passwords or API tokens to be shared with external systems
Publishing to PyPI with a Trusted Publisher The official PyPI documentation to get started with using trusted publishers on PyPI.
Building and testing Python in the official GitHub docs.

'Hypermodernize' your Python Package

Christian Ledermann — Thu, 07 Dec 2023 11:28:00 +0000

In the original Hypermodern Python Blogpost, Poetry was recommended as the preferred tool.
There are quite a lot of packaging tools out there which I do not want to go into in depth, instead I recommend Anna-Lena Popkes An unbiased evaluation of environment management and packaging tools.
What has emerged as the preferred way to store packaging information is the pyproject.toml file.

Using pyproject.toml over setup.py has become a preferred choice for several reasons:

Consistent Configuration: pyproject.toml is part of the PEP 518 and PEP 517 specifications, offering a standardized and consistent way to declare build configurations and dependencies.
PEP 518 Support: pyproject.toml supports PEP 518, allowing the declaration of build system requirements, enabling better compatibility with modern build tools and providing more flexibility in the build process.
Modern Tooling: Some modern Python tools rely on pyproject.toml for project configuration. Adopting pyproject.toml aligns with these tools and facilitates a smoother integration with them.
Readability and Maintainability: The pyproject.toml format is often considered more readable and straightforward than the Python code used in setup.py. This can contribute to better maintainability, especially for more complex projects.
Standardization: As Python packaging evolves, pyproject.toml is becoming the de facto standard for configuration, supported by tools like pip and build systems like flit and poetry.

The adoption of pyproject.toml aligns with modern best practices in the Python packaging ecosystem.

Converting a setup.py base package to a pyproject.toml based one turns out to be straightforward for most use cases.
While it is easy to write a pyproject.toml there are a number of tools to convert legacy package information into this format.

setuptools-py2cfg A script for converting setup.py to setup.cfg
ini2toml which automatically translates .ini/.cfg files into TOML
validate-pyproject for automated checks on pyproject.toml powered by JSON Schema definitions
pyprojectsort enforces consistent formatting of pyproject.toml files, reducing merge request conflicts and saving time otherwise spent on manual formatting.
pyroma Rate your Python packages package friendliness.

Example

Install the required packages

pip install setuptools-py2cfg ini2toml[full]

or if you get an error no matches found: ini2toml[full]

pip install setuptools-py2cfg ini2toml configupdater tomlkit

Create a temporary cfg file

setuptools-py2cfg > tmp.cfg

and convert it into a toml file:

ini2toml --output-file=tmp.toml --profile=setup.cfg tmp.cfg

Apart from the profile setup.cfg ini2toml also has profiles to convert settings to their pyproject.toml equivalent for

.coveragerc
.isort.cfg
mypy.ini
pytest.ini ('ini_options' table)

After you converted the files, cut and paste them into a new (or existing) pyproject.toml file and validate and format them.

pip install validate-pyproject pyprojectsort pyroma

pyprojectsort
validate-pyproject pyproject.toml

Now you can delete your old setup.py file and verify that your package still builds as expected with

rm setup.py
python -m build
pyroma .

Check the dist/[my-package-name].tar.gz file to ensure it builds like before.

Adjust and tweak the settings as outlined in the user guide

Additional information

A Tale of Two Kitchens - Hypermodernizing Your Python Code Base

Christian Ledermann — Sun, 12 Nov 2023 18:58:14 +0000

What is hyper python modern python?

The idea stems from an article series with the same title by Claudio Jolowicz and is an opinionated guideline about best practices and clean code in python in the 21st century. It is a guide to modern Python tooling with a focus on simplicity and minimalism. It walks you through the creation of a complete and up-to-date Python project structure, with unit tests, static analysis, type-checking, documentation, and continuous integration and delivery.

'A tale of two kitchens'

Imagine two Kitchens Kitchen 1 is messy:

Kitchen 2 is clean and tidy:

Which kitchen do you think is better in terms of:

security,
health (including mental health) and safety,
fast delivery,
high quality of outcomes,
job satisfaction,
personal growth?

In a game of would you rather, kitchen one is the unanimous winner.

But in reality some of us work in a kitchen that looks more like this:

Why do we want to clean up our code base and make it hyper modern?

The most important thing I have done as a programmer in recent years is to aggressively pursue static code analysis. Even more valuable than the hundreds of serious bugs I have prevented with it, is the change in mindset about the way I view software reliability and code quality.
-- John Carmack

Clean consistent code minimizes context switches.
If our code looks the same everywhere we need less mental overhead to switch in between different code styles.
A 'LEAN' principle is to eliminate waste to reduce friction, this helps us with it.
The Broken Window Theory suggests that when bad behavior is not corrected immediately, it shows people that there is no downside to breaking the rules, practices or standards. If there is no negative outcome, cutting corners becomes acceptable and in time quality always decreases.
Most engineers have heard of the Boy Scout Rule: 'Always leave the code better than you found it'. It's much easier to leave the place in a better state than you found it, if you found it in good condition in the first place.

How do we start to improve the quality of our code?

Improvements over time are the result of incremental progress rather than a huge leaps forward.

The first step toward the management of disease was replacement of demon theories and humours theories by the germ theory. That very step, the beginning of hope, in itself dashed all hopes of magical solutions. It told workers that progress would be made stepwise, at great effort, and that a persistent, unremitting care would have to be paid to a discipline of cleanliness. So it is with software engineering today.
-- Frederick P. Brooks Jr. No Silver Bullet

While you could enforce cleaner code manually with with documents like styleguides, it is much easier to outsource these tasks to automated tools.

To hypermodernize your code, it's essential to maintain high coding standards and ensure that your codebase adheres to those standards consistently. There are several strategies for achieving this:

A CI system that automatically checks your code whenever you push changes to a code repository (like GitHub). By running tools that check your code against coding standards during every push, you get immediate feedback. If your code doesn't meet the standards, the CI will alert you.
Linters are tools that scan your code for style and quality issues. Running them in "daemon mode" with a file watcher means that they constantly keep an eye on your code. As you write or modify code in your development environment, the linters provide real-time feedback about any deviations from your coding standards.
Many Integrated Development Environments (IDEs) come with built-in support for various coding standards and linters. This means that, as you write code, the IDE can highlight issues and suggest improvements in real-time.
Pre-commit Hooks: Pre-commit is a tool that can be set up to enforce coding rules and standards before you commit your changes to your code repository. This ensures that you can't even check in (commit) code that doesn't meet your standards. This allows a code reviewer to focus on the architecture of a change while not wasting time with trivial style nitpicks.

These strategies help you keep your code in good shape. They ensure that your code is always checked for quality and style, whether you're writing it, pushing it to the code repository, or committing changes. This way, you catch and fix issues early, making your codebase more modern and maintainable.

You won't have much discussion about imports, this is a good point to start:

isort will sort the imports for you
absolufy-imports converts relative imports to absolute ones.
removestar replaces import * in Python files with explicit imports.
unimport: removes unused imports.

To get all your code into a consistent format the next step is to run a formatter.
I recommend black, the well-known uncompromising code formatter, which is the most popular choice.
Alternatives to black are autoflake, prettier and yapf, if you do not agree with blacks constraints.

pyupgrade and flynt are examples of tools that modify your code base from earlier python versions into the newest python syntax, rewriting all string formats into f-strings and similar things.

Ultimately we want to test our code with Flake8 and plugins to enforce a more consistent code style and to encourage best practices.
When you first introduce flake8 or a new plug-in commonly you have a lot of violations that you can silence with a #noqa comment.
When you first introduce a new flake8 plugin, you will likely have a lot of violations, which you silence with #noqa comments. Over time these comments will become obsolete because you fixed the. yesqa will automatically remove these unnecessary #noqa comments.

A more modern alternative for flake8 is Ruff: Ruff can be used to replace Flake8 (plus a variety of plugins), isort, pydocstyle, yesqa, eradicate, pyupgrade, and autoflake, all while executing tens or hundreds of times faster than any individual tool. Ruff supports over 700 lint rules and goes beyond the responsibilities of a traditional linter, instead functioning as an advanced code transformation tool capable of upgrading type annotations, rewriting class definitions, sorting imports, and more.

Security

In the landscape of hypermodern Python, security is paramount. An array of automated security scanning tools exists to fortify code against vulnerabilities. While some tools primarily focus on securing the code, others offer insights into common errors and potential risks.

Bugbear is not specifically a security tool but serves as an effective guard against common coding errors and pitfalls. It pinpoints and rectifies frequent mistakes like setting a list as a default value for a parameter and cautions against such practices, enhancing code robustness.

Bandit is a dedicated security scanner designed to target critical security concerns such as SQL injection and cross-site scripting exploits. It meticulously scrutinizes the codebase to identify and alert developers about possible security breaches or vulnerabilities, thus fortifying the code against potential exploitation.

Safety and Dependabot complement these security tools by focusing on external dependencies. Safety takes charge of examining your dependencies, ensuring they are up-to-date and free from any known vulnerabilities. Dependabot works similarly, scanning dependencies, verifying if they're current and assessing them for potential security flaws. This function is crucial as weaknesses in external dependencies can compromise the security of the entire codebase.

Together, these tools form a comprehensive security net that not only secures the code directly but also safeguards against potential risks from external dependencies, ensuring the development of secure, reliable, and robust Python code within the hypermodern framework.

You improve what you measure

“When a measure becomes a target, it ceases to be a good measure.”
-- Goodhart's Law

The adage "You improve what you measure" underscores the significance of tracking metrics for improvement. This principle is intertwined with Goodhart's Law, stating that when a measure becomes the sole focus or goal, it loses its value as an effective metric.

In the realm of codebase modernization, certain metrics can guide the process:

Test Coverage: Tools such as Coverage and Diff Cover assess how much of your code is under test coverage. While high coverage is valuable, the focus isn't just on achieving a specific percentage. It's crucial to ensure the tests are meaningful and effectively cover the essential aspects of the codebase.

Code Complexity: Metrics like McCabe, Radon, Xenon, and Lizard help evaluate the complexity of code. Lizard, in particular, is an efficient tool, capable of identifying highly complex code sections. It's considered helpful because if Lizard deems code complex, it likely needs simplification or better structuring. Cognitive Complexity, also available as a Flake8 plugin, further aids in assessing how humans perceive and interpret code, encompassing factors like decision points and recursive patterns.

Lack of Cohhesion in Methods, LCOM4 measures the relationship between methods within a class. It quantifies how much these methods are interdependent or independent from each other. This helps assess the class's cohesion, determining if methods are tightly or loosely coupled within a class, influencing code maintainability and aiding in targeted refactoring efforts for improved code quality.

These measures are essential for monitoring and understanding aspects of the codebase that might need improvement. However, it's important not to merely aim for high numbers or low complexity scores. Rather, they should act as guiding posts in the pursuit of maintainable, readable, and efficient code. These metrics help identify areas that might benefit from refactoring, thereby contributing to a more organized, maintainable, and scalable codebase. The focus remains on understanding these metrics to make informed decisions for better code quality rather than solely targeting certain percentages.

Typing

The pursuit of a hyper-modern codebase involves ensuring type correctness, an area where Mypy serves as an invaluable tool. Yet, implementing proper type annotations, especially in legacy code, can pose a significant challenge. Here's a more detailed expansion of the tools and methods to address this challenge:

Mypy and Manual Annotation:

Mypy stands as an essential static type-checking tool. Its primary function is to verify the correctness of types in your codebase. However, manually annotating types in legacy code can be laborious and time-consuming.

MonkeyType:

To alleviate the burden of manual annotation, MonkeyType offers a clever solution. It dynamically observes the types entering and leaving functions during code execution. Based on this observation, it generates a preliminary draft of type annotations. This significantly reduces the effort needed to add type hints to legacy code.

Pyre, PyRight and PyType:

Pyre from Meta, pyright from Microsoft and PyType from Google provide additional assistance. They can 'infer' types based on code flow and existing types within the code.

infer-types:

The infer-types CLI tool is another beneficial asset. This tool automatically inserts initial annotations, acting as a useful starting point for adding type hints to the codebase.

Type-Checking at Runtime with Typeguard:

Typeguard enables runtime type checking in a development environment. It is extremely helpful in ensuring that correct types are being passed around during testing, even if you do not want to activate strict runtime typechecking in your production environment.

These tools and methods collectively aid in the process of introducing type annotations, especially in the context of legacy code. They offer a spectrum of options for reducing the manual overhead and ensuring type correctness, enabling developers to gradually upgrade and modernize the codebase with better type safety without significantly disrupting existing operations.

Tests

When adopting a hyper-modern approach, it's crucial to revamp and improve the testing ecosystem. Consider the following key aspects:

Unit Tests Readability and Transition:
Enhancing unit tests contributes significantly to code readability and precision. Tools like Pytestify and Unittest2Pytest serve as effective means to convert old-style unit tests into Pytest format, aligning them with modern testing standards.
Testing Beyond Pytest:
While the Hyper Modern Python series doesn’t take a stringent stance on testing beyond Pytest, it’s vital to explore advanced testing methodologies.
Hypothesis for Property-Based Testing:
Hypothesis is a Python library facilitating property-based testing. It offers a distinct advantage by generating a wide array of input data based on specified properties or invariants within the code. The perks of Hypothesis include:
- Comprehensive Testing: Hypothesis uncovers edge cases and unexpected behaviors that conventional tests might miss.
- Reduced Test Maintenance: Tests based on properties are less prone to breaking when the code undergoes refactoring or alterations.
- Enhanced Confidence: By testing diverse inputs and edge cases, Hypothesis enhances confidence in code correctness.
- Ease of Integration: The library seamlessly integrates into existing test suites with a straightforward API.
- Simplified Debugging: In case of test failures, Hypothesis simplifies the reproduction of the failed test case, aiding in debugging.
Advantages of Hypothesis:
- Diverse Input Types Support: Hypothesis accommodates various input types, including integers, strings, lists, and dictionaries, making testing more thorough and reliable.
- Ease of Writing and Debugging: Writing tests with Hypothesis reduces the burden of generating specific inputs for tests. The hypothesis.extra.ghostwriter module automatically generates test functions, providing a smooth entry into property-based testing.

The ultimate goal is to bolster testing by moving beyond traditional practices and incorporating property-based testing methods. This not only enriches the testing suite with a broader scope but also reduces maintenance efforts, fortifying code against unexpected flaws and changes.

SchemaThesis is a powerful tool, especially when working with web APIs, and here's how it can enhance your testing capabilities:

API Testing and Schema Verification:
SchemaThesis operates in close conjunction with Hypothesis to provide a comprehensive framework for web API testing. It streamlines the generation of tests and data by aligning them with OpenAPI or GraphQL specifications. This approach ensures the thorough validation of APIs against predetermined schemas.
Service Accessibility:
One of the standout features of SchemaThesis is its flexibility as a service. It can be effortlessly utilized without necessitating deep coding or technical knowledge. This accessibility enables users without extensive programming backgrounds to take full advantage of its testing capabilities.
Automated Test Data Generation:
By interfacing with the OpenAPI or GraphQL specifications, SchemaThesis automates the creation of test scenarios and data points that comply with the defined API schema. This function significantly enhances testing robustness and ensures that the API remains compliant with its expected behavior.
Efficient Schema-Driven Testing:
Leveraging a schema-driven approach to API testing ensures that the generated tests are aligned with the expected structure, input, and output of the API. This methodology boosts efficiency and coverage in the testing phase, providing greater confidence in the API's behavior under various conditions.
User-Friendly Testing Solution:
Its simplified approach allows users to easily point the tool at an OpenAPI or GraphQL specification, enabling the generation of comprehensive test data without delving into intricate coding or complex testing procedures.

SchemaThesis offers a user-friendly and efficient way to test web APIs by utilizing predefined specifications and automatically generating test scenarios and data. This approach ensures adherence to the specified schema, allowing for robust and comprehensive testing without requiring an extensive coding background. It is also available as a service designed to handle the heavy lifting of API debugging so you can concentrate on delivering value with your API.

Quis custodiet ipsos custodes?

"Who watches the watchmen?" is a question that resonates in many contexts, and in the realm of testing code, the reliability of your tests is a critical concern. Test coverage, often seen as the gold standard, isn't a guarantee of thoroughness. That's where mutation testing tools like Mutmut come into play.

Mutmut introduces a clever approach to scrutinizing your tests. It evaluates the effectiveness of your test suite by slightly altering the code after the tests have been written. If a test fails after a minor change, that's a good sign; it means the test is robust enough to catch those changes. But if the test passes even after the code change, it indicates that the test isn't effectively detecting that alteration – this is what Mutmut terms a "surviving mutant."

While it's a powerful tool for enhancing test quality, mutation testing like Mutmut comes with a caveat: it can significantly extend the duration of your testing process. The exhaustive nature of this tool means that comprehensive testing might take a long time. Consequently, it's crucial to be selective about what you test with Mutmut to keep the testing duration manageable. Focusing on the core business logic or key functionalities is an effective strategy to use Mutmut without significantly extending the test execution time.

By selectively targeting specific areas of code or the most crucial functions, you can effectively leverage Mutmut to ensure the strength and accuracy of your tests, thus enhancing their reliability and impact without unduly extending your testing time.

Upgrades

Staying current with the latest Python versions and framework updates is crucial for maintaining code health, security and functionality. To streamline these updates, tools like PyUpgrade and Ruff are invaluable. PyUpgrade is designed to effortlessly manage Python syntax updates, ensuring that the code remains aligned with the latest Python standards.

For those working with Django, specific tools like Django-Upgrade and Django-Codemod offer essential support. These dedicated tools aid in the seamless transition of Django code from earlier versions to the most recent one. They automate the process of converting legacy Django code to adapt to the latest version's syntax and conventions.

Should a more tailored modification tool be necessary, developers can utilize LibCST (Concrete Syntax Tree) to craft their own code transformation tool. LibCST offers a flexible approach, enabling users to build custom tools aligned with their unique requirements, allowing for modifications in code structure or style.

These tools collectively facilitate the efficient and timely upgrading of Python codebases, allowing for smoother transitions to new language features, the latest syntax standards, and ensuring compatibility with the most recent frameworks and libraries. This keeps the codebase relevant and optimally aligned with the current Python ecosystem.

Refactoring as a Service.

Refactoring is a vital aspect of maintaining code health and quality. Sourcery is a fantastic tool that helps with small-scale refactorings by automatically suggesting and implementing code improvements. It offers an automated approach to identify and carry out minor code alterations that can enhance readability, reduce duplication, or improve overall code structure.

On the other hand, SonarCloud is a comprehensive code analysis service designed to identify and rectify issues related to code quality, security, and maintainability. It continuously scans and analyzes code repositories, ensuring adherence to coding standards, finding potential bugs, and offering comprehensive insights into code health. This platform flags problematic areas in the code, allowing developers to refactor and improve code quality effectively.

CodeScene is another tool to manage technical debt. It helps you to identify the most critical areas and plan goals to reduce technical debt in each hotspot.

Sourcery SonarCloud and CodeScene serve as powerful assistants in enhancing code quality and readability. Sourcery focuses on specific, smaller-scale refactoring tasks, while SonarCloud provides a broader perspective by analyzing codebases for overall health, security, and maintainability, guiding developers in making comprehensive improvements across their projects.

Refactoring

When refactoring code, it is important to remember that "perfect is the opposite of done". Refactoring is an iterative process, and there may be times where code is not perfect, but is still useful and can be improved upon over time.

Refactoring is about refining code to be maintainable, extensible, and modular by recognizing patterns and reducing redundancy. It involves adhering to principles like the SOLID principles:

Single Responsibility Principle: Each module/class should have a single responsibility.
Open-Closed Principle: Classes/modules should be open for extension but closed for modification.
Liskov Substitution Principle: Subtypes should be replaceable with their base types without altering the program's correctness.
Interface Segregation Principle: Many client-specific interfaces are better than a single general-purpose interface.
Dependency Inversion Principle: Depend on abstractions, not on concrete implementations.

The CUPID principles (from the lightning talk "Why Every Single SOLID Principle is Wrong" take a descriptive rather than a prescriptive approach.

The five CUPID properties are:

Composable: plays well with others
Unix philosophy: does one thing well
Predictable: does what you expect
Idiomatic: feels natural
Domain-based: the solution domain models the problem domain in language and structure

These principles guide better code creation, emphasizing maintainability and extensibility over perfection. They are guidelines, good advice, rather than hard rules, not natural laws like Isaac Newtons Philosophiæ Naturalis Principia Mathematica.

In refactoring, remember that perfection can impede progress and "perfect is the opposite of done". Refactoring is an iterative process that leads to better code incrementally. Code doesn’t need to be perfect but useful. The goal is maintainability and improvement over time rather than perfection at once.
It is important to focus on creating code that is maintainable and extensible, rather than striving for perfection.

Examples of "Hypermodernization"

“Talk is cheap. Show me the code.”
― Linus Torvalds

While most of my 'hypermodernizing' was done on proprietary code, there is a good example in pygeoif, which was brought up to the standard 10 years after the first version was released. The diff is not very helpful, almost every line was touched in the end, but you can compare the version 0.6 to the current implementation. FastKML is still actively in the process of modernizing and refactoring.

EuroPython 2022, PyCon Ireland Dublin 2022, Limerick 2023 Presentations

Slides
A Tale of Two Kitchens Hypermodernizing Your Codebase.

EuroPython July 2022 Recording

PyCon Ireland November 2022 Recording

Love Your Representation

Christian Ledermann — Sat, 04 Nov 2023 21:39:15 +0000

Embrace the power of __repr__

Usage

There are two ways out that Python provides us with, out of the box, to convert an object into a string: __str__ and __repr__.
__str__ gets all the love, __repr__ is a bit more obscure.

>>> class Simple:
...     def __init__(self, name):
...             self.name = name
...     def __str__(self):
...             return f'My name is {self.name}'
...     def __repr__(self):
...             return f'Simple({self.name})'
... 
>>> simple = Simple('Christian')

`__str__`	`__repr__`
`print(simple)`	`repr(simple)`
`'%s' % simple`	`'%r' % simple`
`'{}'.format(simple)`	`'{!r}'.format(simple)`
`f'{simple}'`	`f'{simple!r}'`
Output
`'My name is Christian'`	`'Simple(Christian)'`

F-Srings in newer Python versions also provide a nice shortcut: f'{simple=}' will produce 'simple=Simple(Christian)'.

What is the difference anyway?

__str__ is meant to define the "informal" or user-friendly string representation of an object. It's used when you want to provide a human-readable description of the object.
__repr__ is meant for the "formal" or unambiguous string representation of an object. It's used for debugging, development, and to represent the object in a way that could be used to recreate the same object.

Think of a Python object as a toy. When we want to describe this toy to someone, we can use two ways:

__str__ is like giving a friendly and simple description of the toy. It's what we tell our friends when we want them to know what the toy looks like or what it does. It's like saying, "This toy is colourful and fun to play with!"

__repr__ is like giving a very detailed and technical description of the toy. It's what we tell someone who needs to know all the nitty-gritty details about the toy. A look under the hood.

Why should I care about implementing a `repr`?

Implementing a __repr__ method for your Python classes can be valuable for several reasons, particularly in debugging, development, and logging:

Debugging: When you're debugging your code, having a well-defined __repr__ method can provide you with a clear and informative representation of an object's state. This can help you quickly identify issues and understand the data stored in an object, making debugging more efficient.
Development: During development, you may frequently need to inspect the contents of objects for testing and problem-solving. A useful __repr__ method can simplify this process by displaying relevant object details, helping you develop and fine-tune your code more effectively.
Logging: When you log information about your program's execution, having a good __repr__ method can be invaluable. Logging the string representation of objects can help you track the program's state, record important data, and diagnose issues when they occur.
Readable Output: A well-implemented __repr__ method can provide human-readable output, making it easier to understand the state of objects. This is especially useful when you need to inspect the program's behavior during development or debugging.
Interactive Environments: In interactive Python environments like Jupyter notebooks, IPython, and REPL, the __repr__ method is used automatically when you evaluate an object. This makes it convenient to understand and explore the object's content without explicitly calling the __repr__ method.
Documentation and Exploration: When working with libraries and frameworks, having a descriptive __repr__ can enhance the documentation and help others understand how to use your classes effectively. It also makes it easier for colleagues or users to explore and experiment with your code.

Implementing a meaningful __repr__ method is a good practice because it provides a clear and informative way to represent your objects, making your code more maintainable, debuggable, and user-friendly. It's especially useful when you need to interact with and understand objects during the development and debugging process.

Examples From The Python Standard Library

An example is the datetime module.

>>> import datetime
>>> now = datetime.datetime.utcnow()
>>> now
datetime.datetime(2023, 11, 3, 18, 55, 45, 862092)
>>>

Data classes provide a nice implementation.

>>> from dataclasses import dataclass
>>> 
>>> @dataclass
... class InventoryItem:
...     """Class for keeping track of an item in inventory."""
...     name: str
...     unit_price: float
...     quantity_on_hand: int = 0
... 
>>> ii = InventoryItem('python', 897)
>>> ii
InventoryItem(name='python', unit_price=897, quantity_on_hand=0)

Even in the Python Standard Library the implementation of __repr__ may vary.

>>> from enum import Enum
>>> 
>>> class DataType(Enum):
...     string = "string"
...     int_ = "int"
...     uint = "uint"
...     short = "short"
... 
>>> ui = DataType('uint')
>>> ui
<DataType.uint: 'uint'>

This is not undisputed and can be overridden (this is copied from: 3.12.0 Documentation » The Python Standard Library » Data Types » enum — Support for enumerations)

>>> from enum import auto
>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __repr__(self):
...         cls_name = self.__class__.__name__
...         return f'{cls_name}.{self.name}'
... 
>>> OtherStyle.ALTERNATE
OtherStyle.ALTERNATE

Example

fastkml is a library to work with <KML /> a geospatial <XML /> format.

>>> from fastkml.gx import Track
>>> doc = """
...     <gx:Track xmlns:gx="http://www.google.com/kml/ext/2.2"
...         xmlns:kml="http://www.opengis.net/kml/2.2">
...         <kml:when>2010-05-28T02:02:09Z</kml:when>
...         <kml:when>2010-05-28T02:02:56Z</kml:when>
...         <kml:when />
...         <gx:angles>45.54 66.23 77.0</gx:angles>
...         <gx:angles />
...         <gx:angles>75.54 86.23 17.0</gx:angles>
...         <gx:coord>-122.20 37.37 156.00</gx:coord>
...         <gx:coord>-122.20 37.37 152.00</gx:coord>
...         <gx:coord>-122.20 37.37 147.00</gx:coord>
...     </gx:Track>
... """

Out of the box, python provides an unambiguous representation.

>>> track = Track.from_string(doc, ns="")
<fastkml.gx.Track object at 0x7f3d3b5fa230>
>>>

That is not much help.

The __init__ method of this class is defined as:

class Track(_Geometry):
    """A track describes how an object moves through the world over a given time period."""
    def __init__(
        self,
        *,
        ns: Optional[str] = None,
        id: Optional[str] = None,
        target_id: Optional[str] = None,
        extrude: Optional[bool] = False,
        tessellate: Optional[bool] = False,
        altitude_mode: Optional[AltitudeMode] = None,
        track_items: Optional[Sequence[TrackItem]] = None,
    ) -> None:

When we define the __repr__ like

    def __repr__(self) -> str:
        return (
            f"{self.__class__.__name__}("
            f"ns={self.ns!r}, "
            f"id={self.id!r}, "
            f"target_id={self.target_id!r}, "
            f"extrude={self.extrude!r}, "
            f"tessellate={self.tessellate!r}, "
            f"altitude_mode={self.altitude_mode}, "
            f"track_items={self.track_items!r}"
            ")"
        )

The representation looks much better

>>> track = Track.from_string(doc, ns="")
>>> track
Track(
    ns="http://www.google.com/kml/ext/2.2",
    id="",
    target_id="",
    extrude=None,
    tessellate=None,
    altitude_mode=None,
    track_items=[
        TrackItem(
            when=datetime.datetime(2010, 5, 28, 2, 2, 9, tzinfo=tzutc()),
            coord=Point(-122.2, 37.37, 156.0),
            angle=Angle(heading=45.54, tilt=66.23, roll=77.0),
        ),
        TrackItem(
            when=datetime.datetime(2010, 5, 28, 2, 2, 56, tzinfo=tzutc()),
            coord=Point(-122.2, 37.37, 152.0),
            angle=None,
        ),
        TrackItem(
            when=None,
            coord=Point(-122.2, 37.37, 147.0),
            angle=Angle(heading=75.54, tilt=86.23, roll=17.0),
        ),
    ],
)

The pattern is simple, construct a string out of the objects attributes for each parameter in the __init__ method.

This could be the end. Just add a __repr__ that mirrors the __init_ signature of the class. There is nothing much to it, easily done and it will save you time and effort in the future when you have to debug your code or figure out what caused a bug from the log files.

Implementing this pattern to your existing code looks like a lot of tedious, error-prone, ungrateful, repetitive, manual labour. It is a major chore when your project has dozens of classes, let alone hundreds or thousands.

Being a developer, I’m too lazy to spend 8 hours mindlessly performing a function, but not too lazy to spend 16 hours automating it.
Timothy Crosley

crepr

It is pronounced "kraypr" (/kɹeɪpr/) like Americans and Australians pronounce crêpe, the French pancake.

A Python script that takes a file name as a command-line argument, imports the specified module, and then prints a __repr__ method for each class defined in the module. It creates the __repr__ by inspecting the keyword arguments of the __init__ method of the class.

Example

Given the file tests/classes/kw_only_test.py with the contents:

class KwOnly:
    def __init__(self, name: str, *, age: int) -> None:
        self.name = name
        self.age = age

The command:

❯ crepr tests/kw_only_test.py

produces

class KwOnly:
    def __init__(self, name: str, *, age: int) -> None:
        self.name = name
        self.age = age

    def __repr__(self) -> str:
        """Create a string (c)representation for KwOnly."""
        return (f'{self.__class__.__module__}.{self.__class__.__name__}('
            f'name={self.name!r}, '
            f'age={self.age!r}, '
        ')')

The repr() of an instance of this class will be:

>>> from tests.classes.kw_only_test import KwOnly
>>> kwo = KwOnly('Christian', age=25)
>>> kwo
tests.classes.kw_only_test.KwOnly(name='Christian', age=25, )

It is Unix-ish, does just one thing: it prints the modified file to StdOut so you can redirect or pipe the output.

The code is tidy and clean, follows best practises, is fully tested and type checked as a hypermodern package should be.

It is still in its infancy, but you can install it from PyPI.

Summary

Implementing a __repr__ method is a best practice as it improves the debugging and development process, enhances code readability, and aids in effective communication of your object's structure and state. Do not forget to include the !r qualifier when logging your objects.

Give your representations some love.

❤️.__repr__(self) -> str:

Type Annotate an existing Python Django Codebase with MonkeyType

Christian Ledermann — Tue, 21 Jul 2020 17:50:10 +0000

Why Add Types?

There has been quite a buzz around type annotations in the recent past, so you may ask yourself if type checking is something you should do. This article is not a general introduction to type annotations and type checks, I recommend Hypermodern Python: Typing to get an overview of the background.

In a nutshell citing the above article:
"Type annotations are a way to annotate functions and variables with types. Combined with tooling that understands them, they can make your programs easier to understand, debug, and maintain. A static type checker can use type annotations and type inference to verify the type correctness of your program without executing it, helping you discover many bugs that would otherwise go unnoticed." or Dropbox puts it like this: "If you aren’t using type checking in your large-scale Python project, now is a good time to get started — nobody who has made the jump I’ve talked to has regretted it. It really makes Python a much better language for large projects."

In addition to the above the tooling around type annotations is growing continuously and helps to keep your code DRY.
There are libraries like Desert or Typical to help with data validation, Typeguard or strongtyping to check types at runtime, sphinx-autodoc-typehints to help build documentation, Typer to build CLIs, FastAPI a web framework for building APIs, and even transpilers to compile your python code with Mypy to Python C or Rust.

For a more complete list please refer to Awesome Python Typing

Do Not Let Legacy Code Become Technical Debt

As Dropbox describes in Our journey to type checking 4 million lines of Python it is quite daunting to type annotate an existing codebase. The article describes in depth how you can approach gradual improvements with type annotations to your codebase.

Enter MonkeyType

But why do I have to write my annotations manually? After all Python knows what type a variable is at runtime. The folks at Instagram thought the same and created MonkeyType. A similar projects is PyAnnotate created by Dropbox. Pytype generates files of inferred type information, located by default in .pytype/pyi. Pyre has a powerful feature for migrating codebases to a typed format. The infer command-line option ingests a file or directory, makes educated guesses about the types used, and applies the annotations to the files.

MonkeyType collects runtime types of function arguments and return values, and can automatically generate stub files or even add draft type annotations directly to your Python code based on the types collected at runtime.

Have a look at the Introduction to MonkeyType for an overview of its functionality or listen to the MonkeyType podcast.

Setup MonkeyType For a Django Project With PyTest

While you can run MonkeyType in a production like environment and get real world data on how you code is called, the most common use case is probably to get this data out of test runs. If you do not use pytest with django Testing Your Django App With Pytest should get you started.

Install the required dependencies by creating a file monkeytype.txt with the contents

mypy
mypy-extensions
MonkeyType
pytest-monkeytype
django-stubs
djangorestframework-stubs

and install the dependencies with pip install -r monkeytype.txt As of writing this pytest-monkeytype needs MonkeyType==19.11.2, this is fixed in this Pull Request

Configure mypy with mypy.ini e.g.

[mypy]
disallow_any_generics = True
disallow_untyped_calls = True
disallow_untyped_defs = True
disallow_untyped_decorators = True
ignore_errors = False
ignore_missing_imports = True
implicit_reexport = False
strict_optional = True
strict_equality = True
no_implicit_optional = True
warn_unused_ignores = True
warn_redundant_casts = True
warn_unused_configs = True
warn_unreachable = True
warn_no_return = True
warn_return_any = True

plugins =
    mypy_django_plugin.main,
    mypy_drf_plugin.main

[mypy.plugins.django-stubs]
django_settings_module = "test_settings"

[mypy-drfdapc.test_permissions]
ignore_errors = True

Create a monkeytype_config.py file:

# Standard Library
import os
from contextlib import contextmanager
from typing import Iterator

# 3rd-party
from monkeytype.config import DefaultConfig


class MonkeyConfig(DefaultConfig):
    @contextmanager
    def cli_context(self, command: str) -> Iterator[None]:
        os.environ.setdefault("DJANGO_SETTINGS_MODULE", "test_settings")
        import django

        django.setup()
        yield


CONFIG = MonkeyConfig()

Change the DJANGO_SETTINGS_MODULE to the one that is used in tests.
Now you can run your tests with pytest --monkeytype-output=./monkeytype.sqlite3 and export MT_DB_PATH=./monkeytype.sqlite3 on Bash, or setenv MT_DB_PATH ./monkeytype.sqlite3 on C Shell.

Check which modules MonkeyType has collected infomation for with monkeytype list-modules.

drfdapc$ monkeytype list-modules
drfdapc.permissions
drfdapc.test_permissions

You can then use the monkeytype stub some.module command to generate a stub file for a module, or apply the type annotations directly to your code with monkeytype apply some.module.

drfdapc$ monkeytype stub drfdapc.permissions
from django.core.handlers.wsgi import WSGIRequest
from unittest.mock import Mock


def allow_all(*args, **kwargs) -> bool: ...


def allow_authenticated(request: WSGIRequest, *args, **kwargs) -> bool: ...


def allow_authorized_key(
    request: WSGIRequest,
    view: Mock,
    *args,
    **kwargs
) -> bool: ...


def allow_staff(request: WSGIRequest, *args, **kwargs) -> bool: ...


def allow_superuser(request: WSGIRequest, *args, **kwargs) -> bool: ...


def deny_all(*args, **kwargs) -> bool: ...


class DABasePermission:
    def has_object_permission(
        self,
        request: WSGIRequest,
        view: None,
        obj: Mock
    ) -> bool: ...
    def has_permission(self, request: WSGIRequest, view: None) -> bool: ...


class DACrudBasePermission:
    def has_object_permission(
        self,
        request: WSGIRequest,
        view: None,
        obj: Mock
    ) -> bool: ...
    def has_permission(self, request: WSGIRequest, view: None) -> bool: ...


class DARWBasePermission:
    def has_object_permission(
        self,
        request: WSGIRequest,
        view: None,
        obj: Mock
    ) -> bool: ...
    def has_permission(self, request: WSGIRequest, view: None) -> bool: ...

Checking the annotations with mypy shows that there is still some work to do and it demonstrates nicely which errors mypy catches.

drfdapc$ mypy drfdapc/permissions.py
...
drfdapc/permissions.py:71: error: Function is missing a type annotation for one or more arguments
drfdapc/permissions.py:86: error: Untyped decorator makes function "allow_superuser" untyped
...
drfdapc/permissions.py:162: error: Argument 2 of "has_permission" is incompatible with supertype "BasePermission"; supertype defines the argument type as "View"
drfdapc/permissions.py:162: note: This violates the Liskov substitution principle
drfdapc/permissions.py:162: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#incompatible-overrides
...
Found 17 errors in 1 file (checked 1 source file)

Remember that MonkeyType’s annotations are an informative first draft, to be checked and corrected by a developer.
In the above example we never pass a view, all objects are mocked and WSGIRequest is too specific, so we need to adjust this. Also run black and isort on this file to have a nicely formatted code. You can see the workflow in this pull request

Start with small modules that have few (or even better no) dependencies on other parts of your code, apply the types, check the correctness of the annotations with mypy some/module.py fix the typing information, and move on to the next module.

Little Helpers

You will want to keep your type information clean, readable and consistent. To achieve this there are some plugins for flake8.

flake8-annotations-complexity reports on too complex, hard to read type annotations. Complex type annotations often means bad annotation usage, wrong code decomposition or improper data structure choice.

flake8-annotations-coverage reports on files with a lot of code without type annotations. This is mostly useful when you add type annotations to existing large codebase and want to know if new code in annotated modules is annotated.

flake8-type-annotations is used to validate type annotations syntax as it was originally proposed

flake8-annotations detects the absence of function annotations.
What this won't do: Check variable annotations respect stub files, or replace mypy.

DEV Community: Christian Ledermann

🎮 *brkrs*: A Brand New Take on Classic Brick-Breaking – Play It, Tweak It, Own It!

🚀 The Story: From Retro Dreams to Modern Reality

🕹️ Play It Now: Levels That Challenge, Physics That Impress

🛠️ Go Deeper: A Game for Builders, Too

🧠 Behind the Scenes: Spec-Driven Awesomeness

📣 Help Wanted: Your Skills Can Level Up brkrs!

🤝 Join the Fun: Learn, Contribute, Create!

Ready to break some bricks and make some waves in game development?

🚀 Breakout to Breakthrough: brkrs —The Rust Game Where Specs Become Code (and AI is Welcome!)

💡 The Philosophy: Spec-First, Incremental, and AI-Ready

What is Spec-Driven Development?

🕹️ Try It Now: Playable & Pluggable

🛠️ Quickstart: Play, Tweak, and Learn

🤝 Your Learning Path and Contribution

🔗 Documentation

Ready to break some bricks and code?

Game development with SpecKit, Rust and Bevy

brkrs — a fun, playable brick-breaker game & learning playground

The Story Behind brkrs

Try it now

Key Features

Quickstart (play & learn)

Core Systems

Learning Path & Contribution

Documentation

Why You’ll Enjoy It

Scratching the Itch, Paying the Debt: How Community Keeps Legacy Open Source Projects Alive

Introduction

The Need for Change

Drivers of Change

A Tale of Two Refactors

Reflecting on Contributions and Community Support

Hacktoberfest and the Power of Community

Python Code Quality Tools Beyond Linting

Reasons to Connect

Trusted publishing ‐ It has never been easier to publish your python packages

How to Publish Your Python Package with Trusted Publishing

Prepare Your Package for Publishing

Configure GitHub Actions in Your Repository

Configure GitHub Environments

Set Up a PyPI Project and Link Your GitHub Repository

Test the Workflow

What Wasn't Covered

Summary

'Hypermodernize' your Python Package

Example

Additional information

A Tale of Two Kitchens - Hypermodernizing Your Python Code Base

What is hyper python modern python?

'A tale of two kitchens'

Why do we want to clean up our code base and make it hyper modern?

How do we start to improve the quality of our code?

Security

You improve what you measure

Typing

Tests

Quis custodiet ipsos custodes?

Upgrades

Refactoring as a Service.

Refactoring

Examples of "Hypermodernization"

Links

EuroPython 2022, PyCon Ireland Dublin 2022, Limerick 2023 Presentations

Love Your Representation

Usage

Why should I care about implementing a __repr__?

Examples From The Python Standard Library

Example

crepr

Example

Summary

Type Annotate an existing Python Django Codebase with MonkeyType

Why Add Types?

Do Not Let Legacy Code Become Technical Debt

Enter MonkeyType

Setup MonkeyType For a Django Project With PyTest

Little Helpers

🎮 brkrs: A Brand New Take on Classic Brick-Breaking – Play It, Tweak It, Own It!

Why should I care about implementing a `repr`?