7.1. Module Objects
A module is a Python object with arbitrarily named attributes that you can bind and reference. The Python code for a module named aname normally resides in a file named aname.py, as covered in "Module Loading" on page 144.
In Python, modules are objects (values) and are handled like other objects. Thus, you can pass a module as an argument in a call to a function. Similarly, a function can return a module as the result of a call. A module, just like any other object, can be bound to a variable, an item in a container, or an attribute of an object. For example, the sys.modules dictionary, covered in "Module Loading" on page 144, holds module objects as its values. The fact that modules are ordinary objects in Python is often expressed by saying that modules are first-class objects.
7.1.1. The import Statement
You can use any Python source file as a module by executing an import statement in some other Python source file. import has the following syntax:
import modname [as varname][,...]
The import keyword is followed by one or more module specifiers, separated by commas. In the simplest, most common case, a module specifier is just modname, an identifiera variable that Python binds to the module object when the import statement finishes. In this case, Python looks for the module of the same name to satisfy the import request. For example:
looks for the module named MyModule and binds the variable named MyModule in the current scope to the module object. modname can also be a sequence of identifiers separated by dots (.) to name a module in a package, as covered in "Packages" on page 149.
When as varname is part of a module specifier, Python looks for a module named modname but then binds the module object as variable varname. For example:
import MyModule as Alias
looks for the module named MyModule and binds the module object to variable Alias in the current scope. varname is always a simple identifier.
126.96.36.199. Module body
The body of a module is the sequence of statements in the module's source file. There is no special syntax required to indicate that a source file is a module; any valid Python source file can be used as a module. A module's body executes immediately the first time the module is imported in a given run of a program. During execution of the body, the module object already exists, and an entry in sys.modules is already bound to the module object, getting gradually populated as the module's body executes.
188.8.131.52. Attributes of module objects
An import statement creates a new namespace containing all the attributes of the module. To access an attribute in this namespace, use the name of the module as a prefix:
import MyModule a = MyModule.f( )
import MyModule as Alias a = Alias.f( )
Attributes of a module object are normally bound by statements in the module body. When a statement in the body binds a variable (a global variable), what gets bound is an attribute of the module object. The normal purpose of a module body is exactly that of creating the module's attributes: def statements create and bind functions, class statements create and bind classes, and assignment statements can bind attributes of any type.
You can also bind and unbind module attributes outside the body (i.e., in other modules), generally using attribute reference syntax M.name (where M is any expression whose value is the module, and identifier name is the attribute name). For clarity, however, it's usually best to limit yourself to binding module attributes in the module's own body.
The import statement implicitly sets some module attributes as soon as it creates the module object, before the module's body executes. The _ _dict_ _ attribute is the dictionary object that the module uses as the namespace for its attributes. Unlike all other attributes of the module, _ _dict_ _ is not available to code in the module as a global variable. All other attributes in the module are entries in the module's _ _dict_ _ and are available to code in the modules as global variables. Attribute _ _name_ _ is the module's name, and attribute _ _file_ _ is the filename from which the module was loaded.
For any module object M, any object x, and any identifier string S (except _ _dict_ _), binding M.S=x is equivalent to binding M._ _dict_ _['S']=x. An attribute reference such as M.S is also substantially equivalent to M._ _dict_ _['S']. The only difference is that when 'S' is not a key in M._ _dict_ _, accessing M._ _dict_ _['S'] raises KeyError, while accessing M.S raises AttributeError. Module attributes are also available to all code in the module's body as global variables. In other words, within the module body, S used as a global variable is equivalent to M.S (i.e., M._ _dict_ _['S']) for both binding and reference.
184.108.40.206. Python built-ins
Python supplies several built-in objects (covered in Chapter 8). All built-in objects are attributes of a preloaded module named _ _builtin_ _. When Python loads a module, the module automatically gets an extra attribute named _ _builtins_ _, which refers either to module _ _builtin_ _ or to _ _builtin_ _'s dictionary. Python may choose either, so don't rely on _ _builtins_ _. If you need to access module _ _builtin_ _ directly (a rare need), use an import _ _builtin_ _ statement. Note the difference between the name of the attribute and the name of the module: the attribute has an extra s. When a global variable is not found in the current module, Python looks for the identifier in the current module's _ _builtins_ _ before raising NameError.
The lookup is the only mechanism that Python uses to let your code access built-ins. The built-ins' names are not reserved, nor are they hardwired in Python itself. Since the access mechanism is simple and documented, your own code can use the mechanism directly (but do so in moderation, or your program's clarity and simplicity will suffer). Thus, you can add your own built-ins or substitute your functions for the normal built-in ones. The following example shows how you can wrap a built-in function with your own function (see "Module Loading" on page 144 for information about _ _import_ _ and "The reload Function" on page 146 for information about reload):
# reload takes a module object; let's make it accept a string as well import _ _builtin_ _ _reload = _ _builtin_ _.reload # save the original built-in def reload(mod_or_name): if isinstance(mod_or_name, str): # if argument is a string mod_or_name = _ _import_ _(mod_or_name) # get the module instead return _reload(mod_or_name) # invoke the real built-in _ _builtin_ _.reload = reload # override built-in w/wrapper
220.127.116.11. Module documentation strings
If the first statement in the module body is a string literal, the compiler binds that string as the module's documentation string attribute, named _ _doc_ _. Documentation strings are also called docstrings and are covered in "Docstrings" on page 72.
18.104.22.168. Module-private variables
No variable of a module is truly private. However, by convention, starting an identifier with a single underscore (_), such as _secret, indicates that the identifier is meant to be private. In other words, the leading underscore communicates to client-code programmers that they should not access the identifier directly.
Development environments and other tools rely on the leading-underscore naming convention to discern which attributes of a module are public (i.e., part of the module's interface) and which are private (i.e., to be used only within the module). It is good programming practice to distinguish between private and public attributes, by starting the private ones with _, for clarity and to get maximum benefit from tools.
It is particularly important to respect the convention when you write client code that uses modules written by others. In other words, avoid using any attributes in such modules whose names start with _. Future releases of the modules will no doubt maintain their public interface but are quite likely to change private implementation details, and private attributes are meant exactly for such implementation details.
7.1.2. The from Statement
Python's from statement lets you import specific attributes from a module into the current namespace. from has two syntax variants:
from modname import attrname [as varname][,...] from modname import *
A from statement specifies a module name, followed by one or more attribute specifiers separated by commas. In the simplest and most common case, an attribute specifier is just an identifier attrname, which is a variable that Python binds to the attribute of the same name in the module named modname. For example:
from MyModule import f
modname can also be a sequence of identifiers separated by dots (.) that names a module within a package, as covered in "Packages" on page 149.
When as varname is part of an attribute specifier, Python gets from the module the value of attribute attrname but then binds it to variable varname. For example:
from MyModule import f as foo
attrname and varname are always simple identifiers.
Since Python 2.4, you may optionally enclose in parentheses all the attribute specifiers that follow the keyword import in a from statement. This is sometimes useful when you have many attribute specifiers in order to split the single logical line of the from statement into multiple logical lines more elegantly than by using backslashes (\):
from some_module_with_a_long_name import (another_name, and_another, one_more, and_yet_another)
22.214.171.124. The from...import * statement
Code that is directly inside a module body (not in the body of a function or class) may use an asterisk (*) in a from statement:
from MyModule import *
The * requests that all attributes of module modname be bound as global variables in the importing module. When module modname has an attribute named _ _all_ _, the attribute's value is the list of the attributes that are bound by this type of from statement. Otherwise, this type of from statement binds all attributes of modname except those beginning with underscores. Since from M import * may bind an arbitrary set of global variables, it can often have unforeseen and undesired side effects, such as hiding built-ins and rebinding variables you still need. Use the * form of from very sparingly, if at all, and only from modules that are explicitly documented as supporting such usage. Most likely, your programs will be better if you never use this form.
126.96.36.199. from versus import
In general, the import statement is most often a better choice than the from statement. Think of the from statement, and most particularly from M import *, as conveniences meant only for occasional use in interactive Python sessions. If you always access module M with the statement import M and always access M's attributes with explicit syntax M.A, your code will be slightly less concise but far clearer and more readable. One good use of from is to import specific modules from a package, as we'll discuss in "Packages" on page 149. But in the vast majority of cases, import is better than from.