Understanding Cognitive Complexity in Python

Modern Python makes it incredibly easy to write code quickly, but much harder to keep it understandable as projects grow. This talk explores cognitive complexity: a metric focused not on what code does, but on how difficult it is for humans to read, reason about, and maintain. Through real Python examples, we will analyze how nested conditionals, branching logic, async flows, exceptions, and growing business rules silently increase the mental load required to work with a codebase. We will also discuss why traditional metrics such as cyclomatic complexity often fail to reflect actual readability, and how cognitive complexity provides a more human-centered perspective on maintainability. The talk includes practical refactoring techniques, common anti-patterns found in production Python projects, and lessons learned while building complexipy, an open source cognitive complexity analyzer for Python written in Rust, designed to provide fast local feedback and CI integration.