8.1 Syntax Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

61
8.2 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
8.3 Handling Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
8.4 Raising Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
8.5 User-defined Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
8.6 Defining Clean-up Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
8.7 Predefined Clean-up Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

9 Classes 69
9.1 A Word About Names and Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
9.2 Python Scopes and Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
9.3 A First Look at Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
9.4 Random Remarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
9.5 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
9.6 Private Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
9.7 Odds and Ends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
9.8 Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
9.9 Generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
9.10 Generator Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

10 Brief Tour of the Standard Library 83

10.1 Operating System Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
10.2 File Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
10.3 Command Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
10.4 Error Output Redirection and Program Termination . . . . . . . . . . . . . . . . . . . . . . . 84
10.5 String Pattern Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
10.6 Mathematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
10.7 Internet Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
10.8 Dates and Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
10.9 Data Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
10.10 Performance Measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
10.11 Quality Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
10.12 Batteries Included . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

11 Brief Tour of the Standard Library — Part II 89

11.1 Output Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
11.2 Templating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
11.3 Working with Binary Data Record Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
11.4 Multi-threading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
11.5 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
11.6 Weak References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
11.7 Tools for Working with Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
11.8 Decimal Floating Point Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

12 Virtual Environments and Packages 97

12.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
12.2 Creating Virtual Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
12.3 Managing Packages with pip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

13 What Now? 101

14 Interactive Input Editing and History Substitution 103

14.1 Tab Completion and History Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
14.2 Alternatives to the Interactive Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

ii
iv
Python Tutorial, Release 3.7.0

2 CONTENTS
Python Tutorial, Release 3.7.0

are really hooked, you can link the Python interpreter into an application written in C and use it as an
extension or command language for that application.
By the way, the language is named after the BBC show “Monty Python’s Flying Circus” and has nothing
to do with reptiles. Making references to Monty Python skits in documentation is not only allowed, it is
encouraged!
Now that you are all excited about Python, you’ll want to examine it in some more detail. Since the best
way to learn a language is to use it, the tutorial invites you to play with the Python interpreter as you read.
In the next chapter, the mechanics of using the interpreter are explained. This is rather mundane information,
but essential for trying out the examples shown later.
The rest of the tutorial introduces various features of the Python language and system through examples,
beginning with simple expressions, statements and data types, through functions and modules, and finally
touching upon advanced concepts like exceptions and user-defined classes.

4 Chapter 1. Whetting Your Appetite

Python Tutorial, Release 3.7.0

All command line options are described in using-on-general.

2.1.1 Argument Passing

When known to the interpreter, the script name and additional arguments thereafter are turned into a list
of strings and assigned to the argv variable in the sys module. You can access this list by executing import
sys. The length of the list is at least one; when no script and no arguments are given, sys.argv[0] is an
empty string. When the script name is given as '-' (meaning standard input), sys.argv[0] is set to '-'.
When -c command is used, sys.argv[0] is set to '-c'. When -m module is used, sys.argv[0] is set to
the full name of the located module. Options found after -c command or -m module are not consumed by
the Python interpreter’s option processing but left in sys.argv for the command or module to handle.

2.1.2 Interactive Mode

When commands are read from a tty, the interpreter is said to be in interactive mode. In this mode it prompts
for the next command with the primary prompt, usually three greater-than signs (>>>); for continuation lines
it prompts with the secondary prompt, by default three dots (...). The interpreter prints a welcome message
stating its version number and a copyright notice before printing the first prompt:

$ python3.7
Python 3.7 (default, Sep 16 2015, 09:25:04)
[GCC 4.8.2] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

Continuation lines are needed when entering a multi-line construct. As an example, take a look at this if
statement:

>>> the_world_is_flat = True

>>> if the_world_is_flat:
... print("Be careful not to fall off!")
...
Be careful not to fall off!

For more on interactive mode, see Interactive Mode.

2.2 The Interpreter and Its Environment

2.2.1 Source Code Encoding

By default, Python source files are treated as encoded in UTF-8. In that encoding, characters of most
languages in the world can be used simultaneously in string literals, identifiers and comments — although
the standard library only uses ASCII characters for identifiers, a convention that any portable code should
follow. To display all these characters properly, your editor must recognize that the file is UTF-8, and it
must use a font that supports all the characters in the file.
To declare an encoding other than the default one, a special comment line should be added as the first line
of the file. The syntax is as follows:

# -*- coding: encoding -*-

where encoding is one of the valid codecs supported by Python.

6 Chapter 2. Using the Python Interpreter

Python Tutorial, Release 3.7.0

8 Chapter 2. Using the Python Interpreter

Python Tutorial, Release 3.7.0

Division (/) always returns a float. To do floor division and get an integer result (discarding any fractional
result) you can use the // operator; to calculate the remainder you can use %:

>>> 17 / 3 # classic division returns a float

5.666666666666667
>>>
>>> 17 // 3 # floor division discards the fractional part
5
>>> 17 % 3 # the % operator returns the remainder of the division
2
>>> 5 * 3 + 2 # result * divisor + remainder
17

With Python, it is possible to use the ** operator to calculate powers1 :

>>> 5 ** 2 # 5 squared
25
>>> 2 ** 7 # 2 to the power of 7
128

The equal sign (=) is used to assign a value to a variable. Afterwards, no result is displayed before the next
interactive prompt:

>>> width = 20
>>> height = 5 * 9
>>> width * height
900

If a variable is not “defined” (assigned a value), trying to use it will give you an error:

>>> n # try to access an undefined variable

Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'n' is not defined

There is full support for floating point; operators with mixed type operands convert the integer operand to
floating point:

>>> 4 * 3.75 - 1
14.0

In interactive mode, the last printed expression is assigned to the variable _. This means that when you are
using Python as a desk calculator, it is somewhat easier to continue calculations, for example:

>>> tax = 12.5 / 100

>>> price = 100.50
>>> price * tax
12.5625
>>> price + _
113.0625
>>> round(_, 2)
113.06

This variable should be treated as read-only by the user. Don’t explicitly assign a value to it — you
would create an independent local variable with the same name masking the built-in variable with its magic
behavior.
1 Since ** has higher precedence than -, -3**2 will be interpreted as -(3**2) and thus result in -9. To avoid this and get

9, you can use (-3)**2.

10 Chapter 3. An Informal Introduction to Python

Python Tutorial, Release 3.7.0

print("""\
Usage: thingy [OPTIONS]
-h Display this usage message
-H hostname Hostname to connect to
""")

produces the following output (note that the initial newline is not included):

Usage: thingy [OPTIONS]

-h Display this usage message
-H hostname Hostname to connect to

Strings can be concatenated (glued together) with the + operator, and repeated with *:

>>> # 3 times 'un', followed by 'ium'

>>> 3 * 'un' + 'ium'
'unununium'

Two or more string literals (i.e. the ones enclosed between quotes) next to each other are automatically
concatenated.

>>> 'Py' 'thon'

'Python'

This feature is particularly useful when you want to break long strings:

>>> text = ('Put several strings within parentheses '

... 'to have them joined together.')
>>> text
'Put several strings within parentheses to have them joined together.'

This only works with two literals though, not with variables or expressions:

>>> prefix = 'Py'

>>> prefix 'thon' # can't concatenate a variable and a string literal
...
SyntaxError: invalid syntax
>>> ('un' * 3) 'ium'
...
SyntaxError: invalid syntax

If you want to concatenate variables or a variable and a literal, use +:

>>> prefix + 'thon'

'Python'

Strings can be indexed (subscripted), with the first character having index 0. There is no separate character
type; a character is simply a string of size one:

>>> word = 'Python'

>>> word[0] # character in position 0
'P'
>>> word[5] # character in position 5
'n'

Indices may also be negative numbers, to start counting from the right:

12 Chapter 3. An Informal Introduction to Python

Python Tutorial, Release 3.7.0

However, out of range slice indexes are handled gracefully when used for slicing:
>>> word[4:42]
'on'
>>> word[42:]
''

Python strings cannot be changed — they are immutable. Therefore, assigning to an indexed position in the
string results in an error:
>>> word[0] = 'J'
...
TypeError: 'str' object does not support item assignment
>>> word[2:] = 'py'
...
TypeError: 'str' object does not support item assignment

If you need a different string, you should create a new one:

>>> 'J' + word[1:]
'Jython'
>>> word[:2] + 'py'
'Pypy'

The built-in function len() returns the length of a string:

>>> s = 'supercalifragilisticexpialidocious'
>>> len(s)
34

See also:
textseq Strings are examples of sequence types, and support the common operations supported by such
types.
string-methods Strings support a large number of methods for basic transformations and searching.
f-strings String literals that have embedded expressions.
formatstrings Information about string formatting with str.format().
old-string-formatting The old formatting operations invoked when strings are the left operand of the %
operator are described in more detail here.

3.1.3 Lists
Python knows a number of compound data types, used to group together other values. The most versatile
is the list, which can be written as a list of comma-separated values (items) between square brackets. Lists
might contain items of different types, but usually the items all have the same type.
>>> squares = [1, 4, 9, 16, 25]
>>> squares
[1, 4, 9, 16, 25]

Like strings (and all other built-in sequence type), lists can be indexed and sliced:
>>> squares[0] # indexing returns the item
1
>>> squares[-1]
(continues on next page)

14 Chapter 3. An Informal Introduction to Python

Python Tutorial, Release 3.7.0

>>> a = ['a', 'b', 'c']

>>> n = [1, 2, 3]
>>> x = [a, n]
>>> x
[['a', 'b', 'c'], [1, 2, 3]]
>>> x[0]
['a', 'b', 'c']
>>> x[0][1]
'b'

3.2 First Steps Towards Programming

Of course, we can use Python for more complicated tasks than adding two and two together. For instance,
we can write an initial sub-sequence of the Fibonacci series as follows:

>>> # Fibonacci series:

... # the sum of two elements defines the next
... a, b = 0, 1
>>> while a < 10:
... print(a)
... a, b = b, a+b
...
0
1
1
2
3
5
8

This example introduces several new features.

• The first line contains a multiple assignment: the variables a and b simultaneously get the new values
0 and 1. On the last line this is used again, demonstrating that the expressions on the right-hand side
are all evaluated first before any of the assignments take place. The right-hand side expressions are
evaluated from the left to the right.
• The while loop executes as long as the condition (here: a < 10) remains true. In Python, like in C,
any non-zero integer value is true; zero is false. The condition may also be a string or list value, in
fact any sequence; anything with a non-zero length is true, empty sequences are false. The test used
in the example is a simple comparison. The standard comparison operators are written the same as in
C: < (less than), > (greater than), == (equal to), <= (less than or equal to), >= (greater than or equal
to) and != (not equal to).
• The body of the loop is indented: indentation is Python’s way of grouping statements. At the interactive
prompt, you have to type a tab or space(s) for each indented line. In practice you will prepare more
complicated input for Python with a text editor; all decent text editors have an auto-indent facility.
When a compound statement is entered interactively, it must be followed by a blank line to indicate
completion (since the parser cannot guess when you have typed the last line). Note that each line
within a basic block must be indented by the same amount.
• The print() function writes the value of the argument(s) it is given. It differs from just writing
the expression you want to write (as we did earlier in the calculator examples) in the way it handles
multiple arguments, floating point quantities, and strings. Strings are printed without quotes, and a
space is inserted between items, so you can format things nicely, like this:

16 Chapter 3. An Informal Introduction to Python

Python Tutorial, Release 3.7.0

18 Chapter 3. An Informal Introduction to Python

Python Tutorial, Release 3.7.0

If you need to modify the sequence you are iterating over while inside the loop (for example to duplicate
selected items), it is recommended that you first make a copy. Iterating over a sequence does not implicitly
make a copy. The slice notation makes this especially convenient:

>>> for w in words[:]: # Loop over a slice copy of the entire list.
... if len(w) > 6:
... words.insert(0, w)
...
>>> words
['defenestrate', 'cat', 'window', 'defenestrate']

With for w in words:, the example would attempt to create an infinite list, inserting defenestrate over
and over again.

4.3 The range() Function

If you do need to iterate over a sequence of numbers, the built-in function range() comes in handy. It
generates arithmetic progressions:

>>> for i in range(5):

... print(i)
...
0
1
2
3
4

The given end point is never part of the generated sequence; range(10) generates 10 values, the legal indices
for items of a sequence of length 10. It is possible to let the range start at another number, or to specify a
different increment (even negative; sometimes this is called the ‘step’):

range(5, 10)
5, 6, 7, 8, 9

range(0, 10, 3)
0, 3, 6, 9

range(-10, -100, -30)

-10, -40, -70

To iterate over the indices of a sequence, you can combine range() and len() as follows:

>>> a = ['Mary', 'had', 'a', 'little', 'lamb']

>>> for i in range(len(a)):
... print(i, a[i])
...
0 Mary
1 had
2 a
3 little
4 lamb

In most such cases, however, it is convenient to use the enumerate() function, see Looping Techniques.
A strange thing happens if you just print a range:

20 Chapter 4. More Control Flow Tools

Python Tutorial, Release 3.7.0

(continued from previous page)

Found a number 3
Found an even number 4
Found a number 5
Found an even number 6
Found a number 7
Found an even number 8
Found a number 9

4.5 pass Statements

The pass statement does nothing. It can be used when a statement is required syntactically but the program
requires no action. For example:

>>> while True:

... pass # Busy-wait for keyboard interrupt (Ctrl+C)
...

This is commonly used for creating minimal classes:

>>> class MyEmptyClass:

... pass
...

Another place pass can be used is as a place-holder for a function or conditional body when you are working
on new code, allowing you to keep thinking at a more abstract level. The pass is silently ignored:

>>> def initlog(*args):

... pass # Remember to implement this!
...

4.6 Defining Functions

We can create a function that writes the Fibonacci series to an arbitrary boundary:

>>> def fib(n): # write Fibonacci series up to n

... """Print a Fibonacci series up to n."""
... a, b = 0, 1
... while a < n:
... print(a, end=' ')
... a, b = b, a+b
... print()
...
>>> # Now call the function we just defined:
... fib(2000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597

The keyword def introduces a function definition. It must be followed by the function name and the
parenthesized list of formal parameters. The statements that form the body of the function start at the next
line, and must be indented.
The first statement of the function body can optionally be a string literal; this string literal is the function’s
documentation string, or docstring. (More about docstrings can be found in the section Documentation

22 Chapter 4. More Control Flow Tools

Python Tutorial, Release 3.7.0

expression), and methodname is the name of a method that is defined by the object’s type. Different
types define different methods. Methods of different types may have the same name without causing
ambiguity. (It is possible to define your own object types and methods, using classes, see Classes) The
method append() shown in the example is defined for list objects; it adds a new element at the end of
the list. In this example it is equivalent to result = result + [a], but more efficient.

4.7 More on Defining Functions

It is also possible to define functions with a variable number of arguments. There are three forms, which
can be combined.

4.7.1 Default Argument Values

The most useful form is to specify a default value for one or more arguments. This creates a function that
can be called with fewer arguments than it is defined to allow. For example:

def ask_ok(prompt, retries=4, reminder='Please try again!'):

while True:
ok = input(prompt)
if ok in ('y', 'ye', 'yes'):
return True
if ok in ('n', 'no', 'nop', 'nope'):
return False
retries = retries - 1
if retries < 0:
raise ValueError('invalid user response')
print(reminder)

This function can be called in several ways:

• giving only the mandatory argument: ask_ok('Do you really want to quit?')
• giving one of the optional arguments: ask_ok('OK to overwrite the file?', 2)
• or even giving all arguments: ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or
no!')
This example also introduces the in keyword. This tests whether or not a sequence contains a certain value.
The default values are evaluated at the point of function definition in the defining scope, so that

i = 5

def f(arg=i):
print(arg)

i = 6
f()

will print 5.
Important warning: The default value is evaluated only once. This makes a difference when the default is
a mutable object such as a list, dictionary, or instances of most classes. For example, the following function
accumulates the arguments passed to it on subsequent calls:

24 Chapter 4. More Control Flow Tools

Python Tutorial, Release 3.7.0

>>> def function(a):

... pass
...
>>> function(0, a=0)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: function() got multiple values for keyword argument 'a'

When a final formal parameter of the form **name is present, it receives a dictionary (see typesmapping)
containing all keyword arguments except for those corresponding to a formal parameter. This may be
combined with a formal parameter of the form *name (described in the next subsection) which receives
a tuple containing the positional arguments beyond the formal parameter list. (*name must occur before
**name.) For example, if we define a function like this:

def cheeseshop(kind, *arguments, **keywords):

print("-- Do you have any", kind, "?")
print("-- I'm sorry, we're all out of", kind)
for arg in arguments:
print(arg)
print("-" * 40)
for kw in keywords:
print(kw, ":", keywords[kw])

It could be called like this:

cheeseshop("Limburger", "It's very runny, sir.",

"It's really very, VERY runny, sir.",
shopkeeper="Michael Palin",
client="John Cleese",
sketch="Cheese Shop Sketch")

and of course it would print:

-- Do you have any Limburger ?

-- I'm sorry, we're all out of Limburger
It's very runny, sir.
It's really very, VERY runny, sir.
----------------------------------------
shopkeeper : Michael Palin
client : John Cleese
sketch : Cheese Shop Sketch

Note that the order in which the keyword arguments are printed is guaranteed to match the order in which
they were provided in the function call.

4.7.3 Arbitrary Argument Lists

Finally, the least frequently used option is to specify that a function can be called with an arbitrary number
of arguments. These arguments will be wrapped up in a tuple (see Tuples and Sequences). Before the
variable number of arguments, zero or more normal arguments may occur.

def write_multiple_items(file, separator, *args):

file.write(separator.join(args))

Normally, these variadic arguments will be last in the list of formal parameters, because they scoop up
all remaining input arguments that are passed to the function. Any formal parameters which occur after

26 Chapter 4. More Control Flow Tools

Python Tutorial, Release 3.7.0

>>> pairs = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
>>> pairs.sort(key=lambda pair: pair[1])
>>> pairs
[(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')]

4.7.6 Documentation Strings

Here are some conventions about the content and formatting of documentation strings.
The first line should always be a short, concise summary of the object’s purpose. For brevity, it should
not explicitly state the object’s name or type, since these are available by other means (except if the name
happens to be a verb describing a function’s operation). This line should begin with a capital letter and end
with a period.
If there are more lines in the documentation string, the second line should be blank, visually separating the
summary from the rest of the description. The following lines should be one or more paragraphs describing
the object’s calling conventions, its side effects, etc.
The Python parser does not strip indentation from multi-line string literals in Python, so tools that process
documentation have to strip indentation if desired. This is done using the following convention. The
first non-blank line after the first line of the string determines the amount of indentation for the entire
documentation string. (We can’t use the first line since it is generally adjacent to the string’s opening quotes
so its indentation is not apparent in the string literal.) Whitespace “equivalent” to this indentation is then
stripped from the start of all lines of the string. Lines that are indented less should not occur, but if they
occur all their leading whitespace should be stripped. Equivalence of whitespace should be tested after
expansion of tabs (to 8 spaces, normally).
Here is an example of a multi-line docstring:
>>> def my_function():
... """Do nothing, but document it.
...
... No, really, it doesn't do anything.
... """
... pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.

No, really, it doesn't do anything.

4.7.7 Function Annotations

Function annotations are completely optional metadata information about the types used by user-defined
functions (see PEP 3107 and PEP 484 for more information).
Annotations are stored in the __annotations__ attribute of the function as a dictionary and have no effect
on any other part of the function. Parameter annotations are defined by a colon after the parameter name,
followed by an expression evaluating to the value of the annotation. Return annotations are defined by a
literal ->, followed by an expression, between the parameter list and the colon denoting the end of the def
statement. The following example has a positional argument, a keyword argument, and the return value
annotated:
>>> def f(ham: str, eggs: str = 'eggs') -> str:
... print("Annotations:", f.__annotations__)
(continues on next page)

28 Chapter 4. More Control Flow Tools

Python Tutorial, Release 3.7.0

30 Chapter 4. More Control Flow Tools

Python Tutorial, Release 3.7.0

list.reverse()
Reverse the elements of the list in place.
list.copy()
Return a shallow copy of the list. Equivalent to a[:].
An example that uses most of the list methods:

>>> fruits = ['orange', 'apple', 'pear', 'banana', 'kiwi', 'apple', 'banana']

>>> fruits.count('apple')
2
>>> fruits.count('tangerine')
0
>>> fruits.index('banana')
3
>>> fruits.index('banana', 4) # Find next banana starting a position 4
6
>>> fruits.reverse()
>>> fruits
['banana', 'apple', 'kiwi', 'banana', 'pear', 'apple', 'orange']
>>> fruits.append('grape')
>>> fruits
['banana', 'apple', 'kiwi', 'banana', 'pear', 'apple', 'orange', 'grape']
>>> fruits.sort()
>>> fruits
['apple', 'apple', 'banana', 'banana', 'grape', 'kiwi', 'orange', 'pear']
>>> fruits.pop()
'pear'

You might have noticed that methods like insert, remove or sort that only modify the list have no return
value printed – they return the default None.1 This is a design principle for all mutable data structures in
Python.

5.1.1 Using Lists as Stacks

The list methods make it very easy to use a list as a stack, where the last element added is the first element
retrieved (“last-in, first-out”). To add an item to the top of the stack, use append(). To retrieve an item
from the top of the stack, use pop() without an explicit index. For example:

>>> stack = [3, 4, 5]

>>> stack.append(6)
>>> stack.append(7)
>>> stack
[3, 4, 5, 6, 7]
>>> stack.pop()
7
>>> stack
[3, 4, 5, 6]
>>> stack.pop()
6
>>> stack.pop()
5
>>> stack
[3, 4]

1 Other languages may return the mutated object, which allows method chaining, such as
d->insert("a")->remove("b")->sort();.

32 Chapter 5. Data Structures

Python Tutorial, Release 3.7.0

>>> combs = []
>>> for x in [1,2,3]:
... for y in [3,1,4]:
... if x != y:
... combs.append((x, y))
...
>>> combs
[(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]

Note how the order of the for and if statements is the same in both these snippets.
If the expression is a tuple (e.g. the (x, y) in the previous example), it must be parenthesized.
>>> vec = [-4, -2, 0, 2, 4]
>>> # create a new list with the values doubled
>>> [x*2 for x in vec]
[-8, -4, 0, 4, 8]
>>> # filter the list to exclude negative numbers
>>> [x for x in vec if x >= 0]
[0, 2, 4]
>>> # apply a function to all the elements
>>> [abs(x) for x in vec]
[4, 2, 0, 2, 4]
>>> # call a method on each element
>>> freshfruit = [' banana', ' loganberry ', 'passion fruit ']
>>> [weapon.strip() for weapon in freshfruit]
['banana', 'loganberry', 'passion fruit']
>>> # create a list of 2-tuples like (number, square)
>>> [(x, x**2) for x in range(6)]
[(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25)]
>>> # the tuple must be parenthesized, otherwise an error is raised
>>> [x, x**2 for x in range(6)]
File "<stdin>", line 1, in <module>
[x, x**2 for x in range(6)]
^
SyntaxError: invalid syntax
>>> # flatten a list using a listcomp with two 'for'
>>> vec = [[1,2,3], [4,5,6], [7,8,9]]
>>> [num for elem in vec for num in elem]
[1, 2, 3, 4, 5, 6, 7, 8, 9]

List comprehensions can contain complex expressions and nested functions:

>>> from math import pi
>>> [str(round(pi, i)) for i in range(1, 6)]
['3.1', '3.14', '3.142', '3.1416', '3.14159']

5.1.4 Nested List Comprehensions

The initial expression in a list comprehension can be any arbitrary expression, including another list com-
prehension.
Consider the following example of a 3x4 matrix implemented as a list of 3 lists of length 4:
>>> matrix = [
... [1, 2, 3, 4],
... [5, 6, 7, 8],
(continues on next page)

34 Chapter 5. Data Structures

Python Tutorial, Release 3.7.0

(continued from previous page)

>>> a
[]

del can also be used to delete entire variables:

>>> del a

Referencing the name a hereafter is an error (at least until another value is assigned to it). We’ll find other
uses for del later.

5.3 Tuples and Sequences

We saw that lists and strings have many common properties, such as indexing and slicing operations. They
are two examples of sequence data types (see typesseq). Since Python is an evolving language, other sequence
data types may be added. There is also another standard sequence data type: the tuple.
A tuple consists of a number of values separated by commas, for instance:
>>> t = 12345, 54321, 'hello!'
>>> t[0]
12345
>>> t
(12345, 54321, 'hello!')
>>> # Tuples may be nested:
... u = t, (1, 2, 3, 4, 5)
>>> u
((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
>>> # Tuples are immutable:
... t[0] = 88888
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: 'tuple' object does not support item assignment
>>> # but they can contain mutable objects:
... v = ([1, 2, 3], [3, 2, 1])
>>> v
([1, 2, 3], [3, 2, 1])

As you see, on output tuples are always enclosed in parentheses, so that nested tuples are interpreted
correctly; they may be input with or without surrounding parentheses, although often parentheses are
necessary anyway (if the tuple is part of a larger expression). It is not possible to assign to the individual
items of a tuple, however it is possible to create tuples which contain mutable objects, such as lists.
Though tuples may seem similar to lists, they are often used in different situations and for different purposes.
Tuples are immutable, and usually contain a heterogeneous sequence of elements that are accessed via
unpacking (see later in this section) or indexing (or even by attribute in the case of namedtuples). Lists are
mutable, and their elements are usually homogeneous and are accessed by iterating over the list.
A special problem is the construction of tuples containing 0 or 1 items: the syntax has some extra quirks to
accommodate these. Empty tuples are constructed by an empty pair of parentheses; a tuple with one item is
constructed by following a value with a comma (it is not sufficient to enclose a single value in parentheses).
Ugly, but effective. For example:
>>> empty = ()
>>> singleton = 'hello', # <-- note trailing comma
>>> len(empty)
(continues on next page)

36 Chapter 5. Data Structures

Python Tutorial, Release 3.7.0

5.5 Dictionaries

Another useful data type built into Python is the dictionary (see typesmapping). Dictionaries are sometimes
found in other languages as “associative memories” or “associative arrays”. Unlike sequences, which are
indexed by a range of numbers, dictionaries are indexed by keys, which can be any immutable type; strings
and numbers can always be keys. Tuples can be used as keys if they contain only strings, numbers, or tuples;
if a tuple contains any mutable object either directly or indirectly, it cannot be used as a key. You can’t use
lists as keys, since lists can be modified in place using index assignments, slice assignments, or methods like
append() and extend().
It is best to think of a dictionary as a set of key: value pairs, with the requirement that the keys are unique
(within one dictionary). A pair of braces creates an empty dictionary: {}. Placing a comma-separated
list of key:value pairs within the braces adds initial key:value pairs to the dictionary; this is also the way
dictionaries are written on output.
The main operations on a dictionary are storing a value with some key and extracting the value given the
key. It is also possible to delete a key:value pair with del. If you store using a key that is already in use,
the old value associated with that key is forgotten. It is an error to extract a value using a non-existent key.
Performing list(d) on a dictionary returns a list of all the keys used in the dictionary, in insertion order
(if you want it sorted, just use sorted(d) instead). To check whether a single key is in the dictionary, use
the in keyword.
Here is a small example using a dictionary:

>>> tel = {'jack': 4098, 'sape': 4139}

>>> tel['guido'] = 4127
>>> tel
{'jack': 4098, 'sape': 4139, 'guido': 4127}
>>> tel['jack']
4098
>>> del tel['sape']
>>> tel['irv'] = 4127
>>> tel
{'jack': 4098, 'guido': 4127, 'irv': 4127}
>>> list(tel)
['jack', 'guido', 'irv']
>>> sorted(tel)
['guido', 'irv', 'jack']
>>> 'guido' in tel
True
>>> 'jack' not in tel
False

The dict() constructor builds dictionaries directly from sequences of key-value pairs:

>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])

{'sape': 4139, 'guido': 4127, 'jack': 4098}

In addition, dict comprehensions can be used to create dictionaries from arbitrary key and value expressions:

>>> {x: x**2 for x in (2, 4, 6)}

{2: 4, 4: 16, 6: 36}

When the keys are simple strings, it is sometimes easier to specify pairs using keyword arguments:

>>> dict(sape=4139, guido=4127, jack=4098)

{'sape': 4139, 'guido': 4127, 'jack': 4098}

38 Chapter 5. Data Structures

Python Tutorial, Release 3.7.0

It is sometimes tempting to change a list while you are looping over it; however, it is often simpler and safer
to create a new list instead.

>>> import math

>>> raw_data = [56.2, float('NaN'), 51.7, 55.3, 52.5, float('NaN'), 47.8]
>>> filtered_data = []
>>> for value in raw_data:
... if not math.isnan(value):
... filtered_data.append(value)
...
>>> filtered_data
[56.2, 51.7, 55.3, 52.5, 47.8]

5.7 More on Conditions

The conditions used in while and if statements can contain any operators, not just comparisons.
The comparison operators in and not in check whether a value occurs (does not occur) in a sequence. The
operators is and is not compare whether two objects are really the same object; this only matters for
mutable objects like lists. All comparison operators have the same priority, which is lower than that of all
numerical operators.
Comparisons can be chained. For example, a < b == c tests whether a is less than b and moreover b equals
c.
Comparisons may be combined using the Boolean operators and and or, and the outcome of a comparison
(or of any other Boolean expression) may be negated with not. These have lower priorities than comparison
operators; between them, not has the highest priority and or the lowest, so that A and not B or C is
equivalent to (A and (not B)) or C. As always, parentheses can be used to express the desired composition.
The Boolean operators and and or are so-called short-circuit operators: their arguments are evaluated from
left to right, and evaluation stops as soon as the outcome is determined. For example, if A and C are true
but B is false, A and B and C does not evaluate the expression C. When used as a general value and not as
a Boolean, the return value of a short-circuit operator is the last evaluated argument.
It is possible to assign the result of a comparison or other Boolean expression to a variable. For example,

>>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'

>>> non_null = string1 or string2 or string3
>>> non_null
'Trondheim'

Note that in Python, unlike C, assignment cannot occur inside expressions. C programmers may grumble
about this, but it avoids a common class of problems encountered in C programs: typing = in an expression
when == was intended.

5.8 Comparing Sequences and Other Types

Sequence objects may be compared to other objects with the same sequence type. The comparison uses lex-
icographical ordering: first the first two items are compared, and if they differ this determines the outcome
of the comparison; if they are equal, the next two items are compared, and so on, until either sequence is
exhausted. If two items to be compared are themselves sequences of the same type, the lexicographical com-
parison is carried out recursively. If all items of two sequences compare equal, the sequences are considered
equal. If one sequence is an initial sub-sequence of the other, the shorter sequence is the smaller (lesser)

40 Chapter 5. Data Structures

Python Tutorial, Release 3.7.0

42 Chapter 5. Data Structures

Python Tutorial, Release 3.7.0

(continued from previous page)

[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
>>> fibo.__name__
'fibo'

If you intend to use a function often you can assign it to a local name:

>>> fib = fibo.fib

>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

6.1 More on Modules

A module can contain executable statements as well as function definitions. These statements are intended
to initialize the module. They are executed only the first time the module name is encountered in an import
statement.1 (They are also run if the file is executed as a script.)
Each module has its own private symbol table, which is used as the global symbol table by all functions
defined in the module. Thus, the author of a module can use global variables in the module without
worrying about accidental clashes with a user’s global variables. On the other hand, if you know what you
are doing you can touch a module’s global variables with the same notation used to refer to its functions,
modname.itemname.
Modules can import other modules. It is customary but not required to place all import statements at the
beginning of a module (or script, for that matter). The imported module names are placed in the importing
module’s global symbol table.
There is a variant of the import statement that imports names from a module directly into the importing
module’s symbol table. For example:

>>> from fibo import fib, fib2

>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

This does not introduce the module name from which the imports are taken in the local symbol table (so in
the example, fibo is not defined).
There is even a variant to import all names that a module defines:

>>> from fibo import *

>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

This imports all names except those beginning with an underscore (_). In most cases Python programmers
do not use this facility since it introduces an unknown set of names into the interpreter, possibly hiding some
things you have already defined.
Note that in general the practice of importing * from a module or package is frowned upon, since it often
causes poorly readable code. However, it is okay to use it to save typing in interactive sessions.
If the module name is followed by as, then the name following as is bound directly to the imported module.

>>> import fibo as fib

>>> fib.fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

1 In fact function definitions are also ‘statements’ that are ‘executed’; the execution of a module-level function definition

enters the function name in the module’s global symbol table.

44 Chapter 6. Modules
Python Tutorial, Release 3.7.0

search path.

After initialization, Python programs can modify sys.path. The directory containing the script being run
is placed at the beginning of the search path, ahead of the standard library path. This means that scripts in
that directory will be loaded instead of modules of the same name in the library directory. This is an error
unless the replacement is intended. See section Standard Modules for more information.

6.1.3 “Compiled” Python files

To speed up loading modules, Python caches the compiled version of each module in the __pycache__
directory under the name module.version.pyc, where the version encodes the format of the compiled file;
it generally contains the Python version number. For example, in CPython release 3.3 the compiled version of
spam.py would be cached as __pycache__/spam.cpython-33.pyc. This naming convention allows compiled
modules from different releases and different versions of Python to coexist.
Python checks the modification date of the source against the compiled version to see if it’s out of date
and needs to be recompiled. This is a completely automatic process. Also, the compiled modules are
platform-independent, so the same library can be shared among systems with different architectures.
Python does not check the cache in two circumstances. First, it always recompiles and does not store the
result for the module that’s loaded directly from the command line. Second, it does not check the cache if
there is no source module. To support a non-source (compiled only) distribution, the compiled module must
be in the source directory, and there must not be a source module.
Some tips for experts:
• You can use the -O or -OO switches on the Python command to reduce the size of a compiled module.
The -O switch removes assert statements, the -OO switch removes both assert statements and __doc__
strings. Since some programs may rely on having these available, you should only use this option if
you know what you’re doing. “Optimized” modules have an opt- tag and are usually smaller. Future
releases may change the effects of optimization.
• A program doesn’t run any faster when it is read from a .pyc file than when it is read from a .py file;
the only thing that’s faster about .pyc files is the speed with which they are loaded.
• The module compileall can create .pyc files for all modules in a directory.
• There is more detail on this process, including a flow chart of the decisions, in PEP 3147.

6.2 Standard Modules

Python comes with a library of standard modules, described in a separate document, the Python Library
Reference (“Library Reference” hereafter). Some modules are built into the interpreter; these provide access
to operations that are not part of the core of the language but are nevertheless built in, either for efficiency
or to provide access to operating system primitives such as system calls. The set of such modules is a
configuration option which also depends on the underlying platform. For example, the winreg module is
only provided on Windows systems. One particular module deserves some attention: sys, which is built
into every Python interpreter. The variables sys.ps1 and sys.ps2 define the strings used as primary and
secondary prompts:

>>> import sys

>>> sys.ps1
'>>> '
>>> sys.ps2
'... '
(continues on next page)

46 Chapter 6. Modules
Python Tutorial, Release 3.7.0

>>> import builtins

>>> dir(builtins)
['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning',
'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError',
'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning',
'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
'FileExistsError', 'FileNotFoundError', 'FloatingPointError',
'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',
'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError',
'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError',
'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented',
'NotImplementedError', 'OSError', 'OverflowError',
'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError',
'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning',
'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',
'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',
'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',
'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning',
'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__',
'__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs',
'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable',
'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits',
'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit',
'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr',
'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass',
'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview',
'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property',
'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice',
'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars',
'zip']

6.4 Packages
Packages are a way of structuring Python’s module namespace by using “dotted module names”. For example,
the module name A.B designates a submodule named B in a package named A. Just like the use of modules
saves the authors of different modules from having to worry about each other’s global variable names, the
use of dotted module names saves the authors of multi-module packages like NumPy or Pillow from having
to worry about each other’s module names.
Suppose you want to design a collection of modules (a “package”) for the uniform handling of sound files and
sound data. There are many different sound file formats (usually recognized by their extension, for example:
.wav, .aiff, .au), so you may need to create and maintain a growing collection of modules for the conversion
between the various file formats. There are also many different operations you might want to perform on
sound data (such as mixing, adding echo, applying an equalizer function, creating an artificial stereo effect),
so in addition you will be writing a never-ending stream of modules to perform these operations. Here’s a
possible structure for your package (expressed in terms of a hierarchical filesystem):

sound/ Top-level package

__init__.py Initialize the sound package
formats/ Subpackage for file format conversions
__init__.py
wavread.py
wavwrite.py
(continues on next page)

48 Chapter 6. Modules
Python Tutorial, Release 3.7.0

in the previous item.

6.4.1 Importing * From a Package

Now what happens when the user writes from sound.effects import *? Ideally, one would hope that this
somehow goes out to the filesystem, finds which submodules are present in the package, and imports them
all. This could take a long time and importing sub-modules might have unwanted side-effects that should
only happen when the sub-module is explicitly imported.
The only solution is for the package author to provide an explicit index of the package. The import statement
uses the following convention: if a package’s __init__.py code defines a list named __all__, it is taken to
be the list of module names that should be imported when from package import * is encountered. It is up
to the package author to keep this list up-to-date when a new version of the package is released. Package
authors may also decide not to support it, if they don’t see a use for importing * from their package. For
example, the file sound/effects/__init__.py could contain the following code:

__all__ = ["echo", "surround", "reverse"]

This would mean that from sound.effects import * would import the three named submodules of the
sound package.
If __all__ is not defined, the statement from sound.effects import * does not import all submodules from
the package sound.effects into the current namespace; it only ensures that the package sound.effects
has been imported (possibly running any initialization code in __init__.py) and then imports whatever
names are defined in the package. This includes any names defined (and submodules explicitly loaded) by
__init__.py. It also includes any submodules of the package that were explicitly loaded by previous import
statements. Consider this code:

import sound.effects.echo
import sound.effects.surround
from sound.effects import *

In this example, the echo and surround modules are imported in the current namespace because they are
defined in the sound.effects package when the from...import statement is executed. (This also works
when __all__ is defined.)
Although certain modules are designed to export only names that follow certain patterns when you use
import *, it is still considered bad practice in production code.
Remember, there is nothing wrong with using from Package import specific_submodule! In fact, this is
the recommended notation unless the importing module needs to use submodules with the same name from
different packages.

6.4.2 Intra-package References

When packages are structured into subpackages (as with the sound package in the example), you can use
absolute imports to refer to submodules of siblings packages. For example, if the module sound.filters.
vocoder needs to use the echo module in the sound.effects package, it can use from sound.effects
import echo.
You can also write relative imports, with the from module import name form of import statement. These
imports use leading dots to indicate the current and parent packages involved in the relative import. From
the surround module for example, you might use:

50 Chapter 6. Modules
Python Tutorial, Release 3.7.0

52 Chapter 6. Modules
Python Tutorial, Release 3.7.0

>>> s = 'Hello, world.'

>>> str(s)
'Hello, world.'
>>> repr(s)
"'Hello, world.'"
>>> str(1/7)
'0.14285714285714285'
>>> x = 10 * 3.25
>>> y = 200 * 200
>>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
>>> print(s)
The value of x is 32.5, and y is 40000...
>>> # The repr() of a string adds string quotes and backslashes:
... hello = 'hello, world\n'
>>> hellos = repr(hello)
>>> print(hellos)
'hello, world\n'
>>> # The argument to repr() may be any Python object:
... repr((x, y, ('spam', 'eggs')))
"(32.5, 40000, ('spam', 'eggs'))"

The string module contains a Template class that offers yet another way to substitute values into strings,
using placeholders like $x and replacing them with values from a dictionary, but offers much less control of
the formatting.

7.1.1 Formatted String Literals

Formatted string literals (also called f-strings for short) let you include the value of Python expressions inside
a string by prefixing the string with f or F and writing expressions as {expression}.
An optional format specifier can follow the expression. This allows greater control over how the value is
formatted. The following example rounds pi to three places after the decimal:

>>> import math

>>> print(f'The value of pi is approximately {math.pi:.3f}.')

Passing an integer after the ':' will cause that field to be a minimum number of characters wide. This is
useful for making columns line up.

>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}

>>> for name, phone in table.items():
... print(f'{name:10} ==> {phone:10d}')
...
Sjoerd ==> 4127
Jack ==> 4098
Dcab ==> 7678

Other modifiers can be used to convert the value before it is formatted. '!a' applies ascii(), '!s' applies
str(), and '!r' applies repr():

>>> animals = 'eels'

>>> print(f'My hovercraft is full of {animals}.')
My hovercraft is full of eels.
>>> print('My hovercraft is full of {animals !r}.')
My hovercraft is full of 'eels'.

For a reference on these format specifications, see the reference guide for the formatspec.

54 Chapter 7. Input and Output

Python Tutorial, Release 3.7.0

(continued from previous page)

6 36 216
7 49 343
8 64 512
9 81 729
10 100 1000

For a complete overview of string formatting with str.format(), see formatstrings.

7.1.3 Manual String Formatting

Here’s the same table of squares and cubes, formatted manually:

>>> for x in range(1, 11):

... print(repr(x).rjust(2), repr(x*x).rjust(3), end=' ')
... # Note use of 'end' on previous line
... print(repr(x*x*x).rjust(4))
...
1 1 1
2 4 8
3 9 27
4 16 64
5 25 125
6 36 216
7 49 343
8 64 512
9 81 729
10 100 1000

(Note that the one space between each column was added by the way print() works: it always adds spaces
between its arguments.)
The str.rjust() method of string objects right-justifies a string in a field of a given width by padding it
with spaces on the left. There are similar methods str.ljust() and str.center(). These methods do not
write anything, they just return a new string. If the input string is too long, they don’t truncate it, but
return it unchanged; this will mess up your column lay-out but that’s usually better than the alternative,
which would be lying about a value. (If you really want truncation you can always add a slice operation, as
in x.ljust(n)[:n].)
There is another method, str.zfill(), which pads a numeric string on the left with zeros. It understands
about plus and minus signs:

>>> '12'.zfill(5)
'00012'
>>> '-3.14'.zfill(7)
'-003.14'
>>> '3.14159265359'.zfill(5)
'3.14159265359'

7.1.4 Old string formatting

The % operator can also be used for string formatting. It interprets the left argument much like a sprintf()-
style format string to be applied to the right argument, and returns the string resulting from this formatting
operation. For example:

56 Chapter 7. Input and Output

Python Tutorial, Release 3.7.0

To read a file’s contents, call f.read(size), which reads some quantity of data and returns it as a string (in
text mode) or bytes object (in binary mode). size is an optional numeric argument. When size is omitted
or negative, the entire contents of the file will be read and returned; it’s your problem if the file is twice as
large as your machine’s memory. Otherwise, at most size bytes are read and returned. If the end of the file
has been reached, f.read() will return an empty string ('').
>>> f.read()
'This is the entire file.\n'
>>> f.read()
''

f.readline() reads a single line from the file; a newline character (\n) is left at the end of the string, and
is only omitted on the last line of the file if the file doesn’t end in a newline. This makes the return value
unambiguous; if f.readline() returns an empty string, the end of the file has been reached, while a blank
line is represented by '\n', a string containing only a single newline.
>>> f.readline()
'This is the first line of the file.\n'
>>> f.readline()
'Second line of the file\n'
>>> f.readline()
''

For reading lines from a file, you can loop over the file object. This is memory efficient, fast, and leads to
simple code:
>>> for line in f:
... print(line, end='')
...
This is the first line of the file.
Second line of the file

If you want to read all the lines of a file in a list you can also use list(f) or f.readlines().
f.write(string) writes the contents of string to the file, returning the number of characters written.
>>> f.write('This is a test\n')
15

Other types of objects need to be converted – either to a string (in text mode) or a bytes object (in binary
mode) – before writing them:
>>> value = ('the answer', 42)
>>> s = str(value) # convert the tuple to string
>>> f.write(s)
18

f.tell() returns an integer giving the file object’s current position in the file represented as number of bytes
from the beginning of the file when in binary mode and an opaque number when in text mode.
To change the file object’s position, use f.seek(offset, from_what). The position is computed from
adding offset to a reference point; the reference point is selected by the from_what argument. A from_what
value of 0 measures from the beginning of the file, 1 uses the current file position, and 2 uses the end of the
file as the reference point. from_what can be omitted and defaults to 0, using the beginning of the file as
the reference point.
>>> f = open('workfile', 'rb+')
>>> f.write(b'0123456789abcdef')
(continues on next page)

58 Chapter 7. Input and Output

Python Tutorial, Release 3.7.0

Contrary to JSON , pickle is a protocol which allows the serialization of arbitrarily complex Python objects.
As such, it is specific to Python and cannot be used to communicate with applications written in other
languages. It is also insecure by default: deserializing pickle data coming from an untrusted source can
execute arbitrary code, if the data was crafted by a skilled attacker.

60 Chapter 7. Input and Output

Python Tutorial, Release 3.7.0

The last line of the error message indicates what happened. Exceptions come in different types, and the
type is printed as part of the message: the types in the example are ZeroDivisionError, NameError and
TypeError. The string printed as the exception type is the name of the built-in exception that occurred.
This is true for all built-in exceptions, but need not be true for user-defined exceptions (although it is a
useful convention). Standard exception names are built-in identifiers (not reserved keywords).
The rest of the line provides detail based on the type of exception and what caused it.
The preceding part of the error message shows the context where the exception happened, in the form of
a stack traceback. In general it contains a stack traceback listing source lines; however, it will not display
lines read from standard input.
bltin-exceptions lists the built-in exceptions and their meanings.

8.3 Handling Exceptions

It is possible to write programs that handle selected exceptions. Look at the following example, which asks
the user for input until a valid integer has been entered, but allows the user to interrupt the program (using
Control-C or whatever the operating system supports); note that a user-generated interruption is signalled
by raising the KeyboardInterrupt exception.

>>> while True:

... try:
... x = int(input("Please enter a number: "))
... break
... except ValueError:
... print("Oops! That was no valid number. Try again...")
...

The try statement works as follows.

• First, the try clause (the statement(s) between the try and except keywords) is executed.
• If no exception occurs, the except clause is skipped and execution of the try statement is finished.
• If an exception occurs during execution of the try clause, the rest of the clause is skipped. Then if its
type matches the exception named after the except keyword, the except clause is executed, and then
execution continues after the try statement.
• If an exception occurs which does not match the exception named in the except clause, it is passed on
to outer try statements; if no handler is found, it is an unhandled exception and execution stops with
a message as shown above.
A try statement may have more than one except clause, to specify handlers for different exceptions. At
most one handler will be executed. Handlers only handle exceptions that occur in the corresponding try
clause, not in other handlers of the same try statement. An except clause may name multiple exceptions as
a parenthesized tuple, for example:

... except (RuntimeError, TypeError, NameError):

... pass

A class in an except clause is compatible with an exception if it is the same class or a base class thereof (but
not the other way around — an except clause listing a derived class is not compatible with a base class).
For example, the following code will print B, C, D in that order:

class B(Exception):
pass

(continues on next page)

62 Chapter 8. Errors and Exceptions

Python Tutorial, Release 3.7.0

instantiate an exception first before raising it and add any attributes to it as desired.
>>> try:
... raise Exception('spam', 'eggs')
... except Exception as inst:
... print(type(inst)) # the exception instance
... print(inst.args) # arguments stored in .args
... print(inst) # __str__ allows args to be printed directly,
... # but may be overridden in exception subclasses
... x, y = inst.args # unpack args
... print('x =', x)
... print('y =', y)
...
<class 'Exception'>
('spam', 'eggs')
('spam', 'eggs')
x = spam
y = eggs

If an exception has arguments, they are printed as the last part (‘detail’) of the message for unhandled
exceptions.
Exception handlers don’t just handle exceptions if they occur immediately in the try clause, but also if they
occur inside functions that are called (even indirectly) in the try clause. For example:
>>> def this_fails():
... x = 1/0
...
>>> try:
... this_fails()
... except ZeroDivisionError as err:
... print('Handling run-time error:', err)
...
Handling run-time error: division by zero

8.4 Raising Exceptions

The raise statement allows the programmer to force a specified exception to occur. For example:
>>> raise NameError('HiThere')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: HiThere

The sole argument to raise indicates the exception to be raised. This must be either an exception instance or
an exception class (a class that derives from Exception). If an exception class is passed, it will be implicitly
instantiated by calling its constructor with no arguments:
raise ValueError # shorthand for 'raise ValueError()'

If you need to determine whether an exception was raised but don’t intend to handle it, a simpler form of
the raise statement allows you to re-raise the exception:
>>> try:
... raise NameError('HiThere')
... except NameError:
(continues on next page)

64 Chapter 8. Errors and Exceptions

Python Tutorial, Release 3.7.0

8.6 Defining Clean-up Actions

The try statement has another optional clause which is intended to define clean-up actions that must be
executed under all circumstances. For example:

>>> try:
... raise KeyboardInterrupt
... finally:
... print('Goodbye, world!')
...
Goodbye, world!
KeyboardInterrupt
Traceback (most recent call last):
File "<stdin>", line 2, in <module>

A finally clause is always executed before leaving the try statement, whether an exception has occurred or
not. When an exception has occurred in the try clause and has not been handled by an except clause (or it
has occurred in an except or else clause), it is re-raised after the finally clause has been executed. The
finally clause is also executed “on the way out” when any other clause of the try statement is left via a
break, continue or return statement. A more complicated example:

>>> def divide(x, y):

... try:
... result = x / y
... except ZeroDivisionError:
... print("division by zero!")
... else:
... print("result is", result)
... finally:
... print("executing finally clause")
...
>>> divide(2, 1)
result is 2.0
executing finally clause
>>> divide(2, 0)
division by zero!
executing finally clause
>>> divide("2", "1")
executing finally clause
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "<stdin>", line 3, in divide
TypeError: unsupported operand type(s) for /: 'str' and 'str'

As you can see, the finally clause is executed in any event. The TypeError raised by dividing two strings
is not handled by the except clause and therefore re-raised after the finally clause has been executed.
In real world applications, the finally clause is useful for releasing external resources (such as files or
network connections), regardless of whether the use of the resource was successful.

8.7 Predefined Clean-up Actions

Some objects define standard clean-up actions to be undertaken when the object is no longer needed, regard-
less of whether or not the operation using the object succeeded or failed. Look at the following example,
which tries to open a file and print its contents to the screen.

66 Chapter 8. Errors and Exceptions

Python Tutorial, Release 3.7.0

68 Chapter 8. Errors and Exceptions

Python Tutorial, Release 3.7.0

understand what’s going on. Incidentally, knowledge about this subject is useful for any advanced Python
programmer.
Let’s begin with some definitions.
A namespace is a mapping from names to objects. Most namespaces are currently implemented as Python
dictionaries, but that’s normally not noticeable in any way (except for performance), and it may change
in the future. Examples of namespaces are: the set of built-in names (containing functions such as abs(),
and built-in exception names); the global names in a module; and the local names in a function invocation.
In a sense the set of attributes of an object also form a namespace. The important thing to know about
namespaces is that there is absolutely no relation between names in different namespaces; for instance, two
different modules may both define a function maximize without confusion — users of the modules must
prefix it with the module name.
By the way, I use the word attribute for any name following a dot — for example, in the expression z.
real, real is an attribute of the object z. Strictly speaking, references to names in modules are attribute
references: in the expression modname.funcname, modname is a module object and funcname is an attribute
of it. In this case there happens to be a straightforward mapping between the module’s attributes and the
global names defined in the module: they share the same namespace!1
Attributes may be read-only or writable. In the latter case, assignment to attributes is possible. Module
attributes are writable: you can write modname.the_answer = 42. Writable attributes may also be deleted
with the del statement. For example, del modname.the_answer will remove the attribute the_answer from
the object named by modname.
Namespaces are created at different moments and have different lifetimes. The namespace containing the
built-in names is created when the Python interpreter starts up, and is never deleted. The global namespace
for a module is created when the module definition is read in; normally, module namespaces also last until
the interpreter quits. The statements executed by the top-level invocation of the interpreter, either read
from a script file or interactively, are considered part of a module called __main__, so they have their own
global namespace. (The built-in names actually also live in a module; this is called builtins.)
The local namespace for a function is created when the function is called, and deleted when the function
returns or raises an exception that is not handled within the function. (Actually, forgetting would be a
better way to describe what actually happens.) Of course, recursive invocations each have their own local
namespace.
A scope is a textual region of a Python program where a namespace is directly accessible. “Directly accessible”
here means that an unqualified reference to a name attempts to find the name in the namespace.
Although scopes are determined statically, they are used dynamically. At any time during execution, there
are at least three nested scopes whose namespaces are directly accessible:
• the innermost scope, which is searched first, contains the local names
• the scopes of any enclosing functions, which are searched starting with the nearest enclosing scope,
contains non-local, but also non-global names
• the next-to-last scope contains the current module’s global names
• the outermost scope (searched last) is the namespace containing built-in names
If a name is declared global, then all references and assignments go directly to the middle scope containing the
module’s global names. To rebind variables found outside of the innermost scope, the nonlocal statement
can be used; if not declared nonlocal, those variables are read-only (an attempt to write to such a variable
will simply create a new local variable in the innermost scope, leaving the identically named outer variable
unchanged).
1 Except for one thing. Module objects have a secret read-only attribute called __dict__ which returns the dictionary used

to implement the module’s namespace; the name __dict__ is an attribute but not a global name. Obviously, using this violates
the abstraction of namespace implementation, and should be restricted to things like post-mortem debuggers.

70 Chapter 9. Classes
Python Tutorial, Release 3.7.0

You can also see that there was no previous binding for spam before the global assignment.

9.3 A First Look at Classes

Classes introduce a little bit of new syntax, three new object types, and some new semantics.

9.3.1 Class Definition Syntax

The simplest form of class definition looks like this:

class ClassName:
<statement-1>
.
.
.
<statement-N>

Class definitions, like function definitions (def statements) must be executed before they have any effect.
(You could conceivably place a class definition in a branch of an if statement, or inside a function.)
In practice, the statements inside a class definition will usually be function definitions, but other statements
are allowed, and sometimes useful — we’ll come back to this later. The function definitions inside a class
normally have a peculiar form of argument list, dictated by the calling conventions for methods — again,
this is explained later.
When a class definition is entered, a new namespace is created, and used as the local scope — thus, all
assignments to local variables go into this new namespace. In particular, function definitions bind the name
of the new function here.
When a class definition is left normally (via the end), a class object is created. This is basically a wrapper
around the contents of the namespace created by the class definition; we’ll learn more about class objects
in the next section. The original local scope (the one in effect just before the class definition was entered)
is reinstated, and the class object is bound here to the class name given in the class definition header
(ClassName in the example).

9.3.2 Class Objects

Class objects support two kinds of operations: attribute references and instantiation.
Attribute references use the standard syntax used for all attribute references in Python: obj.name. Valid
attribute names are all the names that were in the class’s namespace when the class object was created. So,
if the class definition looked like this:

class MyClass:
"""A simple example class"""
i = 12345

def f(self):
return 'hello world'

then MyClass.i and MyClass.f are valid attribute references, returning an integer and a function object,
respectively. Class attributes can also be assigned to, so you can change the value of MyClass.i by assign-
ment. __doc__ is also a valid attribute, returning the docstring belonging to the class: "A simple example
class".

72 Chapter 9. Classes
Python Tutorial, Release 3.7.0

9.3.4 Method Objects

Usually, a method is called right after it is bound:

x.f()

In the MyClass example, this will return the string 'hello world'. However, it is not necessary to call a
method right away: x.f is a method object, and can be stored away and called at a later time. For example:

xf = x.f
while True:
print(xf())

will continue to print hello world until the end of time.

What exactly happens when a method is called? You may have noticed that x.f() was called without an
argument above, even though the function definition for f() specified an argument. What happened to the
argument? Surely Python raises an exception when a function that requires an argument is called without
any — even if the argument isn’t actually used…
Actually, you may have guessed the answer: the special thing about methods is that the instance object is
passed as the first argument of the function. In our example, the call x.f() is exactly equivalent to MyClass.
f(x). In general, calling a method with a list of n arguments is equivalent to calling the corresponding
function with an argument list that is created by inserting the method’s instance object before the first
argument.
If you still don’t understand how methods work, a look at the implementation can perhaps clarify matters.
When a non-data attribute of an instance is referenced, the instance’s class is searched. If the name denotes
a valid class attribute that is a function object, a method object is created by packing (pointers to) the
instance object and the function object just found together in an abstract object: this is the method object.
When the method object is called with an argument list, a new argument list is constructed from the instance
object and the argument list, and the function object is called with this new argument list.

9.3.5 Class and Instance Variables

Generally speaking, instance variables are for data unique to each instance and class variables are for at-
tributes and methods shared by all instances of the class:

class Dog:

kind = 'canine' # class variable shared by all instances

def __init__(self, name):

self.name = name # instance variable unique to each instance

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.kind # shared by all dogs
'canine'
>>> e.kind # shared by all dogs
'canine'
>>> d.name # unique to d
'Fido'
>>> e.name # unique to e
'Buddy'

74 Chapter 9. Classes
Python Tutorial, Release 3.7.0

by stamping on their data attributes. Note that clients may add data attributes of their own to an instance
object without affecting the validity of the methods, as long as name conflicts are avoided — again, a naming
convention can save a lot of headaches here.
There is no shorthand for referencing data attributes (or other methods!) from within methods. I find that
this actually increases the readability of methods: there is no chance of confusing local variables and instance
variables when glancing through a method.
Often, the first argument of a method is called self. This is nothing more than a convention: the name
self has absolutely no special meaning to Python. Note, however, that by not following the convention
your code may be less readable to other Python programmers, and it is also conceivable that a class browser
program might be written that relies upon such a convention.
Any function object that is a class attribute defines a method for instances of that class. It is not necessary
that the function definition is textually enclosed in the class definition: assigning a function object to a local
variable in the class is also ok. For example:

# Function defined outside the class

def f1(self, x, y):
return min(x, x+y)

class C:
f = f1

def g(self):
return 'hello world'

h = g

Now f, g and h are all attributes of class C that refer to function objects, and consequently they are all
methods of instances of C — h being exactly equivalent to g. Note that this practice usually only serves to
confuse the reader of a program.
Methods may call other methods by using method attributes of the self argument:

class Bag:
def __init__(self):
self.data = []

def add(self, x):

self.data.append(x)

def addtwice(self, x):

self.add(x)
self.add(x)

Methods may reference global names in the same way as ordinary functions. The global scope associated
with a method is the module containing its definition. (A class is never used as a global scope.) While one
rarely encounters a good reason for using global data in a method, there are many legitimate uses of the
global scope: for one thing, functions and modules imported into the global scope can be used by methods,
as well as functions and classes defined in it. Usually, the class containing the method is itself defined in this
global scope, and in the next section we’ll find some good reasons why a method would want to reference its
own class.
Each value is an object, and therefore has a class (also called its type). It is stored as object.__class__.

76 Chapter 9. Classes
Python Tutorial, Release 3.7.0

For most purposes, in the simplest cases, you can think of the search for attributes inherited from a parent
class as depth-first, left-to-right, not searching twice in the same class where there is an overlap in the hier-
archy. Thus, if an attribute is not found in DerivedClassName, it is searched for in Base1, then (recursively)
in the base classes of Base1, and if it was not found there, it was searched for in Base2, and so on.
In fact, it is slightly more complex than that; the method resolution order changes dynamically to support
cooperative calls to super(). This approach is known in some other multiple-inheritance languages as
call-next-method and is more powerful than the super call found in single-inheritance languages.
Dynamic ordering is necessary because all cases of multiple inheritance exhibit one or more diamond re-
lationships (where at least one of the parent classes can be accessed through multiple paths from the
bottommost class). For example, all classes inherit from object, so any case of multiple inheritance
provides more than one path to reach object. To keep the base classes from being accessed more than
once, the dynamic algorithm linearizes the search order in a way that preserves the left-to-right order-
ing specified in each class, that calls each parent only once, and that is monotonic (meaning that a class
can be subclassed without affecting the precedence order of its parents). Taken together, these properties
make it possible to design reliable and extensible classes with multiple inheritance. For more detail, see
https://www.python.org/download/releases/2.3/mro/.

9.6 Private Variables

“Private” instance variables that cannot be accessed except from inside an object don’t exist in Python.
However, there is a convention that is followed by most Python code: a name prefixed with an underscore
(e.g. _spam) should be treated as a non-public part of the API (whether it is a function, a method or a data
member). It should be considered an implementation detail and subject to change without notice.
Since there is a valid use-case for class-private members (namely to avoid name clashes of names with names
defined by subclasses), there is limited support for such a mechanism, called name mangling. Any identifier
of the form __spam (at least two leading underscores, at most one trailing underscore) is textually replaced
with _classname__spam, where classname is the current class name with leading underscore(s) stripped.
This mangling is done without regard to the syntactic position of the identifier, as long as it occurs within
the definition of a class.
Name mangling is helpful for letting subclasses override methods without breaking intraclass method calls.
For example:
class Mapping:
def __init__(self, iterable):
self.items_list = []
self.__update(iterable)

def update(self, iterable):

for item in iterable:
self.items_list.append(item)

__update = update # private copy of original update() method

class MappingSubclass(Mapping):

def update(self, keys, values):

# provides new signature for update()
# but does not break __init__()
for item in zip(keys, values):
self.items_list.append(item)

Note that the mangling rules are designed mostly to avoid accidents; it still is possible to access or modify a
variable that is considered private. This can even be useful in special circumstances, such as in the debugger.

78 Chapter 9. Classes
Python Tutorial, Release 3.7.0

(continued from previous page)

<iterator object at 0x00A1DB50>
>>> next(it)
'a'
>>> next(it)
'b'
>>> next(it)
'c'
>>> next(it)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
next(it)
StopIteration

Having seen the mechanics behind the iterator protocol, it is easy to add iterator behavior to your classes.
Define an __iter__() method which returns an object with a __next__() method. If the class defines
__next__(), then __iter__() can just return self:

class Reverse:
"""Iterator for looping over a sequence backwards."""
def __init__(self, data):
self.data = data
self.index = len(data)

def __iter__(self):
return self

def __next__(self):
if self.index == 0:
raise StopIteration
self.index = self.index - 1
return self.data[self.index]

>>> rev = Reverse('spam')

>>> iter(rev)
<__main__.Reverse object at 0x00A1DB50>
>>> for char in rev:
... print(char)
...
m
a
p
s

9.9 Generators
Generators are a simple and powerful tool for creating iterators. They are written like regular functions but
use the yield statement whenever they want to return data. Each time next() is called on it, the generator
resumes where it left off (it remembers all the data values and which statement was last executed). An
example shows that generators can be trivially easy to create:

def reverse(data):
for index in range(len(data)-1, -1, -1):
yield data[index]

80 Chapter 9. Classes
Python Tutorial, Release 3.7.0

82 Chapter 9. Classes
Python Tutorial, Release 3.7.0

10.3 Command Line Arguments

Common utility scripts often need to process command line arguments. These arguments are stored in the
sys module’s argv attribute as a list. For instance the following output results from running python demo.py
one two three at the command line:

>>> import sys

>>> print(sys.argv)
['demo.py', 'one', 'two', 'three']

The getopt module processes sys.argv using the conventions of the Unix getopt() function. More powerful
and flexible command line processing is provided by the argparse module.

10.4 Error Output Redirection and Program Termination

The sys module also has attributes for stdin, stdout, and stderr. The latter is useful for emitting warnings
and error messages to make them visible even when stdout has been redirected:

>>> sys.stderr.write('Warning, log file not found starting a new one\n')

Warning, log file not found starting a new one

The most direct way to terminate a script is to use sys.exit().

10.5 String Pattern Matching

The re module provides regular expression tools for advanced string processing. For complex matching and
manipulation, regular expressions offer succinct, optimized solutions:

>>> import re
>>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
['foot', 'fell', 'fastest']
>>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat')
'cat in the hat'

When only simple capabilities are needed, string methods are preferred because they are easier to read and
debug:

>>> 'tea for too'.replace('too', 'two')

'tea for two'

10.6 Mathematics
The math module gives access to the underlying C library functions for floating point math:

>>> import math

>>> math.cos(math.pi / 4)
0.70710678118654757
>>> math.log(1024, 2)
10.0

The random module provides tools for making random selections:

84 Chapter 10. Brief Tour of the Standard Library

Python Tutorial, Release 3.7.0

tion for output formatting and manipulation. The module also supports objects that are timezone aware.

>>> # dates are easily constructed and formatted

>>> from datetime import date
>>> now = date.today()
>>> now
datetime.date(2003, 12, 2)
>>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.")
'12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'

>>> # dates support calendar arithmetic

>>> birthday = date(1964, 7, 31)
>>> age = now - birthday
>>> age.days
14368

10.9 Data Compression

Common data archiving and compression formats are directly supported by modules including: zlib, gzip,
bz2, lzma, zipfile and tarfile.

>>> import zlib

>>> s = b'witch which has which witches wrist watch'
>>> len(s)
41
>>> t = zlib.compress(s)
>>> len(t)
37
>>> zlib.decompress(t)
b'witch which has which witches wrist watch'
>>> zlib.crc32(s)
226805979

10.10 Performance Measurement

Some Python users develop a deep interest in knowing the relative performance of different approaches to
the same problem. Python provides a measurement tool that answers those questions immediately.
For example, it may be tempting to use the tuple packing and unpacking feature instead of the tradi-
tional approach to swapping arguments. The timeit module quickly demonstrates a modest performance
advantage:

>>> from timeit import Timer

>>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit()
0.57535828626024577
>>> Timer('a,b = b,a', 'a=1; b=2').timeit()
0.54962537085770791

In contrast to timeit’s fine level of granularity, the profile and pstats modules provide tools for identifying
time critical sections in larger blocks of code.

86 Chapter 10. Brief Tour of the Standard Library

Python Tutorial, Release 3.7.0

• The sqlite3 module is a wrapper for the SQLite database library, providing a persistent database
that can be updated and accessed using slightly nonstandard SQL syntax.
• Internationalization is supported by a number of modules including gettext, locale, and the codecs
package.

88 Chapter 10. Brief Tour of the Standard Library

Python Tutorial, Release 3.7.0

>>> import locale

>>> locale.setlocale(locale.LC_ALL, 'English_United States.1252')
'English_United States.1252'
>>> conv = locale.localeconv() # get a mapping of conventions
>>> x = 1234567.8
>>> locale.format("%d", x, grouping=True)
'1,234,567'
>>> locale.format_string("%s%.*f", (conv['currency_symbol'],
... conv['frac_digits'], x), grouping=True)
'$1,234,567.80'

11.2 Templating
The string module includes a versatile Template class with a simplified syntax suitable for editing by
end-users. This allows users to customize their applications without having to alter the application.
The format uses placeholder names formed by $ with valid Python identifiers (alphanumeric characters and
underscores). Surrounding the placeholder with braces allows it to be followed by more alphanumeric letters
with no intervening spaces. Writing $$ creates a single escaped $:
>>> from string import Template
>>> t = Template('${village}folk send $$10 to $cause.')
>>> t.substitute(village='Nottingham', cause='the ditch fund')
'Nottinghamfolk send $10 to the ditch fund.'

The substitute() method raises a KeyError when a placeholder is not supplied in a dictionary or a
keyword argument. For mail-merge style applications, user supplied data may be incomplete and the
safe_substitute() method may be more appropriate — it will leave placeholders unchanged if data is
missing:
>>> t = Template('Return the $item to $owner.')
>>> d = dict(item='unladen swallow')
>>> t.substitute(d)
Traceback (most recent call last):
...
KeyError: 'owner'
>>> t.safe_substitute(d)
'Return the unladen swallow to $owner.'

Template subclasses can specify a custom delimiter. For example, a batch renaming utility for a photo
browser may elect to use percent signs for placeholders such as the current date, image sequence number, or
file format:
>>> import time, os.path
>>> photofiles = ['img_1074.jpg', 'img_1076.jpg', 'img_1077.jpg']
>>> class BatchRename(Template):
... delimiter = '%'
>>> fmt = input('Enter rename style (%d-date %n-seqnum %f-format): ')
Enter rename style (%d-date %n-seqnum %f-format): Ashley_%n%f

>>> t = BatchRename(fmt)
>>> date = time.strftime('%d%b%y')
>>> for i, filename in enumerate(photofiles):
... base, ext = os.path.splitext(filename)
... newname = t.substitute(d=date, n=i, f=ext)
(continues on next page)

90 Chapter 11. Brief Tour of the Standard Library — Part II

Python Tutorial, Release 3.7.0

(continued from previous page)

def run(self):
f = zipfile.ZipFile(self.outfile, 'w', zipfile.ZIP_DEFLATED)
f.write(self.infile)
f.close()
print('Finished background zip of:', self.infile)

background = AsyncZip('mydata.txt', 'myarchive.zip')

background.start()
print('The main program continues to run in foreground.')

background.join() # Wait for the background task to finish

print('Main program waited until background was done.')

The principal challenge of multi-threaded applications is coordinating threads that share data or other
resources. To that end, the threading module provides a number of synchronization primitives including
locks, events, condition variables, and semaphores.
While those tools are powerful, minor design errors can result in problems that are difficult to reproduce.
So, the preferred approach to task coordination is to concentrate all access to a resource in a single thread
and then use the queue module to feed that thread with requests from other threads. Applications using
Queue objects for inter-thread communication and coordination are easier to design, more readable, and
more reliable.

11.5 Logging
The logging module offers a full featured and flexible logging system. At its simplest, log messages are sent
to a file or to sys.stderr:

import logging
logging.debug('Debugging information')
logging.info('Informational message')
logging.warning('Warning:config file %s not found', 'server.conf')
logging.error('Error occurred')
logging.critical('Critical error -- shutting down')

This produces the following output:

WARNING:root:Warning:config file server.conf not found

ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down

By default, informational and debugging messages are suppressed and the output is sent to standard er-
ror. Other output options include routing messages through email, datagrams, sockets, or to an HTTP
Server. New filters can select different routing based on message priority: DEBUG, INFO, WARNING, ERROR, and
CRITICAL.
The logging system can be configured directly from Python or can be loaded from a user editable configuration
file for customized logging without altering the application.

92 Chapter 11. Brief Tour of the Standard Library — Part II

Python Tutorial, Release 3.7.0

>>> from collections import deque

>>> d = deque(["task1", "task2", "task3"])
>>> d.append("task4")
>>> print("Handling", d.popleft())
Handling task1

unsearched = deque([starting_node])
def breadth_first_search(unsearched):
node = unsearched.popleft()
for m in gen_moves(node):
if is_goal(m):
return m
unsearched.append(m)

In addition to alternative list implementations, the library also offers other tools such as the bisect module
with functions for manipulating sorted lists:

>>> import bisect

>>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')]
>>> bisect.insort(scores, (300, 'ruby'))
>>> scores
[(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')]

The heapq module provides functions for implementing heaps based on regular lists. The lowest valued entry
is always kept at position zero. This is useful for applications which repeatedly access the smallest element
but do not want to run a full list sort:

>>> from heapq import heapify, heappop, heappush

>>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
>>> heapify(data) # rearrange the list into heap order
>>> heappush(data, -5) # add a new entry
>>> [heappop(data) for i in range(3)] # fetch the three smallest entries
[-5, 0, 1]

11.8 Decimal Floating Point Arithmetic

The decimal module offers a Decimal datatype for decimal floating point arithmetic. Compared to the
built-in float implementation of binary floating point, the class is especially helpful for
• financial applications and other uses which require exact decimal representation,
• control over precision,
• control over rounding to meet legal or regulatory requirements,
• tracking of significant decimal places, or
• applications where the user expects the results to match calculations done by hand.
For example, calculating a 5% tax on a 70 cent phone charge gives different results in decimal floating point
and binary floating point. The difference becomes significant if the results are rounded to the nearest cent:

>>> from decimal import *

>>> round(Decimal('0.70') * Decimal('1.05'), 2)
Decimal('0.74')
>>> round(.70 * 1.05, 2)
0.73

94 Chapter 11. Brief Tour of the Standard Library — Part II

Python Tutorial, Release 3.7.0

96 Chapter 11. Brief Tour of the Standard Library — Part II

Python Tutorial, Release 3.7.0

(This script is written for the bash shell. If you use the csh or fish shells, there are alternate activate.csh
and activate.fish scripts you should use instead.)
Activating the virtual environment will change your shell’s prompt to show what virtual environment you’re
using, and modify the environment so that running python will get you that particular version and instal-
lation of Python. For example:

$ source ~/envs/tutorial-env/bin/activate
(tutorial-env) $ python
Python 3.5.1 (default, May 6 2016, 10:59:36)
...
>>> import sys
>>> sys.path
['', '/usr/local/lib/python35.zip', ...,
'~/envs/tutorial-env/lib/python3.5/site-packages']
>>>

12.3 Managing Packages with pip

You can install, upgrade, and remove packages using a program called pip. By default pip will install
packages from the Python Package Index, <https://pypi.org>. You can browse the Python Package Index
by going to it in your web browser, or you can use pip’s limited search feature:

(tutorial-env) $ pip search astronomy

skyfield - Elegant astronomy for Python
gary - Galactic astronomy and gravitational dynamics.
novas - The United States Naval Observatory NOVAS astronomy library
astroobs - Provides astronomy ephemeris to plan telescope observations
PyAstronomy - A collection of astronomy related tools for Python.
...

pip has a number of subcommands: “search”, “install”, “uninstall”, “freeze”, etc. (Consult the installing-
index guide for complete documentation for pip.)
You can install the latest version of a package by specifying a package’s name:

(tutorial-env) $ pip install novas

Collecting novas
Downloading novas-3.1.1.3.tar.gz (136kB)
Installing collected packages: novas
Running setup.py install for novas
Successfully installed novas-3.1.1.3

You can also install a specific version of a package by giving the package name followed by == and the version
number:

(tutorial-env) $ pip install requests==2.6.0

Collecting requests==2.6.0
Using cached requests-2.6.0-py2.py3-none-any.whl
Installing collected packages: requests
Successfully installed requests-2.6.0

If you re-run this command, pip will notice that the requested version is already installed and do nothing.
You can supply a different version number to get that version, or you can run pip install --upgrade to
upgrade the package to the latest version:

98 Chapter 12. Virtual Environments and Packages

Python Tutorial, Release 3.7.0

pip has many more options. Consult the installing-index guide for complete documentation for pip. When
you’ve written a package and want to make it available on the Python Package Index, consult the distributing-
index guide.

100 Chapter 12. Virtual Environments and Packages

Python Tutorial, Release 3.7.0

Before posting, be sure to check the list of Frequently Asked Questions (also called the FAQ). The FAQ
answers many of the questions that come up again and again, and may already contain the solution for your
problem.

102 Chapter 13. What Now?

Python Tutorial, Release 3.7.0

104 Chapter 14. Interactive Input Editing and History Substitution

Python Tutorial, Release 3.7.0

>>> 0.1
0.1000000000000000055511151231257827021181583404541015625

That is more digits than most people find useful, so Python keeps the number of digits manageable by
displaying a rounded value instead

>>> 1 / 10
0.1

Just remember, even though the printed result looks like the exact value of 1/10, the actual stored value is
the nearest representable binary fraction.
Interestingly, there are many different decimal numbers that share the same nearest ap-
proximate binary fraction. For example, the numbers 0.1 and 0.10000000000000001 and
0.1000000000000000055511151231257827021181583404541015625 are all approximated by
3602879701896397 / 2 ** 55. Since all of these decimal values share the same approximation,
any one of them could be displayed while still preserving the invariant eval(repr(x)) == x.
Historically, the Python prompt and built-in repr() function would choose the one with 17 significant
digits, 0.10000000000000001. Starting with Python 3.1, Python (on most systems) is now able to choose
the shortest of these and simply display 0.1.
Note that this is in the very nature of binary floating-point: this is not a bug in Python, and it is not a
bug in your code either. You’ll see the same kind of thing in all languages that support your hardware’s
floating-point arithmetic (although some languages may not display the difference by default, or in all output
modes).
For more pleasant output, you may wish to use string formatting to produce a limited number of significant
digits:

>>> format(math.pi, '.12g') # give 12 significant digits

'3.14159265359'

>>> format(math.pi, '.2f') # give 2 digits after the point

'3.14'

>>> repr(math.pi)
'3.141592653589793'

It’s important to realize that this is, in a real sense, an illusion: you’re simply rounding the display of the
true machine value.
One illusion may beget another. For example, since 0.1 is not exactly 1/10, summing three values of 0.1 may
not yield exactly 0.3, either:

>>> .1 + .1 + .1 == .3
False

Also, since the 0.1 cannot get any closer to the exact value of 1/10 and 0.3 cannot get any closer to the exact
value of 3/10, then pre-rounding with round() function cannot help:

>>> round(.1, 1) + round(.1, 1) + round(.1, 1) == round(.3, 1)

False

Though the numbers cannot be made closer to their intended exact values, the round() function can be
useful for post-rounding so that results with inexact values become comparable to one another:

>>> round(.1 + .1 + .1, 10) == round(.3, 10)

True

106 Chapter 15. Floating Point Arithmetic: Issues and Limitations

Python Tutorial, Release 3.7.0

15.1 Representation Error

This section explains the “0.1” example in detail, and shows how you can perform an exact analysis of cases
like this yourself. Basic familiarity with binary floating-point representation is assumed.
Representation error refers to the fact that some (most, actually) decimal fractions cannot be represented
exactly as binary (base 2) fractions. This is the chief reason why Python (or Perl, C, C++, Java, Fortran,
and many others) often won’t display the exact decimal number you expect.
Why is that? 1/10 is not exactly representable as a binary fraction. Almost all machines today (November
2000) use IEEE-754 floating point arithmetic, and almost all platforms map Python floats to IEEE-754
“double precision”. 754 doubles contain 53 bits of precision, so on input the computer strives to convert 0.1
to the closest fraction it can of the form J/2**N where J is an integer containing exactly 53 bits. Rewriting

1 / 10 ~= J / (2**N)

as

J ~= 2**N / 10

and recalling that J has exactly 53 bits (is >= 2**52 but < 2**53), the best value for N is 56:

>>> 2**52 <= 2**56 // 10 < 2**53

True

That is, 56 is the only value for N that leaves J with exactly 53 bits. The best possible value for J is then
that quotient rounded:

>>> q, r = divmod(2**56, 10)

>>> r
6

Since the remainder is more than half of 10, the best approximation is obtained by rounding up:

>>> q+1
7205759403792794

Therefore the best possible approximation to 1/10 in 754 double precision is:

7205759403792794 / 2 ** 56

Dividing both the numerator and denominator by two reduces the fraction to:

3602879701896397 / 2 ** 55

Note that since we rounded up, this is actually a little bit larger than 1/10; if we had not rounded up, the
quotient would have been a little bit smaller than 1/10. But in no case can it be exactly 1/10!
So the computer never “sees” 1/10: what it sees is the exact fraction given above, the best 754 double
approximation it can get:

>>> 0.1 * 2 ** 55
3602879701896397.0

If we multiply that fraction by 10**55, we can see the value out to 55 decimal digits:

>>> 3602879701896397 * 10 ** 55 // 2 ** 55
1000000000000000055511151231257827021181583404541015625

108 Chapter 15. Floating Point Arithmetic: Issues and Limitations

Python Tutorial, Release 3.7.0

110 Chapter 15. Floating Point Arithmetic: Issues and Limitations

Python Tutorial, Release 3.7.0

to the name of a file containing your start-up commands. This is similar to the .profile feature of the Unix
shells.
This file is only read in interactive sessions, not when Python reads commands from a script, and not when
/dev/tty is given as the explicit source of commands (which otherwise behaves like an interactive session). It
is executed in the same namespace where interactive commands are executed, so that objects that it defines
or imports can be used without qualification in the interactive session. You can also change the prompts
sys.ps1 and sys.ps2 in this file.
If you want to read an additional start-up file from the current directory, you can program this in the
global start-up file using code like if os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').
read()). If you want to use the startup file in a script, you must do this explicitly in the script:

import os
filename = os.environ.get('PYTHONSTARTUP')
if filename and os.path.isfile(filename):
with open(filename) as fobj:
startup_file = fobj.read()
exec(startup_file)

16.1.4 The Customization Modules

Python provides two hooks to let you customize it: sitecustomize and usercustomize. To see how it
works, you need first to find the location of your user site-packages directory. Start Python and run this
code:

>>> import site

>>> site.getusersitepackages()
'/home/user/.local/lib/python3.5/site-packages'

Now you can create a file named usercustomize.py in that directory and put anything you want in it. It
will affect every invocation of Python, unless it is started with the -s option to disable the automatic import.
sitecustomize works in the same way, but is typically created by an administrator of the computer in the
global site-packages directory, and is imported before usercustomize. See the documentation of the site
module for more details.

112 Chapter 16. Appendix

Python Tutorial, Release 3.7.0

Arguments are assigned to the named local variables in a function body. See the calls section for the
rules governing this assignment. Syntactically, any expression can be used to represent an argument;
the evaluated value is assigned to the local variable.
See also the parameter glossary entry, the FAQ question on the difference between arguments and
parameters, and PEP 362.
asynchronous context manager An object which controls the environment seen in an async with state-
ment by defining __aenter__() and __aexit__() methods. Introduced by PEP 492.
asynchronous generator A function which returns an asynchronous generator iterator. It looks like a
coroutine function defined with async def except that it contains yield expressions for producing a
series of values usable in an async for loop.
Usually refers to a asynchronous generator function, but may refer to an asynchronous generator
iterator in some contexts. In cases where the intended meaning isn’t clear, using the full terms avoids
ambiguity.
An asynchronous generator function may contain await expressions as well as async for, and async
with statements.
asynchronous generator iterator An object created by a asynchronous generator function.
This is an asynchronous iterator which when called using the __anext__() method returns an awaitable
object which will execute that the body of the asynchronous generator function until the next yield
expression.
Each yield temporarily suspends processing, remembering the location execution state (including local
variables and pending try-statements). When the asynchronous generator iterator effectively resumes
with another awaitable returned by __anext__(), it picks up where it left off. See PEP 492 and PEP
525.
asynchronous iterable An object, that can be used in an async for statement. Must return an asyn-
chronous iterator from its __aiter__() method. Introduced by PEP 492.
asynchronous iterator An object that implements the __aiter__() and __anext__() methods.
__anext__ must return an awaitable object. async for resolves the awaitables returned by an asyn-
chronous iterator’s __anext__() method until it raises a StopAsyncIteration exception. Introduced
by PEP 492.
attribute A value associated with an object which is referenced by name using dotted expressions. For
example, if an object o has an attribute a it would be referenced as o.a.
awaitable An object that can be used in an await expression. Can be a coroutine or an object with an
__await__() method. See also PEP 492.
BDFL Benevolent Dictator For Life, a.k.a. Guido van Rossum, Python’s creator.
binary file A file object able to read and write bytes-like objects. Examples of binary files are files opened
in binary mode ('rb', 'wb' or 'rb+'), sys.stdin.buffer, sys.stdout.buffer, and instances of
io.BytesIO and gzip.GzipFile.
See also text file for a file object able to read and write str objects.
bytes-like object An object that supports the bufferobjects and can export a C-contiguous buffer. This
includes all bytes, bytearray, and array.array objects, as well as many common memoryview ob-
jects. Bytes-like objects can be used for various operations that work with binary data; these include
compression, saving to a binary file, and sending over a socket.
Some operations need the binary data to be mutable. The documentation often refers to these as “read-
write bytes-like objects”. Example mutable buffer objects include bytearray and a memoryview of a
bytearray. Other operations require the binary data to be stored in immutable objects (“read-only
bytes-like objects”); examples of these include bytes and a memoryview of a bytes object.

114 Appendix A. Glossary

Python Tutorial, Release 3.7.0

(continued from previous page)

@staticmethod
def f(...):
...

The same concept exists for classes, but is less commonly used there. See the documentation for
function definitions and class definitions for more about decorators.
descriptor Any object which defines the methods __get__(), __set__(), or __delete__(). When a class
attribute is a descriptor, its special binding behavior is triggered upon attribute lookup. Normally,
using a.b to get, set or delete an attribute looks up the object named b in the class dictionary for a, but
if b is a descriptor, the respective descriptor method gets called. Understanding descriptors is a key
to a deep understanding of Python because they are the basis for many features including functions,
methods, properties, class methods, static methods, and reference to super classes.
For more information about descriptors’ methods, see descriptors.
dictionary An associative array, where arbitrary keys are mapped to values. The keys can be any object
with __hash__() and __eq__() methods. Called a hash in Perl.
dictionary view The objects returned from dict.keys(), dict.values(), and dict.items() are called
dictionary views. They provide a dynamic view on the dictionary’s entries, which means that when
the dictionary changes, the view reflects these changes. To force the dictionary view to become a full
list use list(dictview). See dict-views.
docstring A string literal which appears as the first expression in a class, function or module. While ignored
when the suite is executed, it is recognized by the compiler and put into the __doc__ attribute of the
enclosing class, function or module. Since it is available via introspection, it is the canonical place for
documentation of the object.
duck-typing A programming style which does not look at an object’s type to determine if it has the right
interface; instead, the method or attribute is simply called or used (“If it looks like a duck and quacks
like a duck, it must be a duck.”) By emphasizing interfaces rather than specific types, well-designed
code improves its flexibility by allowing polymorphic substitution. Duck-typing avoids tests using
type() or isinstance(). (Note, however, that duck-typing can be complemented with abstract base
classes.) Instead, it typically employs hasattr() tests or EAFP programming.
EAFP Easier to ask for forgiveness than permission. This common Python coding style assumes the
existence of valid keys or attributes and catches exceptions if the assumption proves false. This clean
and fast style is characterized by the presence of many try and except statements. The technique
contrasts with the LBYL style common to many other languages such as C.
expression A piece of syntax which can be evaluated to some value. In other words, an expression is
an accumulation of expression elements like literals, names, attribute access, operators or function
calls which all return a value. In contrast to many other languages, not all language constructs are
expressions. There are also statements which cannot be used as expressions, such as if. Assignments
are also statements, not expressions.
extension module A module written in C or C++, using Python’s C API to interact with the core and
with user code.
f-string String literals prefixed with 'f' or 'F' are commonly called “f-strings” which is short for formatted
string literals. See also PEP 498.
file object An object exposing a file-oriented API (with methods such as read() or write()) to an underly-
ing resource. Depending on the way it was created, a file object can mediate access to a real on-disk file
or to another type of storage or communication device (for example standard input/output, in-memory
buffers, sockets, pipes, etc.). File objects are also called file-like objects or streams.
There are actually three categories of file objects: raw binary files, buffered binary files and text files.
Their interfaces are defined in the io module. The canonical way to create a file object is by using the

116 Appendix A. Glossary

Python Tutorial, Release 3.7.0

generic function A function composed of multiple functions implementing the same operation for different
types. Which implementation should be used during a call is determined by the dispatch algorithm.
See also the single dispatch glossary entry, the functools.singledispatch() decorator, and PEP
443.
GIL See global interpreter lock.
global interpreter lock The mechanism used by the CPython interpreter to assure that only one thread
executes Python bytecode at a time. This simplifies the CPython implementation by making the object
model (including critical built-in types such as dict) implicitly safe against concurrent access. Locking
the entire interpreter makes it easier for the interpreter to be multi-threaded, at the expense of much
of the parallelism afforded by multi-processor machines.
However, some extension modules, either standard or third-party, are designed so as to release the GIL
when doing computationally-intensive tasks such as compression or hashing. Also, the GIL is always
released when doing I/O.
Past efforts to create a “free-threaded” interpreter (one which locks shared data at a much finer
granularity) have not been successful because performance suffered in the common single-processor
case. It is believed that overcoming this performance issue would make the implementation much more
complicated and therefore costlier to maintain.
hash-based pyc A bytecode cache file that uses the hash rather than the last-modified time of the corre-
sponding source file to determine its validity. See pyc-invalidation.
hashable An object is hashable if it has a hash value which never changes during its lifetime (it needs a
__hash__() method), and can be compared to other objects (it needs an __eq__() method). Hashable
objects which compare equal must have the same hash value.
Hashability makes an object usable as a dictionary key and a set member, because these data structures
use the hash value internally.
All of Python’s immutable built-in objects are hashable; mutable containers (such as lists or dictio-
naries) are not. Objects which are instances of user-defined classes are hashable by default. They all
compare unequal (except with themselves), and their hash value is derived from their id().
IDLE An Integrated Development Environment for Python. IDLE is a basic editor and interpreter envi-
ronment which ships with the standard distribution of Python.
immutable An object with a fixed value. Immutable objects include numbers, strings and tuples. Such an
object cannot be altered. A new object has to be created if a different value has to be stored. They
play an important role in places where a constant hash value is needed, for example as a key in a
dictionary.
import path A list of locations (or path entries) that are searched by the path based finder for modules to
import. During import, this list of locations usually comes from sys.path, but for subpackages it may
also come from the parent package’s __path__ attribute.
importing The process by which Python code in one module is made available to Python code in another
module.
importer An object that both finds and loads a module; both a finder and loader object.
interactive Python has an interactive interpreter which means you can enter statements and expressions
at the interpreter prompt, immediately execute them and see their results. Just launch python with
no arguments (possibly by selecting it from your computer’s main menu). It is a very powerful way to
test out new ideas or inspect modules and packages (remember help(x)).
interpreted Python is an interpreted language, as opposed to a compiled one, though the distinction can
be blurry because of the presence of the bytecode compiler. This means that source files can be run
directly without explicitly creating an executable which is then run. Interpreted languages typically

118 Appendix A. Glossary

Python Tutorial, Release 3.7.0

In a multi-threaded environment, the LBYL approach can risk introducing a race condition between
“the looking” and “the leaping”. For example, the code, if key in mapping: return mapping[key]
can fail if another thread removes key from mapping after the test, but before the lookup. This issue
can be solved with locks or by using the EAFP approach.
list A built-in Python sequence. Despite its name it is more akin to an array in other languages than to a
linked list since access to elements is O(1).
list comprehension A compact way to process all or part of the elements in a sequence and return a list
with the results. result = ['{:#04x}'.format(x) for x in range(256) if x % 2 == 0] generates
a list of strings containing even hex numbers (0x..) in the range from 0 to 255. The if clause is
optional. If omitted, all elements in range(256) are processed.
loader An object that loads a module. It must define a method named load_module(). A loader is typically
returned by a finder. See PEP 302 for details and importlib.abc.Loader for an abstract base class.
mapping A container object that supports arbitrary key lookups and implements the methods specified
in the Mapping or MutableMapping abstract base classes. Examples include dict, collections.
defaultdict, collections.OrderedDict and collections.Counter.
meta path finder A finder returned by a search of sys.meta_path. Meta path finders are related to, but
different from path entry finders.
See importlib.abc.MetaPathFinder for the methods that meta path finders implement.
metaclass The class of a class. Class definitions create a class name, a class dictionary, and a list of base
classes. The metaclass is responsible for taking those three arguments and creating the class. Most
object oriented programming languages provide a default implementation. What makes Python special
is that it is possible to create custom metaclasses. Most users never need this tool, but when the need
arises, metaclasses can provide powerful, elegant solutions. They have been used for logging attribute
access, adding thread-safety, tracking object creation, implementing singletons, and many other tasks.
More information can be found in metaclasses.
method A function which is defined inside a class body. If called as an attribute of an instance of that
class, the method will get the instance object as its first argument (which is usually called self). See
function and nested scope.
method resolution order Method Resolution Order is the order in which base classes are searched for
a member during lookup. See The Python 2.3 Method Resolution Order for details of the algorithm
used by the Python interpreter since the 2.3 release.
module An object that serves as an organizational unit of Python code. Modules have a namespace
containing arbitrary Python objects. Modules are loaded into Python by the process of importing.
See also package.
module spec A namespace containing the import-related information used to load a module. An instance
of importlib.machinery.ModuleSpec.
MRO See method resolution order.
mutable Mutable objects can change their value but keep their id(). See also immutable.
named tuple Any tuple-like class whose indexable elements are also accessible using named attributes (for
example, time.localtime() returns a tuple-like object where the year is accessible either with an
index such as t[0] or with a named attribute like t.tm_year).
A named tuple can be a built-in type such as time.struct_time, or it can be created with a regular
class definition. A full featured named tuple can also be created with the factory function collections.
namedtuple(). The latter approach automatically provides extra features such as a self-documenting
representation like Employee(name='jones', title='programmer').

120 Appendix A. Glossary

Python Tutorial, Release 3.7.0

See also the argument glossary entry, the FAQ question on the difference between arguments and
parameters, the inspect.Parameter class, the function section, and PEP 362.
path entry A single location on the import path which the path based finder consults to find modules for
importing.
path entry finder A finder returned by a callable on sys.path_hooks (i.e. a path entry hook) which knows
how to locate modules given a path entry.
See importlib.abc.PathEntryFinder for the methods that path entry finders implement.
path entry hook A callable on the sys.path_hook list which returns a path entry finder if it knows how
to find modules on a specific path entry.
path based finder One of the default meta path finders which searches an import path for modules.
path-like object An object representing a file system path. A path-like object is either a str or bytes
object representing a path, or an object implementing the os.PathLike protocol. An object that
supports the os.PathLike protocol can be converted to a str or bytes file system path by calling the
os.fspath() function; os.fsdecode() and os.fsencode() can be used to guarantee a str or bytes
result instead, respectively. Introduced by PEP 519.
PEP Python Enhancement Proposal. A PEP is a design document providing information to the Python
community, or describing a new feature for Python or its processes or environment. PEPs should
provide a concise technical specification and a rationale for proposed features.
PEPs are intended to be the primary mechanisms for proposing major new features, for collecting com-
munity input on an issue, and for documenting the design decisions that have gone into Python. The
PEP author is responsible for building consensus within the community and documenting dissenting
opinions.
See PEP 1.
portion A set of files in a single directory (possibly stored in a zip file) that contribute to a namespace
package, as defined in PEP 420.
positional argument See argument.
provisional API A provisional API is one which has been deliberately excluded from the standard library’s
backwards compatibility guarantees. While major changes to such interfaces are not expected, as long
as they are marked provisional, backwards incompatible changes (up to and including removal of
the interface) may occur if deemed necessary by core developers. Such changes will not be made
gratuitously – they will occur only if serious fundamental flaws are uncovered that were missed prior
to the inclusion of the API.
Even for provisional APIs, backwards incompatible changes are seen as a “solution of last resort” -
every attempt will still be made to find a backwards compatible resolution to any identified problems.
This process allows the standard library to continue to evolve over time, without locking in problematic
design errors for extended periods of time. See PEP 411 for more details.
provisional package See provisional API .
Python 3000 Nickname for the Python 3.x release line (coined long ago when the release of version 3 was
something in the distant future.) This is also abbreviated “Py3k”.
Pythonic An idea or piece of code which closely follows the most common idioms of the Python language,
rather than implementing code using concepts common to other languages. For example, a common
idiom in Python is to loop over all elements of an iterable using a for statement. Many other languages
don’t have this type of construct, so people unfamiliar with Python sometimes use a numerical counter
instead:

for i in range(len(food)):
print(food[i])

122 Appendix A. Glossary

Python Tutorial, Release 3.7.0

special method A method that is called implicitly by Python to execute a certain operation on a type,
such as addition. Such methods have names starting and ending with double underscores. Special
methods are documented in specialnames.
statement A statement is part of a suite (a “block” of code). A statement is either an expression or one of
several constructs with a keyword, such as if, while or for.
struct sequence A tuple with named elements. Struct sequences expose an interface similar to named
tuple in that elements can either be accessed either by index or as an attribute. However, they do
not have any of the named tuple methods like _make() or _asdict(). Examples of struct sequences
include sys.float_info and the return value of os.stat().
text encoding A codec which encodes Unicode strings to bytes.
text file A file object able to read and write str objects. Often, a text file actually accesses a byte-oriented
datastream and handles the text encoding automatically. Examples of text files are files opened in text
mode ('r' or 'w'), sys.stdin, sys.stdout, and instances of io.StringIO.
See also binary file for a file object able to read and write bytes-like objects.
triple-quoted string A string which is bound by three instances of either a quotation mark (“) or an
apostrophe (‘). While they don’t provide any functionality not available with single-quoted strings,
they are useful for a number of reasons. They allow you to include unescaped single and double quotes
within a string and they can span multiple lines without the use of the continuation character, making
them especially useful when writing docstrings.
type The type of a Python object determines what kind of object it is; every object has a type. An object’s
type is accessible as its __class__ attribute or can be retrieved with type(obj).
type alias A synonym for a type, created by assigning the type to an identifier.
Type aliases are useful for simplifying type hints. For example:

from typing import List, Tuple

def remove_gray_shades(
colors: List[Tuple[int, int, int]]) -> List[Tuple[int, int, int]]:
pass

could be made more readable like this:

from typing import List, Tuple

Color = Tuple[int, int, int]

def remove_gray_shades(colors: List[Color]) -> List[Color]:

pass

See typing and PEP 484, which describe this functionality.

type hint An annotation that specifies the expected type for a variable, a class attribute, or a function
parameter or return value.
Type hints are optional and are not enforced by Python but they are useful to static type analysis
tools, and aid IDEs with code completion and refactoring.
Type hints of global variables, class attributes, and functions, but not local variables, can be accessed
using typing.get_type_hints().
See typing and PEP 484, which describe this functionality.
universal newlines A manner of interpreting text streams in which all of the following are recognized as
ending a line: the Unix end-of-line convention '\n', the Windows convention '\r\n', and the old

124 Appendix A. Glossary

Python Tutorial, Release 3.7.0

126 Appendix A. Glossary

Python Tutorial, Release 3.7.0

128 Appendix B. About these documents

Python Tutorial, Release 3.7.0

C.2 Terms and conditions for accessing or otherwise using Python

C.2.1 PSF LICENSE AGREEMENT FOR PYTHON 3.7.0

1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and
the Individual or Organization ("Licensee") accessing and otherwise using Python
3.7.0 software in source or binary form and its associated documentation.

2. Subject to the terms and conditions of this License Agreement, PSF hereby
grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
analyze, test, perform and/or display publicly, prepare derivative works,
distribute, and otherwise use Python 3.7.0 alone or in any derivative
version, provided, however, that PSF's License Agreement and PSF's notice of
copyright, i.e., "Copyright © 2001-2018 Python Software Foundation; All Rights
Reserved" are retained in Python 3.7.0 alone or in any derivative version
prepared by Licensee.

3. In the event Licensee prepares a derivative work that is based on or

incorporates Python 3.7.0 or any part thereof, and wants to make the
derivative work available to others as provided herein, then Licensee hereby
agrees to include in any such work a brief summary of the changes made to Python
3.7.0.

4. PSF is making Python 3.7.0 available to Licensee on an "AS IS" basis.

PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF
EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
USE OF PYTHON 3.7.0 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 3.7.0
FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 3.7.0, OR ANY DERIVATIVE
THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material breach of

its terms and conditions.

7. Nothing in this License Agreement shall be deemed to create any relationship

of agency, partnership, or joint venture between PSF and Licensee. This License
Agreement does not grant permission to use PSF trademarks or trade name in a
trademark sense to endorse or promote products or services of Licensee, or any
third party.

8. By copying, installing or otherwise using Python 3.7.0, Licensee agrees

to be bound by the terms and conditions of this License Agreement.

C.2.2 BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0

BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1

1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an office at

160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization
(continues on next page)

130 Appendix C. History and License

Python Tutorial, Release 3.7.0

(continued from previous page)

Agreement. This Agreement together with Python 1.6.1 may be located on the
Internet using the following unique, persistent identifier (known as a handle):
1895.22/1013. This Agreement may also be obtained from a proxy server on the
Internet using the following URL: http://hdl.handle.net/1895.22/1013."

3. In the event Licensee prepares a derivative work that is based on or

incorporates Python 1.6.1 or any part thereof, and wants to make the derivative
work available to others as provided herein, then Licensee hereby agrees to
include in any such work a brief summary of the changes made to Python 1.6.1.

4. CNRI is making Python 1.6.1 available to Licensee on an "AS IS" basis. CNRI
MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE,
BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY
OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF
PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR
ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE
THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material breach of

its terms and conditions.

7. This License Agreement shall be governed by the federal intellectual property

law of the United States, including without limitation the federal copyright
law, and, to the extent such U.S. federal law does not apply, by the law of the
Commonwealth of Virginia, excluding Virginia's conflict of law provisions.
Notwithstanding the foregoing, with regard to derivative works based on Python
1.6.1 that incorporate non-separable material that was previously distributed
under the GNU General Public License (GPL), the law of the Commonwealth of
Virginia shall govern this License Agreement only as to issues arising under or
with respect to Paragraphs 4, 5, and 7 of this License Agreement. Nothing in
this License Agreement shall be deemed to create any relationship of agency,
partnership, or joint venture between CNRI and Licensee. This License Agreement
does not grant permission to use CNRI trademarks or trade name in a trademark
sense to endorse or promote products or services of Licensee, or any third
party.

8. By clicking on the "ACCEPT" button where indicated, or by copying, installing

or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and
conditions of this License Agreement.

C.2.4 CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2

Copyright © 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The

Netherlands. All rights reserved.

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided that
the above copyright notice appear in all copies and that both that copyright
notice and this permission notice appear in supporting documentation, and that
the name of Stichting Mathematisch Centrum or CWI not be used in advertising or
publicity pertaining to distribution of the software without specific, written
prior permission.
(continues on next page)

132 Appendix C. History and License

Python Tutorial, Release 3.7.0

(continued from previous page)

SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Any feedback is very welcome.

http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html
email: m-mat @ math.sci.hiroshima-u.ac.jp (remove space)

C.3.2 Sockets
The socket module uses the functions, getaddrinfo(), and getnameinfo(), which are coded in separate
source files from the WIDE Project, http://www.wide.ad.jp/.

Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.

All rights reserved.

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the project nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

C.3.3 Asynchronous socket services

The asynchat and asyncore modules contain the following notice:

Copyright 1996 by Sam Rushing

All Rights Reserved

Permission to use, copy, modify, and distribute this software and

its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of Sam
Rushing not be used in advertising or publicity pertaining to
(continues on next page)

134 Appendix C. History and License

Python Tutorial, Release 3.7.0

(continued from previous page)

Copyright 1995-1997, Automatrix, Inc., all rights reserved.

Author: Skip Montanaro

Copyright 1991-1995, Stichting Mathematisch Centrum, all rights reserved.

Permission to use, copy, modify, and distribute this Python software and
its associated documentation for any purpose without fee is hereby
granted, provided that the above copyright notice appears in all copies,
and that both that copyright notice and this permission notice appear in
supporting documentation, and that the name of neither Automatrix,
Bioreason or Mojam Media be used in advertising or publicity pertaining to
distribution of the software without specific, written prior permission.

C.3.6 UUencode and UUdecode functions

The uu module contains the following notice:

Copyright 1994 by Lance Ellinghouse

Cathedral City, California Republic, United States of America.
All Rights Reserved
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Lance Ellinghouse
not be used in advertising or publicity pertaining to distribution
of the software without specific, written prior permission.
LANCE ELLINGHOUSE DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL LANCE ELLINGHOUSE CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Modified by Jack Jansen, CWI, July 1995:

- Use binascii module to do the actual line-by-line conversion
between ascii and binary. This results in a 1000-fold speedup. The C
version is still 5 times faster, though.
- Arguments more compliant with Python standard

C.3.7 XML Remote Procedure Calls

The xmlrpc.client module contains the following notice:

The XML-RPC client interface is

Copyright (c) 1999-2002 by Secret Labs AB

Copyright (c) 1999-2002 by Fredrik Lundh

By obtaining, using, and/or copying this software and/or its

(continues on next page)

136 Appendix C. History and License

Python Tutorial, Release 3.7.0

(continued from previous page)

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

C.3.10 SipHash24
The file Python/pyhash.c contains Marek Majkowski’ implementation of Dan Bernstein’s SipHash24 algo-
rithm. The contains the following note:

<MIT License>
Copyright (c) 2013 Marek Majkowski <marek@popcount.org>

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
</MIT License>

Original location:
https://github.com/majek/csiphash/

Solution inspired by code from:

Samuel Neves (supercop/crypto_auth/siphash24/little)
djb (supercop/crypto_auth/siphash24/little2)
Jean-Philippe Aumasson (https://131002.net/siphash/siphash24.c)

C.3.11 strtod and dtoa

The file Python/dtoa.c, which supplies C functions dtoa and strtod for conversion of C doubles to and
from strings, is derived from the file of the same name by David M. Gay, currently available from http:
//www.netlib.org/fp/. The original file, as retrieved on March 16, 2009, contains the following copyright
and licensing notice:

138 Appendix C. History and License

Python Tutorial, Release 3.7.0

(continued from previous page)

*
* 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
* endorse or promote products derived from this software without
* prior written permission. For written permission, please contact
* openssl-core@openssl.org.
*
* 5. Products derived from this software may not be called "OpenSSL"
* nor may "OpenSSL" appear in their names without prior written
* permission of the OpenSSL Project.
*
* 6. Redistributions of any form whatsoever must retain the following
* acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit (http://www.openssl.org/)"
*
* THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
* EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
* ====================================================================
*
* This product includes cryptographic software written by Eric Young
* (eay@cryptsoft.com). This product includes software written by Tim
* Hudson (tjh@cryptsoft.com).
*
*/

Original SSLeay License

-----------------------

/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)

* All rights reserved.
*
* This package is an SSL implementation written
* by Eric Young (eay@cryptsoft.com).
* The implementation was written so as to conform with Netscapes SSL.
*
* This library is free for commercial and non-commercial use as long as
* the following conditions are aheared to. The following conditions
* apply to all code found in this distribution, be it the RC4, RSA,
* lhash, DES, etc., code; not just the SSL code. The SSL documentation
* included with this distribution is covered by the same copyright terms
* except that the holder is Tim Hudson (tjh@cryptsoft.com).
*
* Copyright remains Eric Young's, and as such any Copyright notices in
* the code are not to be removed.
* If this package is used in a product, Eric Young should be given attribution
* as the author of the parts of the library used.

(continues on next page)

140 Appendix C. History and License

Python Tutorial, Release 3.7.0

(continued from previous page)

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

C.3.14 libffi
The _ctypes extension is built using an included copy of the libffi sources unless the build is configured
--with-system-libffi:

Copyright (c) 1996-2008 Red Hat, Inc and others.

Permission is hereby granted, free of charge, to any person obtaining

a copy of this software and associated documentation files (the
``Software''), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,

EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

C.3.15 zlib
The zlib extension is built using an included copy of the zlib sources if the zlib version found on the system
is too old to be used for the build:

Copyright (C) 1995-2011 Jean-loup Gailly and Mark Adler

This software is provided 'as-is', without any express or implied

warranty. In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,

including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

(continues on next page)

142 Appendix C. History and License

Python Tutorial, Release 3.7.0

C.3.17 libmpdec
The _decimal module is built using an included copy of the libmpdec library unless the build is configured
--with-system-libmpdec:

Copyright (c) 2008-2016 Stefan Krah. All rights reserved.

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright

notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright

notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

144 Appendix C. History and License

Python Tutorial, Release 3.7.0

146 Appendix D. Copyright

Python Tutorial, Release 3.7.0

function annotation, 117 json, 59

search path, 45
G sys, 46
garbage collection, 117 module spec, 120
generator, 117, 117 MRO, 120
generator expression, 117, 117 mutable, 120
generator iterator, 117
generic function, 118 N
GIL, 118 named tuple, 120
global interpreter lock, 118 namespace, 121
namespace package, 121
H nested scope, 121
hash-based pyc, 118 new-style class, 121
hashable, 118
help O
built-in function, 83 object, 121
file, 57
I method, 73
IDLE, 118 open
immutable, 118 built-in function, 57
import path, 118
importer, 118 P
importing, 118 package, 121
interactive, 118 parameter, 121
interpreted, 118 PATH, 45, 111
interpreter shutdown, 119 path
iterable, 119 module search, 45
iterator, 119 path based finder, 122
path entry, 122
J path entry finder, 122
json path entry hook, 122
module, 59 path-like object, 122
PEP, 122
K portion, 122
key function, 119 positional argument, 122
keyword argument, 119 provisional API, 122
provisional package, 122
L Python 3000, 122
lambda, 119 Python Enhancement Proposals
LBYL, 119 PEP 1, 122
list, 120 PEP 238, 117
list comprehension, 120 PEP 278, 125
loader, 120 PEP 302, 117, 120
PEP 3107, 28
M PEP 3116, 125
PEP 3147, 46
mapping, 120
PEP 3155, 123
meta path finder, 120
PEP 343, 115
metaclass, 120
PEP 362, 114, 122
method, 120
PEP 411, 122
object, 73
PEP 420, 117, 121, 122
method resolution order, 120
PEP 443, 118
module, 120
PEP 451, 117
builtins, 47
PEP 484, 28, 113, 117, 124, 125

148 Index