docs(python3): clarify Python version compatibility and unsafe site-p…

[kaushalacts]

Summary

This PR improves documentation for gcr.io/distroless/python3 by clarifying
Python version compatibility requirements and common pitfalls when using
multi-stage builds.

Several users (myself included) encounter confusing runtime failures when
copying Python site-packages built with a different Python minor version into
a distroless runtime image. These failures can appear as Python corruption
but are actually caused by ABI mismatches.

This change adds clear guidance to help users avoid this class of issues.

---

What this PR does

• Documents that the Python minor version in the builder and runtime must match
• Warns against copying /usr/local/lib/pythonX.Y across mismatched versions
• Explains why ABI-related runtime errors can occur
• Clarifies the execution model (no shell, absolute paths required)
• Keeps scope limited to documentation only (no behavior changes)

---

What this PR does NOT do

• Does not change image contents or build logic
• Does not propose runtime behavior changes
• Does not introduce new tags or versions

---

Why this is useful

Modern Python workloads (FastAPI, data tooling, ML inference, etc.) often rely on
native extensions and newer Python versions. Without explicit documentation,
users can spend significant time debugging failures that are working as designed.

Clear documentation here should reduce support burden and improve user experience.

---

Fixes #1960

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello @kaushalacts, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the documentation for gcr.io/distroless/python3 images. It addresses a common pain point for users by clarifying critical aspects of Python version compatibility in multi-stage builds, detailing the risks of ABI mismatches, and outlining the specific execution model of these images. The goal is to prevent confusing runtime failures and improve the overall user experience by providing explicit guidance.

Highlights

• Python Version Compatibility: Added clear documentation emphasizing that Python minor versions in builder and runtime must match to avoid ABI-related runtime errors.
• Unsafe Multi-stage Build Patterns: Warned against copying site-packages across mismatched Python versions, detailing common errors like SyntaxError or segmentation faults that can occur due to ABI incompatibilities.
• Execution Model Clarification: Explained that distroless images lack a shell and require absolute paths for commands, providing a Dockerfile CMD example.
• Recommended Usage: Provided guidance on ideal use cases for distroless Python images (pure-Python, minimal dependencies) and suggested alternatives like python:<version>-slim for applications with native extensions.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly improves the documentation for the python3 distroless image by adding crucial information about Python version compatibility and multi-stage build pitfalls. The new sections on versioning, recommended usage, and execution model are clear and will undoubtedly help many users avoid common errors. I have one suggestion to refine the 'Execution Model' section to prevent potential confusion regarding path usage in CMD, but overall this is an excellent and much-needed update.

[gemini-code-assist]

The statement Commands must use absolute paths when invoking the Python interpreter: is a bit strong and could be confusing. The examples/python3 directory shows a CMD with a relative path (["hello.py", "/etc"]) that works because of the base image's ENTRYPOINT and WORKDIR.

To make this clearer and avoid contradiction, I suggest rephrasing to explain why absolute paths are recommended, while acknowledging that other patterns can work. For example, you could mention the default ENTRYPOINT and then present the absolute path CMD as a more robust alternative:

Distroless images do not include a shell. The python3 image has a default ENTRYPOINT of python3, so you can provide a script as a CMD. However, for maximum clarity and to avoid ambiguity, we recommend using absolute paths for the interpreter in your CMD:

[kaushalacts]

Thank you for the detailed review and the kind feedback — much appreciated.

Good catch on the wording in the Execution Model section. You’re absolutely right
that the python3 image’s default ENTRYPOINT allows providing a script via CMD,
as shown in the examples/python3 directory.

I agree that the current phrasing is too strong and could be confusing.
I’ll update the section to:

• Acknowledge the default ENTRYPOINT behavior
• Explain that absolute interpreter paths are a recommended, more explicit pattern,
  rather than a strict requirement

I’ll push a small revision shortly to reflect this. Thanks again for the guidance.