Building and Publishing Your Package

00:00 In the previous lesson, I showed you the ins and outs of package structure. In this lesson, I’ll be showing you how to publish your packages. Before getting into publishing, a brief aside about installation: you can install a package you’re writing into a virtual environment on your own machine. When you do that, the package files are copied into the site-packages/ directory.

00:22 The key part of that sentence was copied. If you edit your source code and then you want to test it in the virtual environment, you’d have to reinstall that package. Thankfully, there is a better way to do this, and it’s called editable mode.

00:36 When you install your code using editable mode, what gets put in the site-packages/ directory is a link to your actual code. This means you can use the code in the environment and edit it at the same time.

00:48 If your package is a framework, or if it comes with executable scripts, this can be very, very handy. To install in editable mode, you use the -e or --editable argument to the pip install command.

01:01 Let’s go try that out. Let me show you where I am … and now I’ll install using -m.

01:17 And there it is, installed. Note that you give it the directory of the package, not the source and the package. You’re giving it the place where it can find the pyproject.toml file. Now, because this is in my virtual environment, I can call it using python -m.

01:36 If it weren’t in the environment, I would have to use the REPL and import it or make one of the scripts in the module directly executable. But because it’s been installed, I can use it the way I intend my users to use it, which is actually pretty good practice because it tends to find bugs.

01:55 In order to build and publish, you’ll need some tools. The two most popular out there are called build and twine. build creates a directory with a wheel and a source distribution inside of it, while twine uploads these kinds of files to PyPI.

02:10 Let’s go do just that. Let me call the build command using python -m.

02:19 And it’s building … and building …

02:28 and building. And there you go. Successfully built the source and wheel files. That’s what I want. So now here’s the disk directory, which has two build files inside of it, the wheel file and the sdist.

02:45 A wheel file is actually a ZIP file with a particular expectation on its contents. That means I can look inside of it with the unzip command.

03:01 What you see here is the reader module, along with some metadata stored in a dist/ info directory. Note that if you’re on Windows, you might have to rename the wheel file to something actually ending in .zip, depending on what ZIP program you’re using. Otherwise, it might refuse to unzip it.

03:19 The twine package is used to do the upload to PyPI, but before uploading it, you can also use it to check the file. This is a useful step, as it validates the metadata. For example, if you had an illegal character in your README file, this would catch that. Yes, I am speaking from experience.

03:41 There’s the check, passed for both files. Nice. All right. This is as far as you go. If you’re playing along at home, this is where you have to stop. You have to stop because the name of the project is already taken, and you’re not one of the contributors unless of course, Geir Arne, you’re listening to this, and then go ahead and do whatever you like.

04:00 If you would like to play around, use -r testpypi in the twine command to point the uploader at the TestPyPI server instead. You’ll still have to rename the package because it exists in the test server as well. All right, I’m going to pretend I’m Geir Arne.

04:21 I’m sending both files with twine, and that’s why it’s dist/*. And once I do that, it asks for the username—yep, that’s not me, that’s the maintainer—and the password.

04:36 Once you’ve entered the password, it uploads the two files and then shows you where you can see the results.

04:45 And that’s it. That’s how you do it. Once you’ve gone through that twine upload step, you would now be able to do pip install of your package. Occasionally, there is a tiny bit of a delay in the index. Once in a while, if I upload a new version of the package and then try to upgrade on my machine, it still sees the old one. Give it thirty seconds, and that’s usually all it takes.

05:08 Here’s a quick little shortcut for you. twine looks for a .pypirc file in your home directory for common configuration values. You can specify what PyPI server to use, your username, and your password—except, yeah, please don’t do that last thing.

05:25 It stores it in clear text, and that’s just not a good idea. I mentioned the idea of what PyPI server to use. Why would you want to do anything but use PyPI? Well, it can actually be very handy in the corporate environment.

05:39 The PyPI server is freely available to be set up as its own instance. I’ve done this with teams of Python programmers. All the libraries that we wrote, which weren’t open source, went on the corporate server and could be pip installed like anything else using that server. You can even specify multiple places to look for things, so it will check one server and then the other, grabbing the corporate stuff first and then going off to the main PyPI afterwards. Here are the contents of my personal .pypirc file.

06:09 It’s pretty much the simplest version, saying to use pypi as my server and my account name. Note that I did not put my password in here. You can see a full listing of what values you can configure in this file at this URL, including how to set up multiple servers.

06:28 And that’s the basics around publishing a package. In the next lesson, I’ll show you other configuration you can do for fancier package situations.