[TASK] Migrate the production Wrangles Docker image to Python 3.13

[ebhills]

Task description

Migrate the production Wrangles container image from Python 3.11 to Python 3.13 in a focused, independently reviewable change.

This is the image built from the repository-root dockerfile and published as ghcr.io/wrangleworks/wrangles. Its entry point runs main.py, which executes the recipe supplied through WRANGLES_RECIPE.

This migration is a compatibility bridge, not a Pandas 3 migration. The production image must move to Python 3.13 with Pandas fixed at 2.3.3, the final Pandas 2.x release, and with a tested NumPy release that supports Python 3.13. Pandas 3.x must remain excluded until its breaking behavioral changes are addressed in separate work.

The migration must update the interpreter and the Python-version-specific image optimizations, add pull-request-level execution of the built image, and preserve the current tested-image promotion controls.

Context

PR #1130 standardizes the local development environment on Python 3.13 while retaining package compatibility with Python 3.11 through 3.13. The production Docker image was intentionally left on Python 3.11 for a separate migration because its build contains runtime-specific behavior that requires dedicated validation.

Python 3.11 is still supported for security fixes, so this is not an emergency replacement. Python 3.13 is nevertheless the preferred target because it is still in bug-fix support, aligns production with the standard developer environment, and has an official python:3.13-slim-bookworm image.

Wrangles currently declares pandas>=2.0,<3.0 in requirements.txt. A clean installation currently resolves that range to Pandas 2.3.3. That release is the correct stepping-stone baseline because Pandas recommends first upgrading to 2.3 and clearing deprecation warnings before moving to 3.x.

Python 3.13 also requires a newer numerical stack. The production Dockerfile's explicit numpy==1.24.3 build supports only Python 3.8–3.11. NumPy 2.1 introduced Python 3.13 support. Removing the old NumPy command without adding a tracked production constraint would allow future resolver drift, so the new image must deliberately select, test, and record an exact Python-3.13-compatible NumPy release.

References:

• Related developer-environment PR: Standardize local development on Python 3.13 #1130
• Python support lifecycle: https://devguide.python.org/versions/
• Official Python Docker image tags: https://github.com/docker-library/official-images/blob/master/library/python
• Pandas 2.3.3 release on PyPI: https://pypi.org/project/pandas/2.3.3/
• Pandas 3.0 migration guidance and breaking changes: https://pandas.pydata.org/docs/whatsnew/v3.0.0.html
• Pandas 3 string-dtype migration guide: https://pandas.pydata.org/docs/user_guide/migration-3-strings.html
• NumPy 1.24.3 supports Python 3.8–3.11 only: https://numpy.org/doc/2.4/release/1.24.3-notes.html
• NumPy 2.1 introduced Python 3.13 support: https://numpy.org/doc/2.3/release/2.1.0-notes.html
• Selected NumPy 2.4.6 release notes: https://numpy.org/doc/stable/release/2.4.6-notes.html
• NumPy 2.5 transition and Python 3.11 support drop: https://numpy.org/devdocs/release/2.5.0-notes.html
• pip deprecated and later removed --global-option: https://pip.pypa.io/en/stable/news/

Analysis decision (2026-08-23)

Use numpy==2.4.6 with pandas==2.3.3 in the Python 3.13 production-container constraint.

Why 2.4.6:

• NumPy 2.4.6 officially supports Python 3.11–3.14 and publishes CPython 3.13 wheels for Windows and Linux.
• It is the final bug-fix release in the mature 2.4 line and fixes regressions found in earlier 2.4 patches.
• It preserves the interpreter range currently declared by Wrangles, whereas NumPy 2.5 drops Python 3.11.
• NumPy 2.5.2 is technically viable but also expires additional deprecated APIs. Taking those removals in the same change as the Python and container migration would increase the production compatibility surface without a demonstrated Wrangles benefit.
• A source scan found no Wrangles use of the NumPy APIs removed in the relevant 2.4/2.5 releases.

Current local evidence:

• Isolated Python 3.13.1 environments resolved the complete Wrangles development dependency set with Pandas fixed at 2.3.3.
• NumPy 2.4.6: imports passed, python -m pip check passed, and the credential-safe suite passed: 1,495 passed, 112 deselected.
• NumPy 2.5.2 comparison: imports passed, python -m pip check passed, and the same suite passed: 1,495 passed, 112 deselected.
• This is Windows/local dependency and behavioral evidence only. Docker was unavailable locally, so Linux/amd64 wheel selection, final image size, runtime contents, and container execution remain required PR/CI evidence.

Reconsider NumPy 2.5 only in separate dependency work after the Python 3.13/Pandas 2.3.3 container baseline is deployed and stable.

Dependency and compatibility boundary

This issue has three distinct dependency responsibilities:

1. Public Wrangles package metadata

   • Keep Pandas 3 excluded.
   • Preserve pandas>=2.0,<3.0 unless a separate compatibility decision explicitly raises the minimum supported Pandas version.
   • Do not change the public package dependency to pandas==2.3.3; an exact application/runtime pin does not belong in the reusable library contract.

2. Production Python 3.13 container

   • Add a tracked container constraint file used by pip install /pkg.
   • Pin pandas==2.3.3 exactly.
   • Pin numpy==2.4.6. It supports Python 3.11–3.14, has Python 3.13 wheels, and passed the direct dependency/test comparison recorded above.
   • Do not move to NumPy 2.5 in this migration; evaluate that line separately after the new production baseline is stable.
   • Record the complete resolved dependency set with python -m pip freeze as build evidence.

3. Future Pandas 3 migration

   • Do not install, permit, or claim compatibility with Pandas 3.x in this issue.
   • Do not widen the package requirement to <4.0.
   • Track Pandas 3 separately because it changes inferred string dtype, enforces Copy-on-Write semantics, removes previously deprecated functionality, and can change datetime resolution and assignment behavior.
   • The later Pandas 3 work must add focused regressions for those behaviors before the upper bound is widened.

Current state

The production dockerfile currently has several Python 3.11 assumptions:

• both build stages use python:3.11-slim-bookworm
• NumPy is preinstalled from numpy==1.24.3 with custom compiler/linker flags
• that NumPy release does not support Python 3.13
• the build uses pip's legacy --global-option=build_ext interface
• Botocore and Pandas cleanup paths are hard-coded under /opt/venv/lib/python3.11/site-packages
• python3-dev comes from Debian Bookworm and should not be assumed to provide headers matching the official-image Python 3.13 interpreter
• build-essential, gcc, and gfortran appear to exist primarily for the old NumPy source-build optimization and should be retained only if a clean build proves they are still required

The image also intentionally reduces size by:

• retaining only the Botocore S3 service model and shared Botocore metadata
• deleting bundled Pandas tests
• copying a prebuilt virtual environment from the compile stage into a slim runtime stage

Repository inspection shows Wrangles currently creates only S3 clients through Boto3, so the S3-focused Botocore trimming remains consistent with current code. That behavior must be preserved and tested rather than silently broadened or removed.

CI and release behavior today

.github/workflows/ci.yml currently:

1. builds the Docker image on pull requests but does not load or run it;
2. pushes an immutable sha-<commit> candidate on main;
3. executes credentialed tests inside that candidate image;
4. promotes the tested digest to latest only after the container tests pass.

The immutable-candidate and promote-after-test behavior is a good safety boundary and must remain intact. The migration should close the pull-request gap by executing the exact locally built candidate without requiring secrets.

At issue creation, the checked-in consumers found in Eric's local repository set use immutable older tags:

• Lambda-Recipes: ghcr.io/wrangleworks/wrangles:1.14.0
• RSIS training workflow: ghcr.io/wrangleworks/wrangles:1.12.0

Those workflows will not change automatically. This issue must not retag or modify them. Consumers of mutable latest or dev outside the checked-in repository set must be treated as unknown until verified.

Proposed implementation

• Start from a freshly fetched origin/main on a dedicated branch and verify it is zero commits behind before editing.
• Change both Docker stages to python:3.13-slim-bookworm.
• Add a tracked production-container constraint file and make the Docker package-install command consume it.
• Pin pandas==2.3.3 in that container constraint file while preserving pandas>=2.0,<3.0 in the public package metadata.
• Pin numpy==2.4.6 in the production-container constraint file.
• Remove the unsupported numpy==1.24.3 source-build step and the legacy --global-option usage.
• Remove python3-dev, gfortran, GCC, and other compile packages that are no longer required. Retain a build dependency only with evidence from a clean, no-cache build.
• Replace all literal python3.11/site-packages paths with interpreter-derived paths or a small Python cleanup step using sysconfig or installed-module locations.
• Preserve and verify the existing Botocore S3-only data reduction and Pandas-test cleanup.
• Keep the final runtime stage free of compilers and build-only packages.
• Update .github/copilot-instructions.md and any other statement that still describes the production image as Python 3.11.
• Update pull-request CI so the exact image built from the PR is loaded and executed without publishing it.
• Run a credential-safe container smoke suite on pull requests. Do not expose repository or organization secrets to untrusted pull-request code.
• Keep the current post-merge immutable candidate, in-container tests, and promote-by-digest sequence unchanged unless a separately documented defect requires adjustment.

Expected pull-request scope

The smallest expected tracked-file set is:

• dockerfile
• a tracked production-container constraints file
• .github/workflows/ci.yml
• .github/copilot-instructions.md

A narrowly scoped smoke-test helper may be added if needed. Avoid application behavior changes, unrelated dependency upgrades, broad Docker hardening, Pandas 3 compatibility changes, or consumer workflow edits.

Pull-request validation

Dependency installation and image construction:

• Build from a clean Docker cache on Linux/amd64.
• Confirm the final image reports Python 3.13.x.
• Confirm the final image reports Pandas 2.3.3 exactly.
• Assert at runtime that Pandas major version is less than 3; fail the smoke test if Pandas 3.x is installed.
• Confirm the final image reports NumPy 2.4.6 exactly.
• Confirm python -m pip check reports no broken requirements.
• Capture python -m pip freeze from the final image as review evidence.
• Inspect installed Wrangles metadata and confirm its Pandas requirement still has the <3.0 upper bound.
• Confirm the final image contains no compiler toolchain or build-only apt packages.
• Confirm the Dockerfile contains no python3.11, numpy==1.24.3, or --global-option references.

Runtime imports and focused behavior:

• Import wrangles, numpy, pandas, pyarrow, polars, and boto3 from the final image.
• Record the resolved Python, Wrangles, NumPy, Pandas, PyArrow, Polars, Boto3, and Botocore versions in validation output.
• Run a basic NumPy/Pandas/PyArrow data round trip.
• Construct an S3 client with metadata lookup disabled and test credentials, without making a network call, proving the retained Botocore S3 model is usable.
• Run the local sample recipe and custom-functions sample against the built image.
• Run the repository's credential-safe pytest selection inside the exact built image. At issue creation the baseline is 1,474 selected tests and 100 explicitly deselected credential/live-service tests.
• Review Pandas-originated FutureWarning and DeprecationWarning output. Do not hide a warning that identifies work required before Pandas 3.
• Report skips separately. Do not treat dependency-absence skips as successful coverage.

Image comparison:

• Record the old and new final image sizes using the same Docker engine and measurement method.
• Explain any material size increase, especially one caused by NumPy wheels or retained package data.
• Confirm the multi-stage build still prevents compilers and source trees from entering the runtime image.

Post-merge validation

• Confirm the main workflow builds and pushes the immutable sha-<commit> image.
• Confirm the existing credentialed container test job passes against that exact digest.
• Confirm latest is promoted only after the container test succeeds.
• Confirm the promoted image still contains Python 3.13.x, Pandas 2.3.3, and NumPy 2.4.6.
• Record the tested image digest, dependency versions, and workflow run in the PR or issue.
• Do not claim Pandas 3, AWS, remote recipe, GHCR consumer, or other live validation unless that check actually ran.

Acceptance criteria

• The published candidate and promoted production image run Python 3.13.x.
• The image installs Pandas 2.3.3 exactly and rejects any Pandas 3.x resolution.
• The public Wrangles package metadata continues to exclude Pandas 3 with pandas<3.0.
• The image installs NumPy 2.4.6 exactly; NumPy 1.24.3 is gone.
• A clean no-cache Docker build succeeds without the unsupported NumPy source-build path.
• All site-package cleanup is Python-version-independent.
• Core imports, numeric/data round trip, S3 model smoke test, local recipe samples, and credential-safe container tests pass.
• Pull-request CI executes the built image without pushing it or exposing secrets.
• Existing post-merge test-before-promotion behavior remains effective.
• Image-size change is measured and documented.
• Package support for Python 3.11 and 3.12 is not removed by this container-only migration.
• Existing versioned GHCR tags and pinned downstream consumers are not modified.
• Documentation accurately distinguishes the Python 3.13 developer environment, the Python 3.13/Pandas 2.3.3 production container, and the deferred Pandas 3 migration.
• The PR description reports installation, imports, focused tests, full/credentialed tests, image build, and live-service results as separate evidence categories.
• No claim of Pandas 3 compatibility is made.

Out of scope

• Installing Pandas 3.x or widening the package dependency to allow it
• Addressing Pandas 3 breaking changes such as default string dtype, Copy-on-Write, removed deprecations, and datetime-resolution changes
• Retagging or rebuilding historical image versions
• Changing Lambda-Recipes or RSIS pinned consumer tags
• Removing Python 3.11/3.12 package compatibility
• Migrating SageMaker training dependencies
• Upgrading unrelated packages
• Broad container security hardening such as changing the runtime user
• Reworking the tagged-release publication design unless tracked separately

Rollback

If the Python 3.13/Pandas 2.3.3 candidate fails post-merge validation, do not promote its digest to latest or dev. Existing mutable tags should remain on the last tested image. Revert the migration commit or issue a narrowly scoped corrective commit; do not overwrite historical versioned tags.