Python Packaging
debt(d7/e5/b5/t5)
Closest to 'only careful code review or runtime testing' (d7) — detection_hints.automated is 'no'; missing lock files or unpinned versions in requirements.txt aren't flagged by standard linters, only noticed when CI/prod installs drift or during review of pyproject.toml/requirements.txt.
Closest to 'touches multiple files / significant refactor in one component' (e5) — quick_fix says migrate to pyproject.toml replacing setup.py/setup.cfg, plus regenerate lock files and update CI; not a one-liner but contained to packaging config.
Closest to 'persistent productivity tax' (b5) — applies_to web and cli contexts; the packaging choice shapes dependency workflows, CI, Docker images, and onboarding across the whole project but isn't quite system-defining.
Closest to 'notable trap most devs eventually learn' (t5) — misconception that requirements.txt is the modern standard is widespread; it lacks lock semantics and dev/prod separation, a documented gotcha Python devs learn after being burned by non-reproducible installs.
Also Known As
TL;DR
Explanation
Modern Python packaging: pyproject.toml (PEP 517/518) replaces setup.py and setup.cfg. Poetry: pyproject.toml + poetry.lock, integrated virtual env management, publish to PyPI. PDM: PEP 582, fast resolver. Key commands: poetry add (install + update lock), poetry install (from lock file, deterministic), poetry install --only main (production — no dev deps). Lock files ensure reproducible installs across environments. Virtual environments isolate project dependencies. PHP analogy: Poetry is to Python as Composer is to PHP.
Common Misconception
Why It Matters
Common Mistakes
- No lock file committed to git — non-deterministic installs across environments
- pip install in production instead of poetry install --only main — installs dev tools
- Not using virtual environments — global installs conflict between projects
- Mixing pip and poetry in the same project — breaks lock file integrity
Code Examples
# requirements.txt — no locking, no separation:
requests
flask
pytest # Dev tool in production!
black # Dev tool in production!
# Different versions installed on different days# pyproject.toml with Poetry:
[tool.poetry.dependencies]
python = '^3.11'
requests = '^2.31'
flask = '^3.0'
[tool.poetry.group.dev.dependencies]
pytest = '^7.4'
black = '^23.0'
# Commands:
# poetry install # From lock file — deterministic
# poetry install --only main # Production: no dev deps
# poetry add requests # Adds + updates poetry.lock
# git add pyproject.toml poetry.lock