Libraries and Modules in Python
Making a Package¶
We met modules in the previous episode. They were useful as we could put functions and classes into a seperate file and access them from other Python scripts. This was done by using the import keyword followed by the name of the module. The name of the module is the filename we give it (for single file modules at least).
If we make our own module, it is initially only importable from the current directory, which is fine for a small project, but if you had a module containin routines that you use regularly, it would be good if they could be imported into any of your projects.
Pip¶
Python comes with its own package manager called pip. Most commonly it is used to install packages contained in PyPI, the Python Packag Index, but can also be used to install packages stored in git repositories and on the local machine, which is what we will look at here.
We can demonstrate how to use pip by reinstalling the superheros module, if you followed through the setup episode this will be installed already, but pip will know this and reinstall anyway. We can install (or reinstall) the local package in ./code/superheros by running
!pip install ./code/superheros
It's as simple as that! pip is the package manager, install is the instruction we want pip to carry out, and ./code/superheros is the location of our package. If we instead wanted to install a package from PyPI we just put the name of the package in place of the path, for instance
!pip install nbfancy
will install the package nbfancy from PyPI's package repository.
Writing a setup.py¶
The reason we could pass the directory ./code/superheros to pip and have it install the package, was because it contained a file named setup.py. This Python file contains all the information pip needs to install the modules in superheros to the computer currently being used.
So to make our modules installable, all we have to do is write our own setup.py. After that we can just pass the directory containing setup.py (and our module) to pip and it will attempt to install it.
setup.py does not need to contain much information. A minimum working example is included in the file basic_setup.py in the module. (This file won't install the package, as it has the wrong filename!)
The script setup.py is not designed to be executed directly, it is called either by pip or with additional command line arguments to perform tasks. As a result you cannot execute setuptools commands directly into a notebook.
To see what is in the file we can use Python to read in the file and print the content to screen:
with open('./code/superheros/basic_setup.py') as fh:
print(fh.read())
We use the package setuptools, as is currently recommended. From the package we import the function setup which uses keyword arguments to provide the information about our package.
nameis the name of the package that will be used by pip. If we wanted to uninstall this package for some reason, we would pass this name to pip (pip listandpip uninstallcommands are uesful here).versionis the release version of our package, which is used by pip to update packages, or select specific versions of a package.py_modulesis a Python list containing all of the modules we want to include in our package.- Normally we would use the
packageskeyword to specify what to include, but we would need additional file structure for this to work.
That is all the necessary information, however there are far more keywords available, which we can see if we look at the file setup.py that is actually used to install the package:
with open('./code/superheros/setup.py') as fh:
print(fh.read())
Most of the keywords should be self explanatory, but if in doubt take a look at the documentation linked to above for specific information about any of these keywords.