Making python packages: a short tutorial

About:

David Silaghi
Aug 28, 2017 · 3 min read

The goal of creating a package is making code distribution more efficient. The recommended way to start a new Python package is by using a scaffolding tool, e.g cookiecutter, to build the namespaces and modules.

Following the 10 easy steps laid out below should bring you to the desired outcome:

Step 1:

Make a new directory with the desired project’s name. i.e. Proj

Step 2:

Create a virtual environment. For the purposes of this tutorial, Python 3 will be used, by typing:

virtualenv -p /usr/bin/python3 .

The main reason for creating the virtual environment in the project’s folder is to make installing the package with pip easily accessible.

It also makes sense to create a specific virtual environment to be your project’s very own. This way, you’ll only install the necessary packages for the project in your local virtual environment, unconcerned by package pollution. Remember to delete the virtual environment once it becomes obsolete.

Step 3:

Install cookiecutter:

bin/pip install -U cookiecutter 

Step 4:

Type

bin/cookiecutter https://github.com/audreyr/cookiecutter-pypackage.git

in order to create your directories and files. You can rearrange the just created files after the installation in order to better satisfy your project’s needs. A scaffolding tool can be used for various types of projects, from simple packages to Pyramid projects, etc.

Step 5:

In

 Proj/MainProj/__init__.py

proceed to write the desired code. For the purposes of this tutorial, a main function will be used, called main():

def main():
message = "You find yourself in the main function"
print (message)

If you want to create another module, build it in the same directory. For example, in a calculator.py module, write:

def calc():
x = 2 + 2
print (x)
return x

Step 6:

As a little bonus, let’s create a console script which uses entry points to open our 2 modules’ functions. Open setup.py and you should see a console script with entry points of the type:

entry_points = {
'console_scripts': ['insert-name-of-your-script- here=namespace.module:main'],
}

In case you are not familiar with the concepts of modules and namespaces, here is a short explanation:

Namespace:

As you can tell from the name, it is a space holding a bunch of names. Think about it as a mapping from names to objects. It will contain all the names, either explicitly designed or imported in your module. Speaking of modules…

Module:

A module is a “.py” file, containing any type of Python code. It can contain classes, functions, lists, etc. Each module has it’s own namespace, which means you can’t have 2 objects in the same module with the same name, as they would share the same namespace.

On the other hand, modules are isolated and namespaces are searched for inside-out. Thus, you can, in fact have identical names inside a namespace as long as the namespace itself (in its entirety) is not identical:

e.g. module1.name and module2.name are different namespaces, despite having some identical names.

In order to control what the namespace of a package contains, write code in the

__init__.py

file of the package.

In our case, the entry points will look something like this:

entry_points = {
'console_scripts': ['project=MainProject:main', 'addition=MainProject.calculator:calc'],
}

Step 7:

Move all the necessary folders and files in the virtual environment’s folder.

Step 8:

In setup.py, you can add any other necessary packages as requirements parameters to the setup function, in the list

requirements = [] 

The packages will be installed in

bin/

when you install the setup.py.

Step 9:

Install the package in the virtual environment:

bin/pip install -e .

Make sure to give the command in the shown form, to install the package as editable.

The difference between a package installed as editable and one which is not is that the first one has a link made for itself in site-packages while the latter is directly copied in site packages. As such, the link to site packages will always direct towards the latest version of the code. This is very convenient because now you can modify your modules after the installation of the package.

Step 10:

In order to launch the project, type

bin/insert-name-of-your-script-here

In our case, run

bin/addition 

and

bin/project

Further reading:

  • module documentation:

https://docs.python.org/3.5/tutorial/modules.html

  • another Python packages tutorial:

https://docs.python.org/3.5/tutorial/modules.html

)
Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade