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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.5.1 Generator Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.6 Sequence Types — list, tuple, range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.6.1 Common Sequence Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.6.2 Immutable Sequence Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.6.3 Mutable Sequence Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.6.4 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.6.5 Tuples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.6.6 Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.7 Text Sequence Type — str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
4.7.1 String Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4.7.2 printf-style String Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.8 Binary Sequence Types — bytes, bytearray, memoryview . . . . . . . . . . . . . . . . . 55
4.8.1 Bytes Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.8.2 Bytearray Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
4.8.3 Bytes and Bytearray Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4.8.4 printf-style Bytes Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
4.8.5 Memory Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
4.9 Set Types — set, frozenset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
4.10 Mapping Types — dict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.10.1 Dictionary view objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
4.11 Context Manager Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
4.12 Type Annotation Types — Generic Alias, Union . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
4.12.1 Generic Alias Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
4.12.2 Union Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
4.13 Other Built-in Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
4.13.1 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
i
4.13.2 Classes and Class Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
4.13.3 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
4.13.4 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
4.13.5 Code Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
4.13.6 Type Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
4.13.7 The Null Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
4.13.8 The Ellipsis Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
4.13.9 The NotImplemented Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
4.13.10 Boolean Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
4.13.11 Internal Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
4.14 Special Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
4.15 Integer string conversion length limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
4.15.1 Aected APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.15.2 Conguring the limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.15.3 Recommended conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
5 Built-in Exceptions 95
5.1 Exception context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
5.2 Inheriting from built-in exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
5.3 Base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
5.4 Concrete exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
5.4.1 OS exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
5.5 Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
5.6 Exception hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
6 Text Processing Services 107
6.1 string — Common string operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
6.1.1 String constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
6.1.2 Custom String Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
6.1.3 Format String Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
6.1.4 Template strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
6.1.5 Helper functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
6.2 re — Regular expression operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
6.2.1 Regular Expression Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
6.2.2 Module Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
6.2.3 Regular Expression Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
6.2.4 Match Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.2.5 Regular Expression Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.3 difflib — Helpers for computing deltas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
6.3.1 SequenceMatcher Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
6.3.2 SequenceMatcher Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.3.3 Dier Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.3.4 Dier Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
6.3.5 A command-line interface to diib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.4 textwrap — Text wrapping and lling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
6.5 unicodedata — Unicode Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
6.6 stringprep — Internet String Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
6.7 readline — GNU readline interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
6.7.1 Init le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
6.7.2 Line buer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
6.7.3 History le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
6.7.4 History list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
6.7.5 Startup hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
6.7.6 Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
6.7.7 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
6.8 rlcompleter — Completion function for GNU readline . . . . . . . . . . . . . . . . . . . . . 158
6.8.1 Completer Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
ii
7 Binary Data Services 159
7.1 struct — Interpret bytes as packed binary data . . . . . . . . . . . . . . . . . . . . . . . . . . 159
7.1.1 Functions and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
7.1.2 Format Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
7.1.3 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7.2 codecs — Codec registry and base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
7.2.1 Codec Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
7.2.2 Encodings and Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
7.2.3 Standard Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
7.2.4 Python Specic Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
7.2.5 encodings.idna — Internationalized Domain Names in Applications . . . . . . . . . 179
7.2.6 encodings.mbcs — Windows ANSI codepage . . . . . . . . . . . . . . . . . . . . . 180
7.2.7 encodings.utf_8_sig — UTF-8 codec with BOM signature . . . . . . . . . . . . 180
8 Data Types 181
8.1 datetime — Basic date and time types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
8.1.1 Aware and Naive Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
8.1.2 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
8.1.3 Available Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
8.1.4 timedelta Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
8.1.5 date Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
8.1.6 datetime Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
8.1.7 time Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
8.1.8 tzinfo Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
8.1.9 timezone Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
8.1.10 strftime() and strptime() Behavior . . . . . . . . . . . . . . . . . . . . . . . . 211
8.2 zoneinfo — IANA time zone support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
8.2.1 Using ZoneInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
8.2.2 Data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
8.2.3 The ZoneInfo class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
8.2.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
8.2.5 Globals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
8.2.6 Exceptions and warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
8.3 calendar — General calendar-related functions . . . . . . . . . . . . . . . . . . . . . . . . . . 221
8.4 collections — Container datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
8.4.1 ChainMap objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
8.4.2 Counter objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
8.4.3 deque objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
8.4.4
defaultdict
objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
8.4.5 namedtuple() Factory Function for Tuples with Named Fields . . . . . . . . . . . . . 236
8.4.6 OrderedDict objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
8.4.7 UserDict objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
8.4.8 UserList objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
8.4.9 UserString objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
8.5 collections.abc — Abstract Base Classes for Containers . . . . . . . . . . . . . . . . . . . 242
8.5.1 Collections Abstract Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
8.5.2 Collections Abstract Base Classes – Detailed Descriptions . . . . . . . . . . . . . . . . . 245
8.5.3 Examples and Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
8.6 heapq — Heap queue algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
8.6.1 Basic Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
8.6.2 Priority Queue Implementation Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
8.6.3 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
8.7 bisect — Array bisection algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
8.7.1 Performance Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
8.7.2 Searching Sorted Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
8.7.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
8.8 array — Ecient arrays of numeric values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
8.9 weakref — Weak references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
iii
