The Python Library Reference
Release 3.0
Guido van Rossum
Fred L. Drake, Jr., editor
December 04, 2008
Python Software Foundation
Email: docs@python.org
CONTENTS
1 Introduction 3
2 Built-in Functions 5
3 Built-in Constants 19
3.1 Constants added by the site module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4 Built-in Objects 21
5 Built-in Types 23
5.1 Truth Value Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.2 Boolean Operations — and, or, not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.3 Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.4 Numeric Types — int, float, complex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.5 Iterator Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.6 Sequence Types — str, bytes, bytearray, list, tuple, range . . . . . . . . . . . . . 27
5.7 Set Types — set, frozenset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.8 Mapping Types — dict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.9 File Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.10 memoryview Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5.11 Context Manager Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.12 Other Built-in Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.13 Special Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6 Built-in Exceptions 49
7 String Services 55
7.1 string — Common string operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.2 re — Regular expression operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
7.3 struct — Interpret bytes as packed binary data . . . . . . . . . . . . . . . . . . . . . . . . . . 76
7.4 difflib — Helpers for computing deltas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
7.5 textwrap — Text wrapping and filling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
7.6 codecs — Codec registry and base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
7.7 unicodedata — Unicode Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
7.8 stringprep — Internet String Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
8 Data Types 105
8.1 datetime — Basic date and time types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
8.2 calendar — General calendar-related functions . . . . . . . . . . . . . . . . . . . . . . . . . 126
8.3 collections — Container datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
8.4 heapq — Heap queue algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
8.5 bisect — Array bisection algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
8.6 array — Efficient arrays of numeric values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
8.7 sched — Event scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
i
8.8 queue — A synchronized queue class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
8.9 weakref — Weak references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
8.10 types — Names for built-in types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
8.11 copy — Shallow and deep copy operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
8.12 pprint — Data pretty printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
8.13 reprlib — Alternate repr() implementation . . . . . . . . . . . . . . . . . . . . . . . . . . 156
9 Numeric and Mathematical Modules 159
9.1 numbers — Numeric abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
9.2 math — Mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
9.3 cmath — Mathematical functions for complex numbers . . . . . . . . . . . . . . . . . . . . . . 165
9.4 decimal — Decimal fixed point and floating point arithmetic . . . . . . . . . . . . . . . . . . 167
9.5 fractions — Rational numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
9.6 random — Generate pseudo-random numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
9.7 itertools — Functions creating iterators for efficient looping . . . . . . . . . . . . . . . . . 192
9.8 functools — Higher order functions and operations on callable objects . . . . . . . . . . . . 201
9.9 operator — Standard operators as functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
10 File and Directory Access 209
10.1 os.path — Common pathname manipulations . . . . . . . . . . . . . . . . . . . . . . . . . . 209
10.2 fileinput — Iterate over lines from multiple input streams . . . . . . . . . . . . . . . . . . . 211
10.3 stat — Interpreting stat() results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
10.4 filecmp — File and Directory Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
10.5 tempfile — Generate temporary files and directories . . . . . . . . . . . . . . . . . . . . . . 216
10.6 glob — Unix style pathname pattern expansion . . . . . . . . . . . . . . . . . . . . . . . . . . 218
10.7 fnmatch — Unix filename pattern matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
10.8 linecache — Random access to text lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
10.9 shutil — High-level file operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
10.10 macpath — Mac OS 9 path manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . 222
11 Data Persistence 223
11.1 pickle — Python object serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
11.2 copyreg — Register pickle support functions . . . . . . . . . . . . . . . . . . . . . . . . . 233
11.3 shelve — Python object persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
11.4 marshal — Internal Python object serialization . . . . . . . . . . . . . . . . . . . . . . . . . . 236
11.5 dbm — Interfaces to Unix “databases” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
11.6 sqlite3 — DB-API 2.0 interface for SQLite databases . . . . . . . . . . . . . . . . . . . . . 240
12 Data Compression and Archiving 257
12.1 zlib — Compression compatible with gzip . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
12.2 gzip — Support for gzip files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
12.3 bz2 — Compression compatible with bzip2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
12.4 zipfile — Work with ZIP archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
12.5 tarfile — Read and write tar archive files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
13 File Formats 275
13.1 csv — CSV File Reading and Writing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
13.2 configparser — Configuration file parser . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
13.3 netrc — netrc file processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
13.4 xdrlib — Encode and decode XDR data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
13.5 plistlib — Generate and parse Mac OS X .plist files . . . . . . . . . . . . . . . . . . . . 290
14 Cryptographic Services 293
14.1 hashlib — Secure hashes and message digests . . . . . . . . . . . . . . . . . . . . . . . . . . 293
14.2 hmac — Keyed-Hashing for Message Authentication . . . . . . . . . . . . . . . . . . . . . . . 294
15 Generic Operating System Services 297
15.1 os — Miscellaneous operating system interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . 297
15.2 io — Core tools for working with streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
ii
15.3 time — Time access and conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
15.4 optparse — More powerful command line option parser . . . . . . . . . . . . . . . . . . . . 327
15.5 getopt — Parser for command line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
15.6 logging — Logging facility for Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
15.7 getpass — Portable password input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
15.8 curses — Terminal handling for character-cell displays . . . . . . . . . . . . . . . . . . . . . 386
15.9 curses.textpad — Text input widget for curses programs . . . . . . . . . . . . . . . . . . . 401
15.10 curses.wrapper — Terminal handler for curses programs . . . . . . . . . . . . . . . . . . . 402
15.11 curses.ascii — Utilities for ASCII characters . . . . . . . . . . . . . . . . . . . . . . . . . 402
15.12 curses.panel — A panel stack extension for curses. . . . . . . . . . . . . . . . . . . . . . . 404
15.13 platform — Access to underlying platform’s identifying data. . . . . . . . . . . . . . . . . . 406
15.14 errno — Standard errno system symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
15.15 ctypes — A foreign function library for Python. . . . . . . . . . . . . . . . . . . . . . . . . . 414
16 Optional Operating System Services 445
16.1 select — Waiting for I/O completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
16.2 threading — Higher-level threading interface . . . . . . . . . . . . . . . . . . . . . . . . . . 449
16.3 dummy_threading — Drop-in replacement for the threading module . . . . . . . . . . . 457
16.4 _thread — Low-level threading API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
16.5 _dummy_thread — Drop-in replacement for the _thread module . . . . . . . . . . . . . . 459
16.6 multiprocessing — Process-based “threading” interface . . . . . . . . . . . . . . . . . . . 459
16.7 mmap — Memory-mapped file support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
16.8 readline — GNU readline interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
16.9 rlcompleter — Completion function for GNU readline . . . . . . . . . . . . . . . . . . . . 515
17 Interprocess Communication and Networking 517
17.1 subprocess — Subprocess management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
17.2 socket — Low-level networking interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
17.3 ssl — SSL wrapper for socket objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
17.4 signal — Set handlers for asynchronous events . . . . . . . . . . . . . . . . . . . . . . . . . 539
17.5 asyncore — Asynchronous socket handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
17.6 asynchat — Asynchronous socket command/response handler . . . . . . . . . . . . . . . . . 544
18 Internet Data Handling 549
18.1 email — An email and MIME handling package . . . . . . . . . . . . . . . . . . . . . . . . . 549
18.2 json — JSON encoder and decoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
18.3 mailcap — Mailcap file handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
18.4 mailbox — Manipulate mailboxes in various formats . . . . . . . . . . . . . . . . . . . . . . . 581
18.5 mimetypes — Map filenames to MIME types . . . . . . . . . . . . . . . . . . . . . . . . . . 596
18.6 base64 — RFC 3548: Base16, Base32, Base64 Data Encodings . . . . . . . . . . . . . . . . . 598
18.7 binhex — Encode and decode binhex4 files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
18.8 binascii — Convert between binary and ASCII . . . . . . . . . . . . . . . . . . . . . . . . . 600
18.9 quopri — Encode and decode MIME quoted-printable data . . . . . . . . . . . . . . . . . . . 602
18.10 uu — Encode and decode uuencode files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
19 Structured Markup Processing Tools 605
19.1 html.parser — Simple HTML and XHTML parser . . . . . . . . . . . . . . . . . . . . . . 605
19.2 html.entities — Definitions of HTML general entities . . . . . . . . . . . . . . . . . . . . 607
19.3 xml.parsers.expat — Fast XML parsing using Expat . . . . . . . . . . . . . . . . . . . . 607
19.4 xml.dom — The Document Object Model API . . . . . . . . . . . . . . . . . . . . . . . . . . 615
19.5 xml.dom.minidom — Lightweight DOM implementation . . . . . . . . . . . . . . . . . . . 624
19.6 xml.dom.pulldom — Support for building partial DOM trees . . . . . . . . . . . . . . . . . 629
19.7 xml.sax — Support for SAX2 parsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
19.8 xml.sax.handler — Base classes for SAX handlers . . . . . . . . . . . . . . . . . . . . . . 630
19.9 xml.sax.saxutils — SAX Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
19.10 xml.sax.xmlreader — Interface for XML parsers . . . . . . . . . . . . . . . . . . . . . . 635
19.11 xml.etree.ElementTree — The ElementTree XML API . . . . . . . . . . . . . . . . . . 639
20 Internet Protocols and Support 645
iii
