Importing Modules
=================
One of the most important things to realize about modules is that they are
data *objects*. Just like a *string* is a collection of individual characters,
and a *list* is a collection of individual elements, *module objects* are
collections of data values and Python code blocks.
The ``import`` Keyword
----------------------
Before we can use any of the items stored in a module, we must import it. The
syntax for this is:
.. index:: ! import, ! dot notation
.. index::
single: module; import
.. sourcecode:: Python
import module_name
The **import** keyword tells Python to find the file called ``module_name`` and
make it available for use in the program. For example, the statement
``import turtle`` creates a new name, ``turtle``, which points to the module
where all of the turtle data and functions are stored.
.. admonition:: Warning
Put all ``import`` statements in the very first lines of a program! This
avoids runtime errors by importing all module items well before your code
calls for them.
To use something stored in a module, we use **dot notation**, which joins the
name of the module with a variable or function name:
.. sourcecode:: Python
module_name.variable_name # Access the data assigned to variable_name
module_name.function_name(arguments) # Call function_name
For example, we have used the ``string`` module to access a list of all the
lowercase letters, and we have used the ``turtle`` module to draw a circle on
the screen:
.. sourcecode:: Python
:linenos:
import string
import turtle
print(string.ascii_lowercase) # Prints abcdefghijklmnopqrstuvwxyz
turtle.circle(50) # Draws a circle with a 50 pixel radius
We can read these two examples of dot notation like this:
#. **Line 4** - In the ``string`` module, access the value for the variable
``ascii_lowercase``.
#. **Line 5** - In the ``turtle`` module, call the function called ``circle``,
and send it the argument ``50``.
.. admonition:: Note
In order to call a function stored in a module, we MUST know the name of
that function. To access a data value stored in a module, we MUST know the
variable name for that value.
Find the Names of Module Items
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _dir-function:
.. index:: ! dir()
To figure out the names of all the items stored in a module, we could look them
up with a Google search. However, Python has a useful directory function,
``dir()``, that returns a list of names for everything stored in a module.
.. admonition:: Example
.. sourcecode:: Python
:linenos:
import string
print(dir(string))
**Console Output**
::
['Formatter', 'Template', '_ChainMap', '_TemplateMetaclass', '__all__', '__builtins__',
'__cached__', '__doc__', '__file__', '__loader__', '__name__',
'__package__', '__spec__', '_re', '_sentinel_dict', '_string',
'ascii_letters', 'ascii_lowercase', 'ascii_uppercase', 'capwords', 'digits',
'hexdigits', 'octdigits', 'printable', 'punctuation', 'whitespace']
To make this output easier to read, we can use a loop to print the list
one element per line.
.. raw:: html
.. admonition:: Tip
From the list of names, skip those that begin with underscores ``__``. Using
these is a more advanced skill, and we will focus on the other options for
now.
The ``from`` Keyword
--------------------
.. index:: ! from
.. index::
single: module; from
The ``import`` keyword makes every data value and function in a module
available for use. However, if we only need a few of the items from a module,
we can use the ``from`` keyword to import only those items.
.. sourcecode:: Python
from module_name import item_name
``item_name`` refers to the specific function or variable that we want from the
module. If we want to import more than one item, we separate the names by
commas.
.. admonition:: Example
Compare the syntax and results from the following imports:
.. sourcecode:: Python
:linenos:
import string
print(string.punctuation)
print(string.ascii_letters)
**Console Output**
::
!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
Adding the ``from`` keyword:
.. sourcecode:: Python
:linenos:
from string import punctuation
print(punctuation)
print(ascii_letters)
**Console Output**
::
!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~
Traceback (most recent call last):
File "main.py", line 4, in
print(ascii_letters)
NameError: name 'ascii_letters' is not defined
Note that when we combine ``from ... import``, we do NOT need to use dot
notation. We can call the variable or function directly by its name. Also note
that ``ascii_letters`` results in a ``NameError``, because that data was not
imported from the ``string`` module in line 1.
The ``as`` Keyword
------------------
.. index::
single: module; as
Python gives us a way to rename the items we import by including the ``as``
keyword as part of the ``import`` statement:
.. sourcecode:: Python
import module_name as new_name
from module_name import item_name as new_name
Try It!
-------
#. Using the clues in the code below, import the modules required to make
the program work:
.. raw:: html
*Challenge*: Modify the code to replace one ``import`` statement with
``from module_name import function_name``.
#. Using the clues in the code below, rename the ``turtle`` module to make
the code work:
.. raw:: html