Modules and Packages

Modules are nothing but files containing Python code. As your program gets bigger, it becomes hard to maintain if you keep it in a single file. Modules in Python are a way to re-factor your code into multiples files and referring those files in your main program.

A Package in Python refers to a collection of modules categorized under one logical grouping.

Lets see these definitions in action.

I would like to start with a simplest example to explain the concept of module. The first step is to create a working directory in any location of you machine. Let's name that directory - python. Open VS Code or any other editor in this directory.

In VS Code, lets create a new file (Ctrl+N). Add the below code.

def sayHello(name):
	return "Hello" + " " + name + "!"

Save this file with name - helloModule.py. Now, in VS Code or in any editor please make sure that you are in the same working directory. Now create a new file and add the below code.

import helloModule

helloText = helloModule.sayHello("Alice")

print(helloText)

Now execute this code (in VS Code, press Alt+Ctrl+N), you will see the following output.

Hello Alice!

That's it. That how you create a module. Now lets dig deep and see how it worked. As soon as you write the statement import <..filename..>, the python interpreter imports all statements and function definitions of the file into your python program. You can now access those function definitions by writing <file name>.<function name>

As we have seen, the import keyword is to load other modules in our program. However, it can take other forms of statements. For e.g. if we do not want all definitions of a module to include, then we can choose selected objects only by writing the following statement.

from <module name> import <object(s)>

To see this, lets modify out helloModule.py and append the following code and save the file.

def sayWelcome(name):
  return "Welcome" + " " + name + "!"

Now, create a new file and add the below lines.

from helloModule import sayWelcome

welcomeText = sayWelcome("Bob")

print(welcomeText)

As you can see, we have only added sayWelcome function in our program and we can directly call the function by the function name. You can also provide alias to the object name you imported.

from helloModule import sayWelcome as greet

print(greet("Chris"))

So, instead of writing sayWelcome we can call the function by the name greet

We can execute any python module through command shell or terminal as a script and it can take command arguments as input parameters. Here is how we can do that. Create a new file and add the following code.

import sys
import helloModule

helloText = helloModule.sayHello(sys.argv[1])
print(helloText)
		

Save this file as script.py

To execute this module (script.py) as script, we need to open command shell in the same directory and write the following command.

python script.py Alice

This will give the following output in command shell.

Hello Alice!

In the above code, we have imported sys module. We are using this module to extract the argument values that we will pass through command shell. We receive the command argument values in an array called sys.argv

As mentioned earlier, a package in python is a way to logically group a collection of modules under one name. You can think of it as providing a same group name to a collection of different modules. For e.g. In an image processing application, you are dealing with three services - filters (used to apply certain image filters), converter (converts an image into different formats) and shaper (used to crop, resize and rotate images)

Now suppose we have the following modules in the app.
sharpness.py
noise.py
props.py
png.py
jpeg.py
crop.py
resize.py
rotate.py

This list of modules can be large as we can have 100s of operations that we can perform on an image. This also creates confusion and is hard to maintain from development perspective. Hence it is better to further segregate and regroup them in to packages. Here is what we can do better.

filters
         __init__.py
         sharpness.py
         noise.py
         props.py
converters
         __init__.py
         png.py
         jpeg.py
shapers
         __init__.py
         crop.py
         resize.py
         rotate.py

Now the app is much more clean and well organized. This is what we can achieve with packages. A package can also contain other packages to further organize into some logical hierarchy.

The __init__.py is required to identify directories as packages. This file can be empty or can contain some code use to do some initializations before accessing modules under that package.

To use a module grouped under a package, we can simply call it with <package name>.<module name>. Considering the above example, if we want to access the resize module, we can do it as.

from shapers.resize import resizeVertically

resizedImage = resizeVertically(image, deltaTop, deltaBottom)

To import everything in a package, we can write the following statement

from filters import *