Python Packages – Creating and Accessing

Python packages help us to manage modules and python scripts. They are normal directories with a init script – __init__.py.

How to Create a Python Package?

We can create a package by following below steps.

1. Create the package directory – we can use terminal or Python IDE for this.
2. Create __init__.py file – this is required to convert a normal directory into python package. This file is used to initialize the package and list all the modules. In the simplest form, this file can be empty.

What can we keep in a Python Package?

• The initialization file
• Python modules
• Python scripts
• Any other type of files

So in general, a package just like is a directory in our computer systems. The only difference is the mandatory inclusion of the __init__.py file.

Can we Create sub-packages in Python?

Yes, we can create a package inside another package. We have to follow the packaging rules to create a sub-package too.

Python Package Examples

Let’s look into some examples of creating and using packages.

1. Creating a Package

$ mkdir utilities
$ touch utilities/__init__.py
$ mkdir utilities/strings
$ mkdir utilities/strings/__init__.py
$ tree
.
└── utilities
    ├── __init__.py
    └── strings
        └── __init__.py

3 directories, 1 file
$ 

2. Adding Modules to the Package

Let’s say we have two python modules – math.py and str_utils.py. They have few functions that will be used in our program.

math.py:

def add(x, y):
    return x + y


def multiply(x, y):
    return x * y

str_utils.py:

def to_uppercase(s):
    s = str(s)
    return s.upper()


def reverse(s):
    s = str(s)
    return s[::-1]

We want to add these modules to our packages. Just copy these files to the packages directory where you want to keep these modules.

$ ls
math.py      str_utils.py utilities
$ mv math.py utilities 
$ mv str_utils.py utilities/strings 
$ tree
.
└── utilities
    ├── __init__.py
    ├── math.py
    └── strings
        ├── __init__.py
        └── str_utils.py

3 directories, 3 files
$ 

3. Importing Modules from a Package

The syntax to import a python module inside a package is:

import package.sub_package1.sub_package2.module
import package.sub_package1.sub_package2.module as module

Python uses sys.path variable to search for packages and modules. The current directory is part of the sys.path variable. So we will keep our python script in the python-packages directory. Otherwise, we will have to add the package location in the sys.path variable.

$ cat my_script.py 
import sys

print(sys.path)
$ python3.7 my_script.py 
['/Users/pankaj/Desktop/python-packages', '/Library/Frameworks/Python.framework/Versions/3.7/lib/python37.zip', '/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7', '/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/lib-dynload', '/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages']
$ 

Here is the my_script.py code to access the modules from the packages and calling their functions.

import utilities.math as math
import utilities.strings.str_utils as str_utils

print(math.add(10, 20))
print(str_utils.reverse("ABC"))

We can also import a module using below syntax:

from package.sub_package1.sub_package2 import module

Here is the updated example to access “math” and “str_utils” module in our program.

from utilities import math
from utilities.strings import str_utils

print(math.add(10, 20))
print(str_utils.reverse("ABC"))

4. Import * from a package

We can import every module from a package using the following syntax.

from package.sub_package1.sub_package2 import *

In this case, Python searches sub_package2 for packages, modules, and functions. This can produce side effects by importing something that you don’t want to. Also, it’s a very time taking process.

We can define a list of modules to be imported by creating __all__ variable in the __init__.py file.

utilities/__init__.py:

print('utilities package initialized')

__all__ = ['math']

utilities/strings/__init__.py:

print('utilities.strings package initialized')

__all__ = ['str_utils']

The updated my_script.py code is:

from utilities import *
from utilities.strings import *

print(math.add(10, 20))
print(str_utils.reverse("ABC"))

Output:

$ python3.7 my_script.py 
utilities package initialized
utilities.strings package initialized
30
CBA

Notice that the python code in the __init__.py gets executed first when the packages are initialized and imported.

How to add a Package to the System Path

It’s not feasible to always depend on the directory hierarchy to import package modules. We can add our custom package to the sys.path variable and then import them in any script.

import sys

sys.path.append("/Users/pankaj/Desktop/python-packages")

print(sys.path)

import utilities.math as math

print(math.add(1, 2))

Output:

$ python3.7 my_script.py 
['/Users/pankaj', '/Library/Frameworks/Python.framework/Versions/3.7/lib/python37.zip', '/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7', '/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/lib-dynload', '/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages', '/Users/pankaj/Desktop/python-packages']
utilities package initialized
3
$ 

Conclusion

Packages in Python allow us to divide our application modules and scripts into logical modules. This keeps our code base clean and easy to maintain.

References:

• Python.org Docs