The Python Library Reference
Release 3.10.8
Guido van Rossum
and the Python development team
October 11, 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 29
3.1 Constants added by the site module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4 Built-in Types 31
4.1 Truth Value Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.2 Boolean Operations — and, or, not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.3 Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.4 Numeric Types — int, float, complex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.4.1 Bitwise Operations on Integer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.4.2 Additional Methods on Integer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.4.3 Additional Methods on Float . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.4.4 Hashing of numeric types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.5 Iterator Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.5.1 Generator Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.6 Sequence Types — list, tuple, range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.6.1 Common Sequence Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.6.2 Immutable Sequence Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.6.3 Mutable Sequence Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.6.4 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.6.5 Tuples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.6.6 Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.7 Text Sequence Type — str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4.7.1 String Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.7.2 printf-style String Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.8 Binary Sequence Types — bytes, bytearray, memoryview . . . . . . . . . . . . . . . . . . . 57
4.8.1 Bytes Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4.8.2 Bytearray Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
4.8.3 Bytes and Bytearray Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
4.8.4 printf-style Bytes Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
4.8.5 Memory Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
4.9 Set Types — set, frozenset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
4.10 Mapping Types — dict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
4.10.1 Dictionary view objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
4.11 Context Manager Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
4.12 Type Annotation Types — Generic Alias, Union . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
i
4.12.1 Generic Alias Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
4.12.2 Union Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
4.13 Other Built-in Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
4.13.1 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.13.2 Classes and Class Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.13.3 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.13.4 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.13.5 Code Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
4.13.6 Type Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
4.13.7 The Null Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
4.13.8 The Ellipsis Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
4.13.9 The NotImplemented Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
4.13.10 Boolean Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
4.13.11 Internal Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
4.14 Special Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
4.15 Integer string conversion length limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
4.15.1 Aected APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
4.15.2 Conguring the limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
4.15.3 Recommended conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
5 Built-in Exceptions 99
5.1 Exception context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
5.2 Inheriting from built-in exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
5.3 Base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
5.4 Concrete exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
5.4.1 OS exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
5.5 Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
5.6 Exception hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
6 Text Processing Services 111
6.1 string — Common string operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
6.1.1 String constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
6.1.2 Custom String Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
6.1.3 Format String Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
6.1.4 Template strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
6.1.5 Helper functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
6.2 re — Regular expression operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
6.2.1 Regular Expression Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
6.2.2 Module Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
6.2.3 Regular Expression Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.2.4 Match Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
6.2.5 Regular Expression Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
6.3 difflib — Helpers for computing deltas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
6.3.1 SequenceMatcher Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
6.3.2 SequenceMatcher Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
6.3.3 Dier Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
6.3.4 Dier Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
6.3.5 A command-line interface to diib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
6.4 textwrap — Text wrapping and lling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
6.5 unicodedata — Unicode Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
6.6 stringprep — Internet String Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
6.7 readline — GNU readline interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.7.1 Init le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.7.2 Line buer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
ii
6.7.3 History le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.7.4 History list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.7.5 Startup hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.7.6 Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
6.7.7 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
6.8 rlcompleter — Completion function for GNU readline . . . . . . . . . . . . . . . . . . . . . . . 165
6.8.1 Completer Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
7 Binary Data Services 167
7.1 struct — Interpret bytes as packed binary data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
7.1.1 Functions and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
7.1.2 Format Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
7.1.3 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
7.2 codecs — Codec registry and base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
7.2.1 Codec Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
7.2.2 Encodings and Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
7.2.3 Standard Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
7.2.4 Python Specic Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
7.2.5 encodings.idna — Internationalized Domain Names in Applications . . . . . . . . . . . 189
7.2.6 encodings.mbcs — Windows ANSI codepage . . . . . . . . . . . . . . . . . . . . . . . 189
7.2.7 encodings.utf_8_sig — UTF-8 codec with BOM signature . . . . . . . . . . . . . . 190
8 Data Types 191
8.1 datetime — Basic date and time types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
8.1.1 Aware and Naive Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
8.1.2 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
8.1.3 Available Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
8.1.4 timedelta Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
8.1.5 date Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
8.1.6 datetime Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
8.1.7 time Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
8.1.8 tzinfo Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
8.1.9 timezone Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
8.1.10 strftime() and strptime() Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . 223
8.2 zoneinfo — IANA time zone support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
8.2.1 Using ZoneInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
8.2.2 Data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
8.2.3 The ZoneInfo class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
8.2.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
8.2.5 Globals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
8.2.6 Exceptions and warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.3 calendar — General calendar-related functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.4 collections — Container datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
8.4.1 ChainMap objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.4.2 Counter objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
8.4.3 deque objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
8.4.4 defaultdict objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
8.4.5 namedtuple() Factory Function for Tuples with Named Fields . . . . . . . . . . . . . . . 248
8.4.6 OrderedDict objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
8.4.7 UserDict objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
8.4.8 UserList objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
8.4.9 UserString objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
8.5 collections.abc — Abstract Base Classes for Containers . . . . . . . . . . . . . . . . . . . . . 255
8.5.1 Collections Abstract Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
iii
