Introduction to distutils (III)29 Jan 2014
Hey there! We have already seen how to write the setup script and how to build and install the Python module, but how about we distribute it so that anyone can download it? For this, we'll use the Python Package Index.
Registering in PyPI
Although I say PyPI, as we are testing things here, it would be better to use the test server available here. All the steps that are going to be followed can be performed in the official PyPI in the same way.
First we need to register our account in the server. With this account, we will be able to register packages in the index and upload code to those packages. Now we need to let distutils know our credentials when uploading anything to the index. The easiest way to do this is by creating a file named .pypirc in your home directory, but take into account that the password is stored as plain text! The content of the file would be as follows:
[distutils] index-servers = pypi test [test] repository:https://testpypi.python.org/pypi username:your_username password:your_password [pypi] repository:https://pypi.python.org/pypi username:your_username password:your_password
By structuring the file this way, you can use both official and test indexes at the same time, for this tutorial, we only care for the test server, so the resulting file:
[distutils] index-servers = test [test] repository:https://testpypi.python.org/pypi username:your_username password:your_password
Applying classifiers to the package
As we are uploading the package to a package index, it is best to use classifiers in order to facilitate finding it. Here you can find the complete list of available classifiers, so choose to your heart's content.
Now we need to apply those classifiers to our setup script. For this, again, we will be using the dummy superfoo module. If we open the setup script, we find:
""" Setup script for superfoo """ from distutils.core import setup setup( # Module name name = 'superfoo', # Module version version = '1.0.0', # Short description description = 'Simple Python module example', # Author author = 'YOUR_NAME_HERE', # Contact email author_email = 'YOUR_EMAIL_HERE', # Support url url = 'YOUR_URL_HERE', # License (if any) license = '', # Packages to include in the build packages = ['superfoo'] )
One way of adding classifiers to the script is by including the classifiers attribute in the
setup() function, for instance:
classifiers = [ 'Development Status :: 3 - Alpha', 'Environment :: Console', 'Intended Audience :: Education', 'Operating System :: OS Independent', 'Programming Language :: Python', 'Programming Language :: Python :: 2.7', 'Topic :: Education', 'Topic :: Education :: Testing' ]
This will tell the package index that our package is an Alpha/development version, that it runs on console, that is intended for use in education, that it runs independently of the OS it is executed in, that is written in Python, specifically version 2.7 and that its main topic is education and testing.
Registering the package in the index
Before we can upload the package to the index, we need to register it. This is done by running the following command from the project's root:
$ python setup.py register -r test
Now, what does the parameter -r test do? Remember that we had the credentials for both the official PyPI and the test one? Well, this allows us to choose the repository in which we want to work. If you were trying to register a package in the official index, you would use pypi instead of test in the command.
If you log into your test PyPI account, you will see that the package superfoo appears listed under the "Your Packages" section. Fine, we have registered the package correctly, but now we need to properly upload the code. Usually, you want to use a source distribution, but you could also use a built distribution, especially when dealing with Windows systems, as it will provide an installable file. First we will do a source distribution:
$ python setup.py sdist
If we now look in the dist directory that has been created in our project's root, we will see a compressed file that contains the source code for our package. Thats neat, but we want to upload it to the index, so we need to use:
$ python setup.py sdist upload -r test
Note that the -r test parameter is also important here! The upload command will upload the built packages you specify before it (in this case sdist), but you can specify as many distribution types as you want before upload, for instance:
$ python setup.py sdist bdist upload -r test
This would create a source distribution and a built distribution and upload both to the index.
Installing uploaded packages
Now that our package has been uploaded and we can manually download it from the index, we need to know how to install it from the index. Of course we can download it and run
setup.py install, but there are tools that make things easier, like pip. Installing a package with pip is as easy as doing:
# pip install package_name
In our case, as the package is uploaded to the test server, we would need to write:
# pip install --index-url https://testpypi.python.org/pypi superfoo
For more information on pip, you can have a look at the official documentation.
Built distributions for Windows systems
Let's face it, using a console or terminal in Windows can be a real pain, especially to those who don't really know how to do it, and this also applies to installing packages from the PyPI. Because of this, it is possible to create installable executables (in a Windows environment) that allow users to download, double-click and install. The way to do this is:
$ python setup.py bdist_wininst
Starting with Python 2.6, it is also possible to cross-compile installers (for 32 and 64 bits) if you have the necessary tools. Here's how to create a 32-bit installer:
$ python setup.py bdist_wininst --plat-name=win32
And a 64-bit installer:
$ python setup.py bdist_wininst --plat-name=win-amd64
If you want to upload the installer, simply add upload -r test at the end of the command.
My name is Rafael Medina, and I like code.