What are Python Modules

Hello Reader,

This post is one in my python-basics series. My intention with this article is to provide the basics and illustrate basic usage. It is not my intention to tell you all you need to know, but rather to give you some of the key words and concepts to help you get started learning about modules.

Okay, boilerplate over, on with the show!

In Python, modules are a unit of Python code encapsulated in a file (or in more rare cases, multiple files). In the case of a single file (often referred to as a script), the name of a module is the name of the file, minus the extension.

For example, if you had a file named gummi.py then Python would determine the module name would be gummi.

This module can then be imported by other modules by using an import statement.

import gummi

Using the import statement will allow another module to have access to anything in the gummi module (under the prefix of gummi.).

But what exactly can be accessed from that module? Well, first we need to define something in the gummi module. We can define variables, functions, or classes within a module file. So in this example, we will define a function named bounce.

def bounce():
    print('Boing!')

And then we can create a new module file named cavin.py. Within this file we will import the gummi module, and then call the bounce function:

import gummi

gummi.bounce()

Since we are just using the bounce function, we can also import it exclusively from the gummi module:

from gummi import bounce

bounce()

But now we have a problem. If another module imports the cavin module, the import statement for the gummi module will be executed, then the call to the bounce funtion will be executed. This can lead to some unpredictable behavior and should be avoided so it does not have to be fixed later when another modules imports the cavin module. Since this is not the behavior we want we need to make a change. So how do we make it so that the bounce function is only executed when the module is ran (rather than imported)? Let's change our cavin module file to look like this:

from gummi import bounce

if '__main__' == __name__:
    bounce()

"But Wait!" you say, "What is this if '__main__' == __name__: thing?" As explained earlier, every module has a name. This is normally derived from the filename. However, when you tell python to run a module it assignes a special name to that module: __main__. This line of code determines if the module is being targeted for execution. This check allows us to isolate the behavior we want for when the module is run, rather than imported. Now, the cavin module can be run like this from your command line:

python -m cavin

This may be a little different than what you may have seen or done before. It is common to run a script like this:

python cavin.py

The benefit of using the -m flag is that it allows for more complex imports to be resolved correctly. So my advice to prevent future pain is to run modules with -m and using their module name, rather than treating them as isolated scripts (thereby preventing future pain and suffering when a more complex import trips you up).

Getting back from our little tangent. Following the path of using the if '__main__' == __name__: line allows us to have the option of importing or executing the module. This allows the code to be reused in both forms, and persisted across successive executions.

Python comes with its own set of included modules. This is one of the things that makes Python a very powerful Scripting and Programming language and a good choice for many audiences. This is often referred to as "batteries included". It even comes with some nice platform specific modules. These are very well documented in the Python Documentation. One place to see them all is on the Python Module Index page. You can also search the Python Documentation if you are looking for more information on a included module that you already know the name of. Finally, Python.org » Documentation » The Python Tutorial » 6. Modules is an excellent place to continue learning about modules and how they work.

Good Luck & Happy Hacking,

=> Charles