In this lesson, you will learn how to inspect your generated build artifacts to ensure your package contains exactly what you intended before shipping it to PyPI or internal repositories.
The Problem with Assumptions
Even with a perfectly configured pyproject.toml, it is easy to accidentally exclude a crucial data file or include sensitive development logs. Simply building your project with python -m build creates the artifacts, but it doesn't automatically tell you what ended up inside the dist/ directory. Relying on assumptions here is how broken installations happen.
Inspecting the Archive
The most reliable way to verify your package is to inspect the contents of the generated .tar.gz (Source Distribution) and .whl (Wheel) files directly. Since these are standard archives (ZIPs for wheels, GZipped tars for source), you can use Python’s built-in zipfile or tarfile modules to peek inside them.
For a wheel, which is a ZIP file, you can run a quick check from your terminal:
# List all files inside the generated wheel
python -m zipfile -l dist/my_package-0.1.0-py3-none-any.whl
What to Look For
When you inspect the output, look for three specific things:
- Source/Package Files: Ensure your actual Python modules (
.pyfiles) are present under the correct package name. - Metadata: Confirm that the
dist-infofolder exists, as this contains the license, README, and dependency metadata the installer needs. - Data/Assets: If your package relies on JSON configuration files or images, verify they are present in the expected subdirectory. If they are missing, your
pyproject.tomlconfiguration (specifically theincludeorpackage-datasettings) likely needs adjustment.
By making this inspection a mandatory step before running twine upload, you prevent "broken ship" scenarios where users install your package only to find the README.md missing or the logic files absent.
Key Takeaway: Always inspect your .whl and .tar.gz files using archive inspection tools before distribution to confirm that all required source code and static assets are correctly bundled inside the final package.