4 Things Tutorials Don't Tell You About PyPI

By

Time to celebrate!

I published my first Python package to PyPI, Suite8080. It’s a suite of Intel 8080 Assembly cross-development tools. It’s in early development, misses some tools, and is rough around the edges. But it works, does something useful (if you’re into retrocomputing), and I’m having ridiculous amounts of fun with this hobby project.

Python Package Index (PyPI) website
The Python Package Index (PyPI) website.

The celebration is wearing out and I’m about to resume the work to complete and improve Suite8080, yet something still bugs me.

Although it’s well known PyPI is unforgiving for good reasons, the package publishing process is not as straightforward as the tutorials make it seem. I run into a few unexpected minor bumps none of the guides mention.

It’s not that the tutorials aren’t good, they are. I recommend the Real Python article on publishing a package to PyPI.

But the authors of these guides are so experienced, and probably so detached from the challenges beginners face, they may not be aware some issues and unknowns are worth addressing. So I thought I’d share my experience with PyPI while it’s still fresh, focusing on 4 things I haven’t seen discussed anywhere.


Relative URLs don’t work

Have you ever seen a PyPI entry with a great README.md but a missing screenshot replaced by the browser’s broken image icon? You can’t miss such entries as they stick out as sore thumbs.

I never figured why this happens and blamed sloppiness until I uploaded Suite8080 to Test PyPI for the very first time. Sure enough, although the screenshot in my README.md showed up nicely on GitHub, it was missing from the Test PyPI entry. A quick check of the Markdown source revealed PyPI doesn’t support relative URLs like ![My screenshot](screenshot.jpg) in README.md. Replacing the relative with an absolute URL starting with https://... fixed the issue. Since my README.md’s screenshot is hosted on GitHub, I can use a URL like https://raw.githubusercontent.com/username/projectname/master/image.jpg.

Neatness counts.


Test PyPI doesn’t purge packages

Once I realized the image link was broken on Test PyPI, I set out to re-upload the fixed package. I wanted to maintain the same version number for the new upload. Why? To keep future uploads in sync between Test PyPI and regular PyPI without changing the version number in the source. I wanted to minimize the differences to catch potential issues on Test PyPI first.

I knew PyPI doesn’t allow to remove versions but I read that Test PyPI is supposed to periodically delete uploaded packages, every 24 hours according to a source. However, the next day my previous upload was still there.

More research revealed Test PyPI nearly never purges packages. The purge seems to have happened only a handful of times over the history of the platform.

Never mind, I’ll let version numbers diverge until I can make them match again at the next minor release bump.


Indexing a new package takes 24 hours

The next step after making sure Suite8080 went live on regular PyPI and telling everyone and their brother was mashing the search box.

The project showed up on PyPI’s home page under the new releases and the link to the Suite8080 entry worked fine.

But searching for the exact name of the package returned nothing. I kept searching and poring over the result pages but ended up empty-handed. This seemed an issue as, until a project is indexed, tools such as shields.io that fetch data from PyPI don’t recognize the name and return an unknown package error.

It turns out poor PyPI needs some time to catch its breath and index new packages. The following day, Suite8080 became the first hit when searching for the exact name, as expected. So it takes the platform 24 hours to index new submissions.


You can delete Twine’s working folders

Building a project for distribution leaves around stuff in the source tree.

Twine stores its working files in the directories build, dist, and projectname.egg-info. While I could leave them there as .gitignore takes care of skipping them, I wanted to remove the directories to maintain a cleaner source tree and make it easier to pick the correct archives from dist when uploading to PyPI.

After some experimentation, I figured I can safely remove the directories as running Twine has no side effects. Building the distribution from the same sources and metadata yields the same archives.

Popular posts from this blog

Using a Bluetooth Keyboard on Android

By
Image
Two years ago I bought a cheap Bluetooth keyboard from Amazon.it. At €14, it was mostly an impulse buy for exploring mobile typing on the go and in similar settings , such as workstations with reduced desk space. My FREALL 7INKEYBD-BK Bluetooth keyboard. I initially used the keyboard with the Android tablet and smartphone I had, a 7” Lenovo Tab E7 and a Pixel 2 XL. I later repurposed the keyboard for the devices I replaced those with, a Lenovo Tab M8 HD 8” tablet and a Pixel 4 XL smartphone. Despite the simplicity of operation, it took me some trial and error to figure out how to pair the keyboard with an Android device and what keystrokes insert the characters I need, such as accented letters when writing in Italian. Moreover, I realized I never blogged about my experience with the unit. So I’m posting these notes in case you come across the same or similar keyboards. The keyboard The keyboard is a cheap, compact, plastic chiclet unit that comes with a small foldable stand for a ta...
Read more

Lenovo Tab M8 HD Review

By
Image
I bought a Lenovo Tab M8 HD , an 8” Android tablet. It comes with a MediaTek Helio A22 SoC, an IPS panel, 2 GB of RAM, and 32 GB of storage. I ordered the device from Lenovo’s Italian online store for €134. In this post I’ll share my early impressions on the device. The packaging box of the Lenovo Tab M8 HD tablet. Motivation The Lenovo Tab M8 HD replaces the Lenovo Tab E7 7” tablet I bought almost a year and a half earlier. After enjoying the Google Nexus 7 2012 and 2013 tablets I left Android slates for several years. My return to tablets with the November 2019 purchase of the cheap Lenovo Tab E7 was a sort of impulse buy. I wanted an affordable Android slate small enough to be compact but with a large enough screen to help productivity . I also figured it would double as an ebook reading device and let me explore the Android ecosystem. The Tab E7 was nice but limited. The screen didn’t have good touch sensitivity, performance was poor, there was a lot of lag, and the screen was no...
Read more

How to Add Code Syntax Highlighting to Blogger

By
Image
On my blog I always wanted to format source code in Python and a couple more languages, but couldn’t find a convenient way. Until I read a tutorial on adding syntax highlighting to Blogger blogs like mine. The Blogger post composer actually provides the monospace Courier font that may be used for source code, but it works well only for inline text . If I apply the Courier font to a block of code, the composer renders each line as a separate paragraph. This leaves too much vertical space that makes the code look ugly. A workaround is to switch to the HTML view in the composer and wrap the block within <pre> ... </pre> tags, which insert the correct line spacing. However, the code doesn’t stand out on the page and there’s room for improving its scannability and visual impact. Fortunately, Blogger is an old dog I can teach new tricks to, like the setup the tutorial I found presents. A Python code snippet with syntax highlighting rendered by highlights.js in a post of the Moo...
Read more