The Python Library Reference
Release 3.7.0
Guido van Rossum
and the Python development team
September 20, 2018
Python Software Foundation
Email: docs@python.org
CONTENTS
1 Introduction 3
2 Built-in Functions 5
3 Built-in Constants 27
3.1 Constants added by the site module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4 Built-in Types 29
4.1 Truth Value Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.2 Boolean Operations — and, or, not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.3 Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.4 Numeric Types — int, float, complex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.5 Iterator Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.6 Sequence Types — list, tuple, range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.7 Text Sequence Type — str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.8 Binary Sequence Types — bytes, bytearray, memoryview . . . . . . . . . . . . . . . . . . . 53
4.9 Set Types — set, frozenset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
4.10 Mapping Types — dict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
4.11 Context Manager Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
4.12 Other Built-in Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
4.13 Special Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
5 Built-in Exceptions 85
5.1 Base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
5.2 Concrete exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
5.3 Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
5.4 Exception hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6 Text Processing Services 95
6.1 string — Common string operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
6.2 re — Regular expression operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
6.3 difflib — Helpers for computing deltas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
6.4 textwrap — Text wrapping and filling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.5 unicodedata — Unicode Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
6.6 stringprep — Internet String Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
6.7 readline — GNU readline interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.8 rlcompleter — Completion function for GNU readline . . . . . . . . . . . . . . . . . . . . . 147
7 Binary Data Services 149
7.1 struct — Interpret bytes as packed binary data . . . . . . . . . . . . . . . . . . . . . . . . . 149
7.2 codecs — Codec registry and base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
i
8 Data Types 173
8.1 datetime — Basic date and time types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
8.2 calendar — General calendar-related functions . . . . . . . . . . . . . . . . . . . . . . . . . 203
8.3 collections — Container datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
8.4 collections.abc — Abstract Base Classes for Containers . . . . . . . . . . . . . . . . . . . 224
8.5 heapq — Heap queue algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
8.6 bisect — Array bisection algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.7 array — Efficient arrays of numeric values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
8.8 weakref — Weak references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.9 types — Dynamic type creation and names for built-in types . . . . . . . . . . . . . . . . . . 245
8.10 copy — Shallow and deep copy operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
8.11 pprint — Data pretty printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
8.12 reprlib — Alternate repr() implementation . . . . . . . . . . . . . . . . . . . . . . . . . . 255
8.13 enum — Support for enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
9 Numeric and Mathematical Modules 275
9.1 numbers — Numeric abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
9.2 math — Mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
9.3 cmath — Mathematical functions for complex numbers . . . . . . . . . . . . . . . . . . . . . 283
9.4 decimal — Decimal fixed point and floating point arithmetic . . . . . . . . . . . . . . . . . . 287
9.5 fractions — Rational numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
9.6 random — Generate pseudo-random numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
9.7 statistics — Mathematical statistics functions . . . . . . . . . . . . . . . . . . . . . . . . . 323
10 Functional Programming Modules 329
10.1 itertools — Functions creating iterators for efficient looping . . . . . . . . . . . . . . . . . 329
10.2 functools — Higher-order functions and operations on callable objects . . . . . . . . . . . . 343
10.3 operator — Standard operators as functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
11 File and Directory Access 359
11.1 pathlib — Object-oriented filesystem paths . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
11.2 os.path — Common pathname manipulations . . . . . . . . . . . . . . . . . . . . . . . . . . 375
11.3 fileinput — Iterate over lines from multiple input streams . . . . . . . . . . . . . . . . . . 380
11.4 stat — Interpreting stat() results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
11.5 filecmp — File and Directory Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
11.6 tempfile — Generate temporary files and directories . . . . . . . . . . . . . . . . . . . . . . 389
11.7 glob — Unix style pathname pattern expansion . . . . . . . . . . . . . . . . . . . . . . . . . 393
11.8 fnmatch — Unix filename pattern matching . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
11.9 linecache — Random access to text lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
11.10 shutil — High-level file operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
11.11 macpath — Mac OS 9 path manipulation functions . . . . . . . . . . . . . . . . . . . . . . . 404
12 Data Persistence 407
12.1 pickle — Python object serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
12.2 copyreg — Register pickle support functions . . . . . . . . . . . . . . . . . . . . . . . . . . 420
12.3 shelve — Python object persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
12.4 marshal — Internal Python object serialization . . . . . . . . . . . . . . . . . . . . . . . . . 423
12.5 dbm — Interfaces to Unix “databases” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
12.6 sqlite3 — DB-API 2.0 interface for SQLite databases . . . . . . . . . . . . . . . . . . . . . 429
13 Data Compression and Archiving 451
13.1 zlib — Compression compatible with gzip . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
13.2 gzip — Support for gzip files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
13.3 bz2 — Support for bzip2 compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
13.4 lzma — Compression using the LZMA algorithm . . . . . . . . . . . . . . . . . . . . . . . . . 460
ii
13.5 zipfile — Work with ZIP archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
13.6 tarfile — Read and write tar archive files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
14 File Formats 485
14.1 csv — CSV File Reading and Writing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
14.2 configparser — Configuration file parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
14.3 netrc — netrc file processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
14.4 xdrlib — Encode and decode XDR data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
14.5 plistlib — Generate and parse Mac OS X .plist files . . . . . . . . . . . . . . . . . . . . 513
15 Cryptographic Services 517
15.1 hashlib — Secure hashes and message digests . . . . . . . . . . . . . . . . . . . . . . . . . . 517
15.2 hmac — Keyed-Hashing for Message Authentication . . . . . . . . . . . . . . . . . . . . . . . 527
15.3 secrets — Generate secure random numbers for managing secrets . . . . . . . . . . . . . . . 529
16 Generic Operating System Services 533
16.1 os — Miscellaneous operating system interfaces . . . . . . . . . . . . . . . . . . . . . . . . . 533
16.2 io — Core tools for working with streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
16.3 time — Time access and conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593
16.4 argparse — Parser for command-line options, arguments and sub-commands . . . . . . . . . 602
16.5 getopt — C-style parser for command line options . . . . . . . . . . . . . . . . . . . . . . . 634
16.6 logging — Logging facility for Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
16.7 logging.config — Logging configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
16.8 logging.handlers — Logging handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
16.9 getpass — Portable password input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
16.10 curses — Terminal handling for character-cell displays . . . . . . . . . . . . . . . . . . . . . 676
16.11 curses.textpad — Text input widget for curses programs . . . . . . . . . . . . . . . . . . . 694
16.12 curses.ascii — Utilities for ASCII characters . . . . . . . . . . . . . . . . . . . . . . . . . 695
16.13 curses.panel — A panel stack extension for curses . . . . . . . . . . . . . . . . . . . . . . . 698
16.14 platform — Access to underlying platform’s identifying data . . . . . . . . . . . . . . . . . . 699
16.15 errno — Standard errno system symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
16.16 ctypes — A foreign function library for Python . . . . . . . . . . . . . . . . . . . . . . . . . 708
17 Concurrent Execution 741
17.1 threading — Thread-based parallelism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
17.2 multiprocessing — Process-based parallelism . . . . . . . . . . . . . . . . . . . . . . . . . . 753
17.3 The concurrent package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
17.4 concurrent.futures — Launching parallel tasks . . . . . . . . . . . . . . . . . . . . . . . . 796
17.5 subprocess — Subprocess management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
17.6 sched — Event scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819
17.7 queue — A synchronized queue class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
17.8 _thread — Low-level threading API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
17.9 _dummy_thread — Drop-in replacement for the _thread module . . . . . . . . . . . . . . . . 826
17.10 dummy_threading — Drop-in replacement for the threading module . . . . . . . . . . . . . 826
18 contextvars — Context Variables 829
18.1 Context Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
18.2 Manual Context Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830
18.3 asyncio support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832
19 Networking and Interprocess Communication 833
19.1 asyncio — Asynchronous I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833
19.2 socket — Low-level networking interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913
19.3 ssl — TLS/SSL wrapper for socket objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
19.4 select — Waiting for I/O completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970
iii
