Python dependency upgrades

Python Dependency Upgrades

When to Use

Use when upgrading Python libraries, frameworks (FastAPI, Django, Flask, SQLAlchemy, Celery, Pydantic, Pytest), data/ML libraries (NumPy, Pandas, SciPy, PyTorch), or Python runtime versions (requires-python).

Environment & Tooling Discovery

1. Identify the Active Resolver & Lock Mechanism

Never mix Python package managers or run bare global pip install:

• uv (pyproject.toml + uv.lock): Use uv lock --upgrade-package <pkg> followed by uv sync (or uv run pytest). Verify lock consistency with uv lock --check.
• Poetry (pyproject.toml + poetry.lock): Use poetry update <pkg> (never poetry lock without --no-update on older Poetry v1 unless intending to refresh all unlocked packages; in Poetry 1.8+/2.0, poetry lock preserves existing locked versions by default). Verify with poetry check --lock.
• pip-tools (requirements.in $\rightarrow$ requirements.txt): Use pip-compile --upgrade-package <pkg> --generate-hashes requirements.in so only the targeted package and its sub-dependencies move.
• Pipenv (Pipfile + Pipfile.lock): Use pipenv update <pkg>. -Always activate or execute inside the project's virtual environment (.venv, uv run, poetry run).

2. Python Version Markers & Binary Wheel Availability

• Inspect requires-python in pyproject.toml (e.g., >=3.11,<3.14), .python-version, Dockerfile base images (python:3.12-slim-bookworm), and CI matrix versions.
• Multi-platform lockfiles (uv.lock, poetry.lock) resolve environment markers (sys_platform, platform_machine, implementation_name) across macOS (arm64/x86_64), Linux (manylinux glibc vs musllinux Alpine), and Windows.
• Check C/Rust extension packages (psycopg/psycopg2-binary, cryptography, orjson, pydantic-core, pillow, lxml, numpy, scipy, grpcio):
  • Confirm prebuilt manylinux / musllinux / macosx wheels exist on PyPI for the target Python version so production or CI builds do not unexpectedly fall back to slow, fragile source compilation requiring gcc, rustup, libpq-dev, or python3-dev.

Ecosystem-Specific Upgrade Contracts

1. Pydantic v1 $\rightarrow$ v2 & FastAPI / SQLModel Alignment

• Check whether any dependency still imports pydantic.v1 or relies on Pydantic v1 APIs (@validator $\rightarrow$ @field_validator, @root_validator $\rightarrow$ @model_validator, .dict() $\rightarrow$ .model_dump(), .json() $\rightarrow$ .model_dump_json(), .parse_obj() $\rightarrow$ .model_validate(), class Config $\rightarrow$ model_config = ConfigDict(...), BaseSettings moved to pydantic-settings).
• Upgrade pydantic, pydantic-core, pydantic-settings, and fastapi in compatible combinations.

2. SQLAlchemy 1.4 $\rightarrow$ 2.0 & Alembic

• Watch for 2.0 contract shifts: legacy session.query() vs select() + session.execute().scalars(), explicit session.commit() / transaction boundaries, DeclarativeBase and Mapped[...] / mapped_column(...) typing, and removed implicit autocommit (engine.execute() removed in favor of with engine.connect() as conn:).
• Ensure database driver packages (asyncpg, psycopg[binary], aiomysql, aiosqlite) match SQLAlchemy's dialect expectations.

3. Django LTS & Async / Middleware / Form Changes

• Check Django's official release notes for removed deprecation shims (USE_L10N, DEFAULT_FILE_STORAGE $\rightarrow$ STORAGES dict, index_together $\rightarrow$ Meta.indexes, url() $\rightarrow$ path()/re_path(), CSRF CSRF_TRUSTED_ORIGINS scheme requirements).
• Run python manage.py check --deploy and python manage.py makemigrations --check --dry-run after every Django or third-party app upgrade to confirm zero unapplied model/migration drift.

4. Static Typecheckers (mypy, pyright) & pytest

• When upgrading mypy, pyright, or types-* stub packages (types-requests, types-redis, types-PyYAML, django-stubs), fix newly uncovered Optional/Union or generic invariance issues in code rather than adding blanket # type: ignore.
• Run pytest -W error::DeprecationWarning on targeted modules to surface deprecations before the next major upgrade.