{
  "id": 11564685,
  "title": "Your Python Tests Passed. Your Published Wheel Is Missing Files.",
  "url": "https://urgent.news/2026/10/03/your-python-tests-passed-your-published-wheel-is-missing-files",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-10-03T00:48:52.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/haoli/your-python-tests-passed-your-published-wheel-is-missing-files-5gkc"
  },
  "original_language": "en",
  "account": "In July 2026, MLX released version 0.32.0 of its Python package for macOS ARM64. The distribution wheel was missing important files, specifically all .pyi stub files that were present in the previous release. As a result, type checking functionality broke for downstream users since the tests did not detect the issue as they ran against the source code repository, not the wheel file.\n\nThis same issue was also observed in OpenSpace, where a tracked host_skills/ directory was unintentionally omitted during the distribution process, leading to broken integrations when users installed the package via pip. The root cause of both these bugs was a lack of artifact verification during the publishing process.\n\nThe standard Python tooling does not check if the files actually make it into the wheel or source distribution (sdist) that is uploaded to PyPI. This oversight can be easily exploited by build backends, MANIFEST.in glitches, and misconfigured package-data settings, leading to the same outcome of a missing file at runtime.\n\nTo address this problem, the author developed a tool called wheeltruth that checks the actual artifact served by PyPI, rather than the source repository. wheeltruth is a standard library-only Python command-line interface that verifies various aspects of the wheel distribution. When run against the built artifacts, wheeltruth performs the following checks:\n\n1. RECORD completeness - It verifies that every file listed in the wheel's RECORD is present, has the correct SHA256 hash and size.\n2. Entry point resolution - It ensures that each console_scripts and gui_scripts target points to an actual module inside the wheel.\n3. Typing stub consistency - If a package includes .pyi stub files, wheeltruth checks that every module has a corresponding stub. An incomplete set of stubs (like in the MLX case) will be flagged.\n4. METADATA consistency - It confirms that the package name and version match between the wheel file name and the wheel's own METADATA.\n\nwheeltruth can also compare both the wheel and sdist distributions, highlighting files that were included in the sdist but missing from the wheel (like in the OpenSpace case), and vice versa. The tool supports both src/ layouts and ignores common test, docs, and other unrelated directories.\n\nIn addition to the standard checks, wheeltruth offers two additional modes for more paranoid checks:\n\n1. It verifies that the packages declared in pyproject.toml or setup.cfg actually exist within the wheel.\n2. It can perform a smoke test by installing the wheel into a throwaway virtual environment and attempting to import every top-level module.\n\nThe tool exits with a status code of 0 when no issues are found, and 1 when problems are detected, making it easy to integrate into continuous integration (CI) pipelines. An exit code of 0 indicates a clean build, while an exit code of 1 signals that problems were found and need to be addressed.\n\nIt's important to note the tool's limitations. As of version 0.1, wheeltruth only performs check operations and does not correct any configuration issues. The expected files are heuristics inferred from the sdist or project configuration, so exotic layouts may produce false positives. The smoke test requires a working virtual environment and takes a few seconds per wheel. Additionally, the stub check is a consistency check and cannot predict what was included in previous releases.",
  "summary": "In July 2026, MLX shipped v0.32.0 for macOS ARM64. The wheel contained py.typed . It did not contain a single .pyi stub — every stub the previous release had was silently gone. Downstream type checking broke for users. The project's own test suite never noticed, because tests run against the source tree, not the wheel. A month earlier, OpenSpace's built distribution silently dropped a tracked…",
  "key_points": [
    "MLX Python package version 0.32.0 released in July 2026",
    "Missing .pyi stub files caused type checking to break",
    "wheeltruth tool developed to verify wheel distributions"
  ],
  "editors_take": "The lack of artifact verification during publishing has led to broken packages, but a new tool called wheeltruth can help address this issue by checking wheel distributions for completeness and consistency.",
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}