code-quality

---
name: "code-quality"
description: "Python code-quality anti-patterns and review checks: exception-hierarchy correctness, singleton identity comparison, narrow exception handling, wildcard-import avoidance, magic-number naming, and dead-local removal. Use when reviewing or self-reviewing Python code for correctness and readability defects that linters and reviewers should catch."
license: "MIT"
---

# Python Code Quality

High-value Python code-quality anti-patterns to check during review or self-review.
This skill is **review-focused**: it covers correctness and readability defects that a
reviewer (or a linter) should flag, separate from testing mechanics (`pytest`) and
whole-codebase health scoring (`code-quality-scoring`).

> **Source note:** These anti-patterns are derived from CAST Highlight's Python code
> quality indicators (https://doc.casthighlight.com/), which reference **PEP 8** and the
> Python data model as primary sources. Where a rule mirrors PEP 8, the PEP is the
> authoritative source. All examples are original.

## When to Use This Skill

Use it when the task is **"is this Python code clean and correct?"** — for example:

- Reviewing a pull request and checking for the defects below.
- Self-reviewing before opening a PR.
- Configuring `ruff`/`pylint`/`mypy` rules so CI catches these automatically.
- Writing or updating a team's Python code-quality guidance.

Do **not** use it for testing mechanics (use the `pytest` skill) or for scoring a whole
codebase's health and technical debt (use the `code-quality-scoring` skill).

## Core Anti-Patterns (Summary)

Six highest-value Python anti-patterns. Each has a non-compliant/compliant example and a
"how to test" note in the reference doc:

- **Custom exceptions must derive from `Exception`** — a class meant to be raised that
  inherits from `object` fails at runtime and breaks every `except` clause.
- **Compare singletons with `is`, not `==`** — use `is`/`is not` for `None`/`True`/`False`
  (PEP 8); use `is` *only* for singletons, never for value comparison.
- **Avoid bare / overly broad `except`** — catch the narrowest type you can handle; a
  generic `except Exception` only as a last-position fallback that logs or re-raises.
- **Avoid wildcard imports** (`from x import *`) — they hide dependencies, risk silent
  name collisions, and defeat static analysis.
- **Replace magic numbers with named constants** — promote non-obvious literals to
  documented, named constants.
- **Remove unused local variables** — a dead assignment misleads readers and can hide a
  bug where a value was meant to be used.

## Best Practices

- **Gate these in CI.** Most are enforceable cheaply with `ruff` (F403/F405 wildcard,
  F841 unused locals, `E711`/`E712` singleton comparison), `pylint`, and `mypy`. Put the
  lint step in CI so review effort focuses on judgment, not mechanics.
- **Prefer specific exception handlers.** Order handlers narrowest-first; reserve a
  generic `except Exception` for a logging/re-raising last resort.
- **Name intent, not values.** A constant's *name* documents why a threshold exists; a
  bare literal documents nothing.

## Anti-Patterns (What to Avoid)

- Inheriting custom exceptions from `object` or directly from `BaseException`.
- `== None`, `== True`, or `is "some literal"`.
- Bare `except:` or `except BaseException:` that swallows control-flow signals.
- `from module import *` outside a curated `__init__.py` with explicit `__all__`.
- Unexplained numeric literals in business logic.
- Assigned-but-never-read locals left behind by a stale refactor.

## Navigation

- **[quality-antipatterns.md](references/quality-antipatterns.md)**: Full non-compliant
  vs compliant examples and a "how to test" note for each of the six anti-patterns.

## Related Skills

- **pytest** (`toolchains/python/testing/pytest`): testing mechanics — fixtures,
  parametrization, mocking. Several anti-patterns here (broad `except`, malformed
  exception classes) directly cause flaky tests.
- **code-review-standards** (`universal/process/code-review-standards`): the
  project-wide, severity-tagged review checklist that incorporates equivalents of these.
- **code-quality-scoring** (`universal/quality/code-quality-scoring`): whole-codebase
  health and technical-debt scoring, rather than individual findings.