5.1. Modules and Package¶

5.1.1. Modules¶

5.1.1.1. Creating a module¶

Let’us look to the following example. In the file exponential.py we have written the following function:

def exp(x, epsilon=1E-6):
    """ calculate e to the power x """
    result = 0
    n = 1
    term = 1 # Initial value
    while abs(term)>epsilon :
        result = result + term
        term  = term * x/n
        n = n+1

How to use this exp from another file ? A solution could be the execute the file from the script with the exec(open('exponentielle.py').read()) command. However, there is a much more convenient technique in python. The function be can imported using the command

from exponential import exp

We do not put the .py file extension. Using modules has many advantages :

If the module was already imported, python do not execute the file a second time.
One can choose what we want to import in the module.
Python can automatically looks for different pathes to find the file.

5.1.1.2. Importing from a module¶

Python is not a general purpose language. All the function that are specific are defined in a module. Mathematical function (and constants) are in the math module.

They can be imported in different ways :

Import of the module
```
import math
print math.sin(math.pi/3)
```

Import of specific objects in the module

from math import sin, pi
print sin(pi/3)

Import of all the objects defined in the module
```
from math import *
print sin(pi/3)
```

The first method is more verbose because we have to specify the module name every time. However, we have to use this method in our example if we want to compare the exp function from two different modules.

In general, the second method should be preferred over the third one. Indeed, when all the functions are imported it is not easy then to know from which module the function was imported. Furthermore, this import can override existing function (for example, there is an open function is the module os. Therefore the command from os import * will override the standard open function).

The import * can be used for module with well known functions that are used many times in a program. This is the case for the math module.

5.1.2. Package¶

A package is a group of module (in other language it is called a library).

5.1.2.1. Installation of a package¶

Many packages are available on the Pypy web site. The pip shell command can be used to download and install the package on your computer. For example if you want to install the PyDAQmx package, simply run the command :

pip install PyDAQmx

If you don’t have root permission, then use the --user option.

If the package is not available on Pypy, then the usual way consist in downloading the package and then install it by running the setup script :

wget https://pypi.python.org/packages/source/P/PyDAQmx/PyDAQmx-1.3.2.tar.gz
tar -xvzf PyDAQmx-1.3.2.tar.gz
cd PyDAQmx-1.3.2
python setup.py install --user

5.1.2.2. Create your package¶

A package is a collection of modules and sub-packages. In order to create a package, you simply have to put the files into the same directory (called for example my_package). Python will know that this directory is a package if the there is a file called __init__.py in the directory. This file can be empty.

In order to import the modules, you can then do import my_package.mod1 or from my_package import mod1, ...

The __init__.py is a python module whose content is imported by from my_package import ....

Python will be able to import “my_package” :

If your current working directory is the directory containing the “my_package” directory
If this directory is in your search path. You can dynamically a directory into the search path using the following :
import sys
sys.path.insert(1, 'directory/containing/my_package')
If your directory is in the the “PYTHONPATH” environment variable.

If you have installed your package (see instruction bellow).

5.1.2.3. Local import¶

Inside a package, it is common to import modules or sub-packages, for example in the __init__.py file. This is a local import. You should indicate to python that an import is local by prefixing the module name with a dot. For example, in the __init__.py of my_package

from .mod1 import my_function

from . import mod1
mod1.my_function()

If you are in a sub-package, then you can import from the parent package using two (or more) dots.

5.1.2.4. Distribute your package¶

It is easy to create you package and distribute it. You have to write a setup.py file containing some informations about your package. Then Python will take care of everything. The setup.py file should be in the same directory as the “my_package” directory. A minimal example of a setup.py file is the following :

#!/usr/bin/env python
# -*- coding: utf_8 -*-

from distutils.core import setup
__version__ = "alpha"

long_description="""This is a very nice package

"""

setup(name='my_package',
      version=__version__,
      description='A very nice package',
      author=u'François Pignon',
      author_email='francois.pignon@trucmuch.fr',
      url='',
      packages=['my_package'],
     )

Then you can execute the following commands :

python setup.py install # Install the package
python setup.py sdist # create a tar.gz or zip of your package

python setup.py register # register on Pypy
python seupt.py sdist upload # Upload your package on Pypy

pip install -e . --user

The last command is very useful for developers. It installs the project in editable mode, which means that modification of the project files will be taken into account (a simple install will copy the files to another place).