To gain access to the variables and functions from a module, you have to import it. To tell Python that you want to use functions in module math, for example, you use this import statement:
| | >>> import math |
Importing a module creates a new variable with that name. That variable refers to an object whose type is module:
| | >>> type(math) |
| | <class 'module'> |
Once you have imported a module, you can use built-in function help to see what it contains. Here is the first part of the help output:
| | >>> help(math) |
| | Help on module math: |
| | |
| | NAME |
| | math |
| | |
| | MODULE REFERENCE |
| | https://docs.python.org/3.6/library/math |
| | |
| | The following documentation is automatically generated from the Python |
| | source files. It may be incomplete, incorrect or include features that |
| | are considered implementation detail and may vary between Python |
| | implementations. When in doubt, consult the module reference at the |
| | location listed above. |
| | |
| | DESCRIPTION |
| | This module is always available. It provides access to the |
| | mathematical functions defined by the C standard. |
| | |
| | FUNCTIONS |
| | acos(...) |
| | acos(x) |
| | Return the arc cosine (measured in radians) of x. |
| | |
| | acosh(...) |
| | acosh(x) |
| | Return the inverse hyperbolic cosine of x. |
| | |
| | [Lots of other functions not shown here.] |
The statement import math creates a variable called math that refers to a module object. In that object are all the names defined in that module. Some of them refer to a function objects:
Great—our program can now use all the standard mathematical functions. When we try to calculate a square root, though, we get an error telling us that Python is still unable to find function sqrt:
| | >>> sqrt(9) |
| | Traceback (most recent call last): |
| | File "<stdin>", line 1, in <module> |
| | NameError: name 'sqrt' is not defined |
The solution is to tell Python explicitly to look for the function in module math by combining the module’s name with the function’s name using a dot:
| | >>> math.sqrt(9) |
| | 3.0 |
The dot is an operator, just like + and ** are operators. Its meaning is “look up the object that the variable to the left of the dot refers to and, in that object, find the name that occurs to the right of the dot.” In math.sqrt(9), Python finds math in the current namespace, looks up the module object that math refers to, finds function sqrt inside that module, and then executes the function call following the standard rules described in Tracing Function Calls in the Memory Model.
Modules can contain more than just functions. Module math, for example, also defines some variables like pi. Once the module has been imported, you can use these variables like any others:
| | >>> import math |
| | >>> math.pi |
| | 3.141592653589793 |
| | >>> radius = 5 |
| | >>> print('area is', math.pi * radius ** 2) |
| | area is 78.53981633974483 |
You can even assign to variables imported from modules:
| | >>> import math |
| | >>> math.pi = 3 |
| | >>> radius = 5 |
| | >>> print('area is', math.pi * radius ** 2) |
| | area is 75 |
Don’t do this! Changing the value of π isn’t a good idea. In fact, it’s such a bad idea that many languages allow programmers to define unchangeable constants as well as variables. As the name suggests, the value of a constant cannot be changed after it has been defined: π is always 3.14159 and a little bit, while SECONDS_PER_DAY is always 86,400. The fact that Python doesn’t allow programmers to “freeze” values like this is one of the language’s few significant flaws.
Combining the module’s name with the names of the things it contains is safe, but it isn’t always convenient. For this reason, Python lets you specify exactly what you want to import from a module, like this:
| | >>> from math import sqrt, pi |
| | >>> sqrt(9) |
| | 3.0 |
| | >>> radius = 5 |
| | >>> print('circumference is', 2 * pi * radius) |
| | circumference is 31.41592653589793 |
This doesn’t introduce a variable called math. Instead, it creates function sqrt and variable pi in the current namespace, as if you had typed the function definition and variable assignment yourself. Restart your shell and try this:
| | >>> from math import sqrt, pi |
| | >>> math.sqrt(9) |
| | Traceback (most recent call last): |
| | File "<pyshell#12>", line 1, in <module> |
| | math.sqrt(9) |
| | NameError: name 'math' is not defined |
| | >>> sqrt(9) |
| | 3.0 |
Here, we don’t have a variable called math. Instead, we imported variables sqrt and pi directly into the current namespace, as shown in this diagram:
This can lead to problems when different modules provide functions that have the same name. If you import a function called spell from a module called magic and then you import another function called spell from the grammar module, the second replaces the first. It’s exactly like assigning one value to a variable and then assigning another value: the most recent assignment or import wins.
This is why it’s usually not a good idea to use import *, which brings in everything from the module at once:
| | >>> from math import * |
| | >>> print(sqrt(8)) |
| | 2.8284271247461903 |
Although import * saves some typing, you run the risk of your program accessing the incorrect function and not working properly.
The standard Python library contains several hundred modules to do everything from figuring out what day of the week it is to fetching data from a website. The full list is online at http://docs.python.org/release/3.6.0/py-modindex.html; although it’s far too much to absorb in one sitting (or even one course), knowing how to use the library well is one of the things that distinguishes good programmers from poor ones.