warming up your workspace

Why PyPI cares how you wrap a Python package

Your tests pass and your wheel builds. PyPI’s tighter archive checks explain why the package itself deserves a test of its own.

A fitted instrument case sits beneath transparent inspection plates.

The release that worked on your laptop

Imagine maintaining a tiny Python package that draws tide charts. Your examples run, your tests pass and a colleague has tried the latest change. Then the package upload fails. Nothing points to the code that computes the tide. The index is complaining about the file you put that code inside. An easy detail to miss when learning Python is that publishing a library creates another object with rules of its own.

On 18 November, PyPI described stricter checks it has introduced over the past few months for uploaded source and built distributions. It wants different tools reading the same archive to agree about what is inside. The announcement concerns publishers who produce files that fail the checks. PyPI says people installing packages have no breaking change to act on. For our imaginary chart maintainer, that narrows the investigation considerably.

Source: Python Package Index announcement

What exactly did the test exercise?

Picture the directory before release. Alongside the Python files sit a table of tide stations, a licence and a small image used by one example. Running the tests from that directory allows the code to see files lying right beside it. A person installing the package in another directory gets only what the build collected. A green test run on the working copy answers a different question from a successful installation of the finished wheel.

Try drawing three boxes on paper. Give the first box the names of the files in your checkout, the second the names in the distribution and the third the names the installed program actually opens. Trace the station table across all three. If it falls out at the second box, editing your calculation will have no effect. That missing table is an ordinary packaging mistake in our example. PyPI's announcement tackles a deeper problem at the same boundary.

Two readers should see one parcel

Think of a parcel passing between a dispatch desk, a sorting office and a recipient. Each can read a different fact about it, but they have to agree which parcel it is. A package index, an installer and a mirror likewise have different jobs. If their archive readers interpret the same bytes differently, a successful inspection by one tells the next less than you might expect. That disagreement is what programmers mean here by a parser differential.

For a maintainer facing a rejected release, the error message and the exact distribution are useful evidence. Keep the file your build produced. Record the Python and build backend versions, consult the index's archive guidance and rebuild using supported tools. Repeating the upload of an identical file gives you little new information. Comparing two builds while changing one thing gives you a chance to identify which step produced a different parcel.

A small release rehearsal

Before the next release of our tide chart library, imagine handing a colleague the wheel and a one sentence task. Ask them to draw the chart for one named station from an empty working directory. Give them neither the repository nor your open terminal. You will quickly discover which assumptions traveled with the package and which lived only on your laptop. It is a modest rehearsal with a concrete finish line. A stranger can open the parcel, find the table and draw the same tide.

Original source: Python Package Index