Python - Custom Modules

We already know that a module is a file containing definition of functions, classes, variables, constants or any other Python object, even some executable code. Standard distribution of Python contains a large number of modules, generally known as built-in modules. These built-in modules may be written in C and integrated with Python interpreter, or a Python script (with .py extension). In this chapter we shall learn to build a custom Python module and use its functions in other programs.

Any text file with .py extension and containing Python code is a module. Just as in built-in modules, different Python objects in a custom module can be imported in interpreter session or another script.

If the program has a large number of functions and classes, they are logically organised in separate modules. One module stores classes, functions and other resources of similar relevance or developed for similar purpose. Such a modular design of the code is easy to understand, use and maintain.

Create custom module

Shown below is a Python script (messages.py) containing definition of a couple of functions.

"docstring of messages module"
def welcome(name):
       print ("Hi {}. Welcome to Python Tutorial".format(name))
       return
def bye(name):
       print ("Good Bye {}. See you again".format(name))

Importing module

We can now import this module and execute its functions from Python prompt

>>> import messages
>>> messages.welcome("Ravi")
Hi Ravi. Welcome to Python Tutorial
>>> messages.bye("Ravi")
Good Bye Ravi. See you again

Import module with alias

Use as keyword to refer to a module by an alias name.

>>> import messages as msg
>>> msg.welcome("Amar")
Hi Amar. Welcome to Python Tutorial

Import functions by name

When you import a module, all resources defined in it are loaded in current namespace. You may choose to load specific function(s) from the module using from..to syntax. This will not load other unwanted functions.

>>> from messages import welcome
>>> welcome("Rama")
Hi Rama. Welcome to Python Tutorial
>>> bye("Rama")
Traceback (most recent call last):
 File "<pyshell#2>", line 1, in <module>
   bye("Rama")
NameError: name 'bye' is not defined

Here only 'welcome()' function gets loaded from messages module. Hence calling 'bye()' function raises NameError. Note that function need not be called by prefixing name of its module to it.

There is also another alternative syntax available – 'from module import *' which is effectively equivalent to importing entire module (import module)

Importing module in another script 

As mentioned earlier, functions in Python module can be imported in another. We try to access welcome() function in messages module from following script (moduletest.py)

import messages
name=input('enter name:')
messages.welcome(name)

 Run 'moduletest.py' to get following output:

enter name:MurliMohan
Hi MurliMohan. Welcome to Python Tutorial

 Module attributes

Every Python resource is object. Likewise every module, either built-in or custom, is object of module class.

>>> #built-in module
>>> import math
>>> type(math)
<class 'module'>
>>> #custom module
>>> import messages
>>> type(messages)
<class 'module'>

A module object is characterized by various attributes. Attribute names are prefixed and post-fixed by double underscore __. Here are some important attributes:

__name__ :

When Python is running in interactive mode or as a script, it sets value of this special variable to '__main__'. It is the name of scope in which top level is being executed.

>>> __name__
'__main__'

From within a script also, we find value of __name__ attribute is set to '__main__'. Execute following script.

'module docstring'
print ('name of module:',__name__)

Output:

name of module: __main__

However, for imported module this attribute is set to name of the Python script. (excluding the extension .py). For messages.py module

>>> import messages
>>> messages.__name__
'messages'

However, this can be modified by assigning different string to this attribute.

>>> messages.__name__='mymessages'
>>> messages.__name__
'mymessages'

As seen earlier, value of __name__ is set to __main__ for top level module. However, for imported module it is set to name of file. Run following script (moduletest.py)

import messages
print ('name of top level module:', __name__)
print ('name of imported module:', messages.__name__)

Output:

name of top level module: __main__
name of imported module: messages

A Python script containing function may also have a certain executable code. Hence if we import it its code will be run automatically. To messages.py we add some executable code as below:

"docstring of messages module"
def welcome(name):
       print ("Hi {}. Welcome to Python Tutorial".format(name))
       return
def bye(name):
       print ("Good Bye {}. See you again".format(name))
name=input('enter name:')
bye(name)

Now we if we run the moduletest.py script, We'll find that the input statement and call to welcome() will be executed.

c:\python37>python moduletest.py

Output:

enter name:Kamala
Good Bye Kamala. See you again
enter name:mohan
Hi mohan. Welcome to Python Tutorial

This is output of both the scripts. What if we just want to import function from messages module and run executable code in it?

This is where the fact that value of  __name__attribute of top level script is __main__ is useful.  Change messages.py script such that it executes input and function call statement only if __name__ is equal to __main__.

"docstring of messages module"
def welcome(name):
       print ("Hi {}. Welcome to Python Tutorial".format(name))
       return
def bye(name):
       print ("Good Bye {}. See you again".format(name))
if __name__=='__main__':
       name=input('enter name')
       bye(name)

The moduletest.py is run unchanged. Executable part in imported messages module won't run now.

enter name: mohan
Hi  mohan. Welcome to Python Tutorial

Note that you can always run messages.py script independently.

__doc__: 

This attribute returns the docstring of module. Just as in function, Documentation string (docstring) is a string literal in first line written in module code. In messages.py module

"docstring of messages module"
def welcome(name):
       print ("Hi {}. Welcome to Python Tutorial".format(name))
       return
def bye(name):
       print ("Good Bye {}. See you again".format(name))
if __name__=='__main__':
       name=input('enter name')
       bye(name)

The __doc__ attribute will return string defined at the beginning of module code.

>>> messages.__doc__
'docstring of messages module'

__file__:

This attribute will returns the name and path of the module file.

>>> messages.__file__
'C:\\python37\\messages.py'

__dict__:

This attribute returns a dictionary object of all attributes, functions and other definitions and their respective values.

>>> dct=messages.__dict__
>>> dct['__doc__']
'docstring of messages module'
>>> dct['__name__']
'messages'
>>> dct['__file__']
'C:\\python36\\messages.py'
>>> dct['bye']
<function bye at 0x000001B227E0D158>
>>> dct['welcome']
<function welcome at 0x000001B225701E18>

dir() is a built-in function that also returns list of all attributes and functions in a module.

>>> dir('messages')
['__add__', '__class__', '__contains__', '__delattr__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__getnewargs__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__iter__', '__le__', '__len__', '__lt__', '__mod__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__rmod__', '__rmul__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'capitalize', 'casefold', 'center', 'count', 'encode', 'endswith', 'expandtabs', 'find', 'format', 'format_map', 'index', 'isalnum', 'isalpha', 'isdecimal', 'isdigit', 'isidentifier', 'islower', 'isnumeric', 'isprintable', 'isspace', 'istitle', 'isupper', 'join', 'ljust', 'lower', 'lstrip', 'maketrans', 'partition', 'replace', 'rfind', 'rindex', 'rjust', 'rpartition', 'rsplit', 'rstrip', 'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title', 'translate', 'upper', 'zfill']

Module search path

How does Python interpreter find a module when a script requests it to be imported? Python follows following method to locate a module:

• Whether it is present in current working directory?
• If not found there, directories in PYTHONPATH environment variable are searched.
• Otherwise, it searches the installation dependent default directory.

The sys.path attribute holds all locations to be searched for module.

>>> import sys
>>> sys.path
['', 'C:\\python37\\Lib\\idlelib', 'C:\\python37\\python37.zip', 'C:\\python37\\DLLs', 
'C:\\python37\\lib', 'C:\\python37', 'C:\\Users\\acer\\AppData\\Roaming\\Python\\Python37\\site-packages', 'C:\\python37\\lib\\site-packages']

If the module is not present in any of directories in the path, ModuleNotFoundError is raised.

Reloading a module

Python loads any module only once even if import statement is issued repeatedly. Consider following messages.py script:

"docstring of messages module"
def welcome(name):
       print ("Hi {}. Welcome to Python Tutorial".format(name))
       return
def bye(name):
       print ("Good Bye {}. See you again".format(name))
welcome("world")
bye("world")

Let us import messages module from Python prompt. The calls to functions in the code also get executed. However, repeating import statement doesn't execute them again.

>>> import messages
Hi world. Welcome to Python Tutorial
Good Bye world. See you again
>>> import messages
>>>

Now suppose we need to modify the SayHello() function before executing it again. Updated function is :

"docstring of messages module"
def welcome(name):
       print ("Hi {}. Welcome to Python Tutorial".format(name))
       return
def bye(name):
       print ("Good Bye {}. See you again".format(name))
welcome("Guest")
bye("Guest")

This change will be effected only if current interpreter session is closed and re-launched. If such changes are to be done frequently, to close and restart Python is cumbersome. In order to call load the module without terminating interpreter session, use reload() function from imp module.

>>> import imp
>>> imp.reload(messages)
Hi Guest. Welcome to Python Tutorial
Good Bye Guest. See you again
<module 'messages' from 'C:\\python37\\messages.py'>

In this chapter we learned how to build a custom module and import functions from it into other module.