In Python, a module is a file that contains python code with functions, classes or just variables.
We already introduced modules in the Modules section.
We will cover modules more in depth in this section but let us briefly remind how to import a module.
7.1. Quick start: how to import a standard module¶
In order to import a module, use the import keyword as follows:
>>> import sys >>> import os
You can import several modules on the same line:
>>> import sys, os
Modules contain functions, classes, variables, other modules... To access module’s attribute (and more generally object’s attributes), qualify the attribute with the object name by using the dot operator:
Sometimes, you may want to import only a particular function:
>>> from sys import path
or all the functions but without importing the module itself:
>>> from sys import *
This method is not adviced because you import everything and therefore increase the possiblity to import function with same names as those in your scope. See Module design and special attributes for a solution.
You may find convenient to import a module with a different name:
>>> import math as maths
although as is a keyword, it can be used only with import.
There are a lots of standard modules provided with Python. However, you can easily creates your own modules (non standard modules).
7.2. How to create and import your modules¶
It works exactly as for the standard modules. You create a file, put some python code in it, open a python shell and type:
However, be aware that the Python interpreter looks in the directories that are part of the module search path defined by an environmental variable (PYTHONPATH under linux). You can check its contents within a Python shell with
import sys print sys.path
You can also modify it within python by adding an existing path to it:
import sys sys.path.append("newpath")
7.3. Contents of a module¶
>>> import copy >>> dir_list = [name for name in dir(copy) if name!='_'] ['Error', 'PyStringMap', 'copy', 'deepcopy', 'dispatch_table', 'error', 'name', 't', 'weakref']
7.4. Module’s name¶
When you import a module, it contains a special attribute called __name__, which contains the name of the module:
>>> import math >>> math.__name__ 'math'
Note, however, that within a module (or when you call the module with python executable) then the attribute __name__ contains the value “__main__”. So, you could include the following code to make a Python module executable:
if __name__ == "__main__": # run something. # you could call a function for instance.
This feature is useful when using test suite or if you want to create an executable. When you run the module directly, __name__ is __main__, so the test suite executes. When you import the module, __name__ is something else, so the test suite is ignored. This makes it easier to develop and debug new modules before integrating them into a larger program.
On Mac, there is an additional step to make the if __name__ trick work: pop up the module’s options menu by clicking the black triangle in the upper-right corner of the windows and make sure Run as __main__ is checked
7.6. Module design and special attributes¶
You have quite a lot of freedom on the organisation of your module.
You can add functions, classes, variables, other modules, documentation.
Here is an example of a module that we call mymod:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
#!/usr/bin/python """Some documentation should be added on the top of the module""" # Then you import modules (could be elsewhere but traditionally it is on the top) import math __all__ = ["A", "welcome"] some_variable = 1 _var = 2 class A(object): """example of class""" pass class internal(object): """example of internal class""" pass def welcome(x): print("Hello") if __name__ = "__main__": welcome()
Note that an empty module is perfectly valid: everything is optional.
The first line include what is called shebang line. It is not needed under Windows or Mac system but could be used under Linux if you want the file to be an executable to specifically indicate where is the python executable. If so, it must be the first line of the module.
The string on the top is the documentation of the module. It must be either on the top or just below the shebang. It will populate the special attribute __doc__. When you type:
this docstring will be shown.
The __all__ statement (line 6) is optional. It defines the API (public functionalities of the module). When you type:
from mymod import *
you import all the classes, functions and variables (except those starting with an underscore). However, at the beginning of the module, you can specify what should be the public part of the module using:
__all__ = ["A", "welcome"]
This variable can be found when importing the module:
>>> import mymod >>> mymod.__all__ ["A", "welcome"]
In such case, only these names are imported. You can still access to a non-public functionality given its name by typing:
from mymod import internal
There are other special attributes that could be useful:
- __file__ returns the physical name of the module.
- __package__ returns the package to which the module belongs.
- __doc__ returns the docstring at the top of the module if any
- __dict__ returns the entire scope of the module
An empty modules contains these 4 attributes and the __builtins__ attributes.
7.7. More about importing module¶
Although import can appear anywhere in the module, it is customary to add them at the top of the module;
You can import several modules on the same liner. These statements are correct:
import sys import os, math
Once a module is imported, Python creates a variable for this module and another import will have no effect:
>>> import math >>> math.pi = 3 >>> import math # no effect >>> math.pi 3
You can overcome this problem by using the reload/dreload functions (see next section reload and dreload)
You can load a specific attributes using from:
from math import pi
you can import several names:
from math import pi, cos, sin
and again, you can import all the attributes:
from math import *
This statement can be used only on top of the module, not within a class or function definitions.
You should use from with cautious especially the last statement. from does not create a module object. It only copies the objects. You can not refer to the module. Instead, you should use import. As for the import case, from execustes the code only once. So,
>>> from math import pi >>> pi = 3 >>> from math import pi >>> pi 3.141592653589793
7.8. reload and dreload¶
When developping new code, it is not uncommon to import a module in a Python session, to change the code and want to use it without quitting the session. In other words, you want to reload the module or function. The reload() function does that for you. It imports a previously imported module again:
Note that module_name is the name of the module you want to reload and not the string con- taining the module name. The module name should be named module_name and not module_name.
reload() will load only the module that has been loaded fully and not those imported with a from-import statement.
Since a module also import other modules, you may need to perform a deep reload:
7.9. intra-packages reference¶
to be completed
>>> from . import echo >>> from .. import formats >>> from .. filters import equalizer
See builtins function called __module__() to override the default behaviour of the import function.
You can attach a variable to a module or function:
def square(x): return x * x square.info = "simple square function"
You can use as several times on the same line:
>>> import math as m, sys as s
You can combine from, import and as:
from math import pi as constant_pi