Python Packages & Modules Tutorial

In this tutorial we learn how to structure your Python application with packages, sub-packages and modules.

We cover creating packages with modules, importing them, and how to access items from a module inside a package.

Here's a table of contents of what you'll learn in this lesson:
(click on a link to skip to its section)

Let's jump right in.

What are packages

As our application becomes larger, it makes sense to store sections of code into modules. Similarly, we can store modules inside packages as a means to group them.

Packages use an operating system’s inherent hierarchical file structure. Think of packages as the same as directories on your computer.

We have packages for directories, sub-packages for sub-directories, and modules for files.

A directory must contain a file named __init__.py for Python to consider it as a package. In general, the __init__.py file has our initialization code for that package, but it may be left empty.

How to create a package with modules

If you’re not using PyCharm, please ensure that you have the following.

In the directory where your current Python files are:

  • Create a sub-directory called MyPackage.
  • Create 2 python files and name them:
    • __init__.py
    • functions.py

If you are using PyCharm, follow the steps below:

  1. In the explorer pane, right-click on your project folder and select New > Python Package.
  2. Type in “MyPackage” as the name and click Ok. The __init__.py file will be automatically created for us.
  3. Right-click on “MyPackage” and select New > Python File and call it “functions”.

In the functions.py file write some simple code from what we’ve learned so far in the tutorial series.

Example:
def print_greeting(name):
    print("Hello", name)

shopping_list = ["Bread", "Milk", "Fruits"]

def print_list():
    print("Shopping list:")
    for item in shopping_list:
        print(item)

How to import the package and module

Back in our main Python file we import the package and the modules we want. In this case we only have one module called functions.

To import a module from inside a package we use the from import statement, where we import the module from the package.

Syntax:
 from package_name import module_name
Example:
 from MyPackage import functions

How to access items from a module inside a package

If we import the module directly, we have to use dot notation on the module.

Example: direct import, dot notation
from MyPackage import functions

functions.print_list()

If we import the module directly, with an alias, we can spare ourselves some writing time.

Example: direct import, alias
from MyPackage import functions as pkg_f

pkg_f.print_list()

__init__.py in a package

The __init__.py file in a package serves two purposes.

  1. If it exists inside a directory, the directory will be considered a package.
  2. It exposes any items we specify from the package modules.

An empty __init__.py file will make all the code inside all the modules available when a package is imported.

How to specify explicitly what code may be imported from which modules

To specify explicitly what code may be imported from a module, we use a from import statement again, this time in the __init__.py file.

Syntax:
 from .module_name import item1, item2, item3, ...

We have to specify the dot operator before the module name.

Example:
 from .functions import print_list

In most cases people leave the __init__.py file empty and prefer to write their specific import code in the document that’s importing a package module.

Summary: Points to remember

  • Packages are storage systems for modules, similar to how we store files in directories on our computers.
  • Python will only consider a folder as a package if it contains an __init__.py file.
  • Modules are imported from packages with the from package import module statement.
  • Items in a package module are accessed with dot notation.
  • If we want to specify which code should be imported from which modules, we use the from/import statement in the __init__.py file.