Libraries

Overview

Teaching: 6 min
Exercises: 5 min

Questions

• How can I use software that other people have written?

• How can I find out what that software does?

Objectives

• Explain what software libraries are and why programmers create and use them.

• Write programs that import and use modules from Python’s standard library.

• Find and read documentation for the standard library interactively (in the interpreter) and online.

Most of the power of a programming language is in its libraries.

• A library is a collection of files (called modules) that contains functions for use by other programs.
  • May also contain data values (e.g., numerical constants) and other things.
  • Library’s contents are supposed to be related, but there’s no way to enforce that.
• The Python standard library is an extensive suite of modules that comes with Python itself.
• Many additional libraries are available from PyPI (the Python Package Index).

Libraries and modules

A library is a collection of modules, but the terms are often used interchangeably, especially since many libraries only consist of a single module, so don’t worry if you mix them.

A program must import a library module before using it.

• Use import to load a library module into a program’s memory.
• Then refer to things from the module as module_name.thing_name.
  • Python uses . to mean “part of”.
• Using math, one of the modules in the standard library:

import math

print('pi is', math.pi)
print('cos(pi) is', math.cos(math.pi))

pi is 3.141592653589793
cos(pi) is -1.0

• Have to refer to each item with the module’s name.
  • math.cos(pi) won’t work: the reference to pi doesn’t somehow “inherit” the function’s reference to math.

Use help to learn about the contents of a library module.

• Works just like help for a function.

help(math)

Help on module math:

NAME
    math

MODULE REFERENCE
    http://docs.python.org/3/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(x, /)
        Return the arc cosine (measured in radians) of x.
⋮ ⋮ ⋮

Import specific items from a library module to shorten programs.

• Use from ... import ... to load only specific items from a library module.
• Then refer to them directly without library name as prefix.

from math import cos, pi

print('cos(pi) is', cos(pi))

cos(pi) is -1.0

Create an alias for a library module when importing it to shorten programs.

• Use import ... as ... to give a library a short alias while importing it.
• Then refer to items in the library using that shortened name.

import math as m

print('cos(pi) is', m.cos(m.pi))

cos(pi) is -1.0

• Commonly used for libraries that are frequently used or have long names.
  • E.g., the matplotlib plotting library is often aliased as mpl.
• But can make programs harder to understand, since readers must learn your program’s aliases.

When Is Help Available?

When a colleague of yours types help(math), Python reports an error:

NameError: name 'math' is not defined

What has your colleague forgotten to do?

Solution

Importing the math module (import math)

Importing Specific Items

1. Fill in the blanks so that the program below prints 90.0.
2. Do you find this version easier to read than preceding ones?
3. Why wouldn’t programmers always use this form of import?

____ math import ____, ____
angle = degrees(pi / 2)
print(angle)

Solution

from math import degrees, pi
angle = degrees(pi / 2)
print(angle)

Most likely you find this version easier to read since it’s less dense. The main reason not to use this form of import is to avoid name clashes. For instance, you wouldn’t import degrees this way if you also wanted to use the name degrees for a variable or function of your own. Or if you were to also import a function named degrees from another library.

Key Points

• Most of the power of a programming language is in its libraries.

• A program must import a library module in order to use it.

• Use help to learn about the contents of a library module.

• Import specific items from a library to shorten programs.

• Create an alias for a library when importing it to shorten programs.