The Python Library Reference
Release 3.11.1
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
1.1.1 WebAssembly platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
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 . . . . . . . . . . . . . . . . . 56
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
4.8.5 Memory Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
4.9 Set Types — set, frozenset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.10 Mapping Types — dict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
4.10.1 Dictionary view objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
4.11 Context Manager Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
4.12 Type Annotation Types — Generic Alias, Union . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
4.12.1 Generic Alias Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
4.12.2 Union Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
4.13 Other Built-in Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
i
4.13.1 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
4.13.2 Classes and Class Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
4.13.3 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
4.13.4 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
4.13.5 Code Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
4.13.6 Type Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
4.13.7 The Null Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.13.8 The Ellipsis Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.13.9 The NotImplemented Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.13.10 Boolean Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.13.11 Internal Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.14 Special Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.15 Integer string conversion length limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
4.15.1 Aected APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
4.15.2 Conguring the limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
4.15.3 Recommended conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
5 Built-in Exceptions 97
5.1 Exception context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
5.2 Inheriting from built-in exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
5.3 Base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
5.4 Concrete exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
5.4.1 OS exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
5.5 Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
5.6 Exception groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
5.7 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.3.2 SequenceMatcher Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
6.3.3 Dier Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
6.3.4 Dier Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
6.3.5 A command-line interface to diib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
6.4 textwrap — Text wrapping and lling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
6.5 unicodedata — Unicode Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
6.6 stringprep — Internet String Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
6.7 readline — GNU readline interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
6.7.1 Init le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.7.2 Line buer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.7.3 History le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.7.4 History list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.7.5 Startup hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.7.6 Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.7.7 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.8 rlcompleter — Completion function for GNU readline . . . . . . . . . . . . . . . . . . . . . 164
ii
6.8.1 Completer Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
7 Binary Data Services 165
7.1 struct — Interpret bytes as packed binary data . . . . . . . . . . . . . . . . . . . . . . . . . . 165
7.1.1 Functions and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
7.1.2 Format Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
7.1.3 Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
7.1.4 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
7.2 codecs — Codec registry and base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
7.2.1 Codec Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
7.2.2 Encodings and Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
7.2.3 Standard Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
7.2.4 Python Specic Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
7.2.5 encodings.idna — Internationalized Domain Names in Applications . . . . . . . . . 187
7.2.6 encodings.mbcs — Windows ANSI codepage . . . . . . . . . . . . . . . . . . . . . 188
7.2.7 encodings.utf_8_sig — UTF-8 codec with BOM signature . . . . . . . . . . . . 188
8 Data Types 189
8.1 datetime — Basic date and time types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
8.1.1 Aware and Naive Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
8.1.2 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
8.1.3 Available Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
8.1.4 timedelta Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
8.1.5 date Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
8.1.6 datetime Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
8.1.7 time Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
8.1.8 tzinfo Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
8.1.9 timezone Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
8.1.10 strftime() and strptime() Behavior . . . . . . . . . . . . . . . . . . . . . . . . 220
8.2 zoneinfo — IANA time zone support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
8.2.1 Using ZoneInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
8.2.2 Data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
8.2.3 The ZoneInfo class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
8.2.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
8.2.5 Globals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
8.2.6 Exceptions and warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
8.3 calendar — General calendar-related functions . . . . . . . . . . . . . . . . . . . . . . . . . . 229
8.4 collections — Container datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
8.4.1 ChainMap objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
8.4.2 Counter objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
8.4.3 deque objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
8.4.4 defaultdict objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
8.4.5 namedtuple() Factory Function for Tuples with Named Fields . . . . . . . . . . . . . 244
8.4.6 OrderedDict objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
8.4.7 UserDict objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
8.4.8 UserList objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
8.4.9 UserString objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
8.5 collections.abc — Abstract Base Classes for Containers . . . . . . . . . . . . . . . . . . . 250
8.5.1 Collections Abstract Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
8.5.2 Collections Abstract Base Classes – Detailed Descriptions . . . . . . . . . . . . . . . . . 254
8.5.3 Examples and Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
8.6 heapq — Heap queue algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
8.6.1 Basic Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
8.6.2 Priority Queue Implementation Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
8.6.3 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
8.7 bisect — Array bisection algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
8.7.1 Performance Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
8.7.2 Searching Sorted Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
iii
