The Python Library Reference
Release 3.8.16
Guido van Rossum
and the Python development team
December 06, 2022
Python Software Foundation
Email: docs@python.org
CONTENTS
1 Introduction 3
1.1 Notes on availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . 52
4.9 Set Types — set, frozenset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
4.10 Mapping Types — dict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
4.11 Context Manager Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
4.12 Other Built-in Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
4.13 Special Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
4.14 Integer string conversion length limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
5 Built-in Exceptions 87
5.1 Base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
5.2 Concrete exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
5.3 Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
5.4 Exception hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
6 Text Processing Services 97
6.1 string — Common string operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
6.2 re — Regular expression operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
6.3 difflib — Helpers for computing deltas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
6.4 textwrap — Text wrapping and lling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.5 unicodedata — Unicode Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
6.6 stringprep — Internet String Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
6.7 readline — GNU readline interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
6.8 rlcompleter — Completion function for GNU readline . . . . . . . . . . . . . . . . . . . . . 146
7 Binary Data Services 149
7.1 struct — Interpret bytes as packed binary data . . . . . . . . . . . . . . . . . . . . . . . . . . 149
7.2 codecs — Codec registry and base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
8 Data Types 171
i
8.1 datetime — Basic date and time types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
8.2 calendar — General calendar-related functions . . . . . . . . . . . . . . . . . . . . . . . . . . 205
8.3 collections — Container datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
8.4 collections.abc — Abstract Base Classes for Containers . . . . . . . . . . . . . . . . . . . 225
8.5 heapq — Heap queue algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
8.6 bisect — Array bisection algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
8.7 array — Ecient arrays of numeric values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
8.8 weakref — Weak references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
8.9 types — Dynamic type creation and names for built-in types . . . . . . . . . . . . . . . . . . . 246
8.10 copy — Shallow and deep copy operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
8.11 pprint — Data pretty printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
8.12 reprlib — Alternate repr() implementation . . . . . . . . . . . . . . . . . . . . . . . . . . 257
8.13 enum — Support for enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
9 Numeric and Mathematical Modules 277
9.1 numbers — Numeric abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
9.2 math — Mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
9.3 cmath — Mathematical functions for complex numbers . . . . . . . . . . . . . . . . . . . . . . 286
9.4 decimal — Decimal xed point and oating point arithmetic . . . . . . . . . . . . . . . . . . . 289
9.5 fractions — Rational numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
9.6 random — Generate pseudo-random numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
9.7 statistics — Mathematical statistics functions . . . . . . . . . . . . . . . . . . . . . . . . . 323
10 Functional Programming Modules 335
10.1 itertools — Functions creating iterators for ecient looping . . . . . . . . . . . . . . . . . . 335
10.2 functools — Higher-order functions and operations on callable objects . . . . . . . . . . . . . 349
10.3 operator — Standard operators as functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
11 File and Directory Access 365
11.1 pathlib — Object-oriented lesystem paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
11.2 os.path — Common pathname manipulations . . . . . . . . . . . . . . . . . . . . . . . . . . 381
11.3 fileinput — Iterate over lines from multiple input streams . . . . . . . . . . . . . . . . . . . 386
11.4 stat — Interpreting stat() results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
11.5 filecmp — File and Directory Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
11.6 tempfile — Generate temporary les and directories . . . . . . . . . . . . . . . . . . . . . . . 395
11.7 glob — Unix style pathname pattern expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
11.8 fnmatch — Unix lename pattern matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
11.9 linecache — Random access to text lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
11.10 shutil — High-level le operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
12 Data Persistence 413
12.1 pickle — Python object serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
12.2 copyreg — Register pickle support functions . . . . . . . . . . . . . . . . . . . . . . . . . . 428
12.3 shelve — Python object persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
12.4 marshal — Internal Python object serialization . . . . . . . . . . . . . . . . . . . . . . . . . . 432
12.5 dbm — Interfaces to Unix “databases” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
12.6 sqlite3 — DB-API 2.0 interface for SQLite databases . . . . . . . . . . . . . . . . . . . . . . 437
13 Data Compression and Archiving 459
13.1 zlib — Compression compatible with gzip . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
13.2 gzip — Support for gzip les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
13.3 bz2 — Support for bzip2 compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
13.4 lzma — Compression using the LZMA algorithm . . . . . . . . . . . . . . . . . . . . . . . . . 469
13.5 zipfile — Work with ZIP archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
13.6 tarfile — Read and write tar archive les . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
14 File Formats 495
14.1 csv — CSV File Reading and Writing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
14.2 configparser — Conguration le parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
ii
14.3 netrc — netrc le processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
14.4 xdrlib — Encode and decode XDR data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
14.5 plistlib — Generate and parse Mac OS X .plist les . . . . . . . . . . . . . . . . . . . . 521
15 Cryptographic Services 525
15.1 hashlib — Secure hashes and message digests . . . . . . . . . . . . . . . . . . . . . . . . . . 525
15.2 hmac — Keyed-Hashing for Message Authentication . . . . . . . . . . . . . . . . . . . . . . . . 535
15.3 secrets — Generate secure random numbers for managing secrets . . . . . . . . . . . . . . . . 536
16 Generic Operating System Services 539
16.1 os — Miscellaneous operating system interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . 539
16.2 io — Core tools for working with streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
16.3 time — Time access and conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
16.4 argparse — Parser for command-line options, arguments and sub-commands . . . . . . . . . . 609
16.5 getopt — C-style parser for command line options . . . . . . . . . . . . . . . . . . . . . . . . 640
16.6 logging — Logging facility for Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
16.7 logging.config — Logging conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
16.8 logging.handlers — Logging handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
16.9 getpass — Portable password input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
16.10 curses — Terminal handling for character-cell displays . . . . . . . . . . . . . . . . . . . . . . 680
16.11 curses.textpad — Text input widget for curses programs . . . . . . . . . . . . . . . . . . . 697
16.12 curses.ascii — Utilities for ASCII characters . . . . . . . . . . . . . . . . . . . . . . . . . 698
16.13 curses.panel — A panel stack extension for curses . . . . . . . . . . . . . . . . . . . . . . . 700
16.14 platform — Access to underlying platform’s identifying data . . . . . . . . . . . . . . . . . . . 702
16.15 errno — Standard errno system symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
16.16 ctypes — A foreign function library for Python . . . . . . . . . . . . . . . . . . . . . . . . . . 710
17 Concurrent Execution 743
17.1 threading — Thread-based parallelism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
17.2 multiprocessing — Process-based parallelism . . . . . . . . . . . . . . . . . . . . . . . . . 755
17.3 multiprocessing.shared_memory — Provides shared memory for direct access across
processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
17.4 The concurrent package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
17.5 concurrent.futures — Launching parallel tasks . . . . . . . . . . . . . . . . . . . . . . . 801
17.6 subprocess — Subprocess management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
17.7 sched — Event scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
17.8 queue — A synchronized queue class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825
17.9 contextvars — Context Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828
17.10 _thread — Low-level threading API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832
17.11 _dummy_thread — Drop-in replacement for the _thread module . . . . . . . . . . . . . . . 834
17.12 dummy_threading — Drop-in replacement for the threading module . . . . . . . . . . . . 834
18 Networking and Interprocess Communication 835
18.1 asyncio — Asynchronous I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
18.2 socket — Low-level networking interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
18.3 ssl — TLS/SSL wrapper for socket objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941
18.4 select — Waiting for I/O completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
18.5 selectors — High-level I/O multiplexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
18.6 asyncore — Asynchronous socket handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
18.7 asynchat — Asynchronous socket command/response handler . . . . . . . . . . . . . . . . . . 989
18.8 signal — Set handlers for asynchronous events . . . . . . . . . . . . . . . . . . . . . . . . . . 991
18.9 mmap — Memory-mapped le support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
19 Internet Data Handling 1003
19.1 email — An email and MIME handling package . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
19.2 json — JSON encoder and decoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057
19.3 mailcap — Mailcap le handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1066
19.4 mailbox — Manipulate mailboxes in various formats . . . . . . . . . . . . . . . . . . . . . . . 1067
19.5 mimetypes — Map lenames to MIME types . . . . . . . . . . . . . . . . . . . . . . . . . . . 1084
iii
