Python Programming/Modules

Modules are a way to structure a program and create reusable libraries. A module is usually stored in and corresponds to a separate .py file. Many modules are available from the standard library. You can create your own modules. Python searches for modules in the current directory and other locations; the list of module search locations can be expanded by expanding PYTHONPATH environment variable and by other means.

Importing a Module

To use the functions and classes offered by a module, you have to import the module:

importmathprint(math.sqrt(10))

The above imports the math standard module, making all of the functions in that module namespaced by the module name. It imports all functions and all classes, if any.

You can import the module under a different name:

importmathasMathematicsprint(Mathematics.sqrt(10))

You can import a single function, making it available without the module name namespace:

frommathimportsqrtprint(sqrt(10))

You can import a single function and make it available under a different name:

frommathimportcosascosineprint(cosine(10))

You can import multiple modules in a row:

importos,sys,re

You can make an import as late as in a function definition:

defsqrtTen():importmathprint(math.sqrt(10))

Such an import only takes place when the function is called.

You can import all functions from the module without the module namespace, using an asterisk notation:

frommathimport*print(sqrt(10))

However, if you do this inside a function, you get a warning in Python 2 and error in Python 3:

defsqrtTen():frommathimport*print(sqrt(10))

You can guard for a module not found:

try:importcustommoduleexceptImportError:pass

Modules can be different kinds of things:

• Python files
• Shared Objects (under Unix and Linux) with the .so suffix
• DLL's (under Windows) with the .pyd suffix
• Directories

Modules are loaded in the order they're found, which is controlled by sys.path. The current directory is always on the path.

Directories should include a file in them called __init__.py, which should probably include the other files in the directory.

Creating a DLL that interfaces with Python is covered in another section.

Imported Check

You can check whether a module has been imported as follows:

if"re"insys.modules:print("Regular expression module is ready for use.")

Links:

• 28.1. sys # sys.modules, docs.python.org

Creating a Module

From a File

The easiest way to create a module is by having a file called mymod.py either in a directory recognized by the PYTHONPATH variable or (even easier) in the same directory where you are working. If you have the following file mymod.py

classObject1:def__init__(self):self.name='object 1'

you can already import this "module" and create instances of the object Object1.

importmymodmyobject=mymod.Object1()frommymodimport*myobject=Object1()

From a Directory

It is not feasible for larger projects to keep all classes in a single file. It is often easier to store all files in directories and load all files with one command. Each directory needs to have a __init__.py file which contains python commands that are executed upon loading the directory.

Suppose we have two more objects called Object2 and Object3 and we want to load all three objects with one command. We then create a directory called mymod and we store three files called Object1.py, Object2.py and Object3.py in it. These files would then contain one object per file but this not required (although it adds clarity). We would then write the following __init__.py file:

fromObject1import*fromObject2import*fromObject3import*__all__=["Object1","Object2","Object3"]

The first three commands tell python what to do when somebody loads the module. The last statement defining __all__ tells python what to do when somebody executes from mymod import *. Usually we want to use parts of a module in other parts of a module, e.g. we want to use Object1 in Object2. We can do this easily with an from . import * command as the following file Object2.py shows:

from.import*classObject2:def__init__(self):self.name='object 2'self.otherObject=Object1()

We can now start python and import mymod as we have in the previous section.

Making a program usable as a module

In order to make a program usable both as a standalone program to be called from a command line and as a module, it is advisable that you place all code in functions and methods, designate one function as the main one, and call then main function when __name__ built-in equals '__main__'. The purpose of doing so is to make sure that the code you have placed in the main function is not called when your program is imported as a module; the code would be called upon import if it were placed outside of functions and methods.

Your program, stored in mymodule.py, can look as follows:

defreusable_function(x,y):returnx+ydefmain():pass# Any code you likeif__name__=='__main__':main()

The uses of the above program can look as follows:

frommymoduleimportreusable_functionmy_result=reusable_function(4,5)

Links:

• The Python Tutorial - 6.1.1. Executing modules as scripts, python.org

Extending Module Path

When import is requested, modules are searched in the directories (and zip files?) in the module path, accessible via sys.path, a Python list. The module path can be extended as follows:

importsyssys.path.append("/My/Path/To/Module/Directory")fromModuleFileNameimportmy_function

Above, if ModuleFileName.py is located at /My/Path/To/Module/Directory and contains a definition of my_function, the 2nd line ensures the 3rd line actually works.

Links:

• The Module Search Path at Python doc

Module Names

Module names seem to be limited to alphanumeric characters and underscore; dash cannot be used. While my-module.py can be created and run, importing my-module fails. The name of a module is the name of the module file minus the .py suffix.

Module names are case sensitive. If the module file is called MyModule.py, doing "import mymodule" fails while "import MyModule" is fine.

PEP 0008 recommends module names to be in all lowercase, with possible use of underscores.

Examples of module names from the standard library include math, sys, io, re, urllib, difflib, and unicodedata.

Links:

• Package and Module Names at PEP 0008 -- Style Guide for Python Code
• The Python Standard Library at docs.python.org

Built-in Modules

For a module to be built-in is not the same as to be part of the standard library. For instance, re is not a built-in module but rather a module written in Python. By contrast, _sre is a built-in module.

Obtaining a list of built-in module names:

print(sys.builtin_module_names) print("_sre" in sys.builtin_module_names) # True print("math" in sys.builtin_module_names) # True 

Links:

• 28.1. sys # sys.builtin_module_names, docs.python.org
• The Python Standard Library, docs.python.org

External links

• 6. Modules, The Python Tutorial, python.org
• Python Module Index, python.org
• 31. Importing Modules, python.org
• Installing Python Modules, python.org
• Idioms and Anti-Idioms in Python, python.org
• Python: Why should 'from <module> import *' be prohibited?, stackoverflow.com
• Error handling when importing modules, stackoverflow.com