1.. _glossary: 2 3******** 4Glossary 5******** 6 7.. if you add new entries, keep the alphabetical sorting! 8 9.. glossary:: 10 11 ``>>>`` 12 The default Python prompt of the interactive shell. Often seen for code 13 examples which can be executed interactively in the interpreter. 14 15 ``...`` 16 Can refer to: 17 18 * The default Python prompt of the interactive shell when entering the 19 code for an indented code block, when within a pair of matching left and 20 right delimiters (parentheses, square brackets, curly braces or triple 21 quotes), or after specifying a decorator. 22 23 * The :const:`Ellipsis` built-in constant. 24 25 2to3 26 A tool that tries to convert Python 2.x code to Python 3.x code by 27 handling most of the incompatibilities which can be detected by parsing the 28 source and traversing the parse tree. 29 30 2to3 is available in the standard library as :mod:`lib2to3`; a standalone 31 entry point is provided as :file:`Tools/scripts/2to3`. See 32 :ref:`2to3-reference`. 33 34 abstract base class 35 Abstract base classes complement :term:`duck-typing` by 36 providing a way to define interfaces when other techniques like 37 :func:`hasattr` would be clumsy or subtly wrong (for example with 38 :ref:`magic methods <special-lookup>`). ABCs introduce virtual 39 subclasses, which are classes that don't inherit from a class but are 40 still recognized by :func:`isinstance` and :func:`issubclass`; see the 41 :mod:`abc` module documentation. Python comes with many built-in ABCs for 42 data structures (in the :mod:`collections.abc` module), numbers (in the 43 :mod:`numbers` module), streams (in the :mod:`io` module), import finders 44 and loaders (in the :mod:`importlib.abc` module). You can create your own 45 ABCs with the :mod:`abc` module. 46 47 annotation 48 A label associated with a variable, a class 49 attribute or a function parameter or return value, 50 used by convention as a :term:`type hint`. 51 52 Annotations of local variables cannot be accessed at runtime, but 53 annotations of global variables, class attributes, and functions 54 are stored in the :attr:`__annotations__` 55 special attribute of modules, classes, and functions, 56 respectively. 57 58 See :term:`variable annotation`, :term:`function annotation`, :pep:`484` 59 and :pep:`526`, which describe this functionality. 60 61 argument 62 A value passed to a :term:`function` (or :term:`method`) when calling the 63 function. There are two kinds of argument: 64 65 * :dfn:`keyword argument`: an argument preceded by an identifier (e.g. 66 ``name=``) in a function call or passed as a value in a dictionary 67 preceded by ``**``. For example, ``3`` and ``5`` are both keyword 68 arguments in the following calls to :func:`complex`:: 69 70 complex(real=3, imag=5) 71 complex(**{'real': 3, 'imag': 5}) 72 73 * :dfn:`positional argument`: an argument that is not a keyword argument. 74 Positional arguments can appear at the beginning of an argument list 75 and/or be passed as elements of an :term:`iterable` preceded by ``*``. 76 For example, ``3`` and ``5`` are both positional arguments in the 77 following calls:: 78 79 complex(3, 5) 80 complex(*(3, 5)) 81 82 Arguments are assigned to the named local variables in a function body. 83 See the :ref:`calls` section for the rules governing this assignment. 84 Syntactically, any expression can be used to represent an argument; the 85 evaluated value is assigned to the local variable. 86 87 See also the :term:`parameter` glossary entry, the FAQ question on 88 :ref:`the difference between arguments and parameters 89 <faq-argument-vs-parameter>`, and :pep:`362`. 90 91 asynchronous context manager 92 An object which controls the environment seen in an 93 :keyword:`async with` statement by defining :meth:`__aenter__` and 94 :meth:`__aexit__` methods. Introduced by :pep:`492`. 95 96 asynchronous generator 97 A function which returns an :term:`asynchronous generator iterator`. It 98 looks like a coroutine function defined with :keyword:`async def` except 99 that it contains :keyword:`yield` expressions for producing a series of 100 values usable in an :keyword:`async for` loop. 101 102 Usually refers to an asynchronous generator function, but may refer to an 103 *asynchronous generator iterator* in some contexts. In cases where the 104 intended meaning isn't clear, using the full terms avoids ambiguity. 105 106 An asynchronous generator function may contain :keyword:`await` 107 expressions as well as :keyword:`async for`, and :keyword:`async with` 108 statements. 109 110 asynchronous generator iterator 111 An object created by a :term:`asynchronous generator` function. 112 113 This is an :term:`asynchronous iterator` which when called using the 114 :meth:`__anext__` method returns an awaitable object which will execute 115 the body of the asynchronous generator function until the next 116 :keyword:`yield` expression. 117 118 Each :keyword:`yield` temporarily suspends processing, remembering the 119 location execution state (including local variables and pending 120 try-statements). When the *asynchronous generator iterator* effectively 121 resumes with another awaitable returned by :meth:`__anext__`, it 122 picks up where it left off. See :pep:`492` and :pep:`525`. 123 124 asynchronous iterable 125 An object, that can be used in an :keyword:`async for` statement. 126 Must return an :term:`asynchronous iterator` from its 127 :meth:`__aiter__` method. Introduced by :pep:`492`. 128 129 asynchronous iterator 130 An object that implements the :meth:`__aiter__` and :meth:`__anext__` 131 methods. ``__anext__`` must return an :term:`awaitable` object. 132 :keyword:`async for` resolves the awaitables returned by an asynchronous 133 iterator's :meth:`__anext__` method until it raises a 134 :exc:`StopAsyncIteration` exception. Introduced by :pep:`492`. 135 136 attribute 137 A value associated with an object which is referenced by name using 138 dotted expressions. For example, if an object *o* has an attribute 139 *a* it would be referenced as *o.a*. 140 141 awaitable 142 An object that can be used in an :keyword:`await` expression. Can be 143 a :term:`coroutine` or an object with an :meth:`__await__` method. 144 See also :pep:`492`. 145 146 BDFL 147 Benevolent Dictator For Life, a.k.a. `Guido van Rossum 148 <https://gvanrossum.github.io/>`_, Python's creator. 149 150 binary file 151 A :term:`file object` able to read and write 152 :term:`bytes-like objects <bytes-like object>`. 153 Examples of binary files are files opened in binary mode (``'rb'``, 154 ``'wb'`` or ``'rb+'``), :data:`sys.stdin.buffer`, 155 :data:`sys.stdout.buffer`, and instances of :class:`io.BytesIO` and 156 :class:`gzip.GzipFile`. 157 158 See also :term:`text file` for a file object able to read and write 159 :class:`str` objects. 160 161 bytes-like object 162 An object that supports the :ref:`bufferobjects` and can 163 export a C-:term:`contiguous` buffer. This includes all :class:`bytes`, 164 :class:`bytearray`, and :class:`array.array` objects, as well as many 165 common :class:`memoryview` objects. Bytes-like objects can 166 be used for various operations that work with binary data; these include 167 compression, saving to a binary file, and sending over a socket. 168 169 Some operations need the binary data to be mutable. The documentation 170 often refers to these as "read-write bytes-like objects". Example 171 mutable buffer objects include :class:`bytearray` and a 172 :class:`memoryview` of a :class:`bytearray`. 173 Other operations require the binary data to be stored in 174 immutable objects ("read-only bytes-like objects"); examples 175 of these include :class:`bytes` and a :class:`memoryview` 176 of a :class:`bytes` object. 177 178 bytecode 179 Python source code is compiled into bytecode, the internal representation 180 of a Python program in the CPython interpreter. The bytecode is also 181 cached in ``.pyc`` files so that executing the same file is 182 faster the second time (recompilation from source to bytecode can be 183 avoided). This "intermediate language" is said to run on a 184 :term:`virtual machine` that executes the machine code corresponding to 185 each bytecode. Do note that bytecodes are not expected to work between 186 different Python virtual machines, nor to be stable between Python 187 releases. 188 189 A list of bytecode instructions can be found in the documentation for 190 :ref:`the dis module <bytecodes>`. 191 192 callback 193 A subroutine function which is passed as an argument to be executed at 194 some point in the future. 195 196 class 197 A template for creating user-defined objects. Class definitions 198 normally contain method definitions which operate on instances of the 199 class. 200 201 class variable 202 A variable defined in a class and intended to be modified only at 203 class level (i.e., not in an instance of the class). 204 205 coercion 206 The implicit conversion of an instance of one type to another during an 207 operation which involves two arguments of the same type. For example, 208 ``int(3.15)`` converts the floating point number to the integer ``3``, but 209 in ``3+4.5``, each argument is of a different type (one int, one float), 210 and both must be converted to the same type before they can be added or it 211 will raise a :exc:`TypeError`. Without coercion, all arguments of even 212 compatible types would have to be normalized to the same value by the 213 programmer, e.g., ``float(3)+4.5`` rather than just ``3+4.5``. 214 215 complex number 216 An extension of the familiar real number system in which all numbers are 217 expressed as a sum of a real part and an imaginary part. Imaginary 218 numbers are real multiples of the imaginary unit (the square root of 219 ``-1``), often written ``i`` in mathematics or ``j`` in 220 engineering. Python has built-in support for complex numbers, which are 221 written with this latter notation; the imaginary part is written with a 222 ``j`` suffix, e.g., ``3+1j``. To get access to complex equivalents of the 223 :mod:`math` module, use :mod:`cmath`. Use of complex numbers is a fairly 224 advanced mathematical feature. If you're not aware of a need for them, 225 it's almost certain you can safely ignore them. 226 227 context manager 228 An object which controls the environment seen in a :keyword:`with` 229 statement by defining :meth:`__enter__` and :meth:`__exit__` methods. 230 See :pep:`343`. 231 232 context variable 233 A variable which can have different values depending on its context. 234 This is similar to Thread-Local Storage in which each execution 235 thread may have a different value for a variable. However, with context 236 variables, there may be several contexts in one execution thread and the 237 main usage for context variables is to keep track of variables in 238 concurrent asynchronous tasks. 239 See :mod:`contextvars`. 240 241 contiguous 242 .. index:: C-contiguous, Fortran contiguous 243 244 A buffer is considered contiguous exactly if it is either 245 *C-contiguous* or *Fortran contiguous*. Zero-dimensional buffers are 246 C and Fortran contiguous. In one-dimensional arrays, the items 247 must be laid out in memory next to each other, in order of 248 increasing indexes starting from zero. In multidimensional 249 C-contiguous arrays, the last index varies the fastest when 250 visiting items in order of memory address. However, in 251 Fortran contiguous arrays, the first index varies the fastest. 252 253 coroutine 254 Coroutines are a more generalized form of subroutines. Subroutines are 255 entered at one point and exited at another point. Coroutines can be 256 entered, exited, and resumed at many different points. They can be 257 implemented with the :keyword:`async def` statement. See also 258 :pep:`492`. 259 260 coroutine function 261 A function which returns a :term:`coroutine` object. A coroutine 262 function may be defined with the :keyword:`async def` statement, 263 and may contain :keyword:`await`, :keyword:`async for`, and 264 :keyword:`async with` keywords. These were introduced 265 by :pep:`492`. 266 267 CPython 268 The canonical implementation of the Python programming language, as 269 distributed on `python.org <https://www.python.org>`_. The term "CPython" 270 is used when necessary to distinguish this implementation from others 271 such as Jython or IronPython. 272 273 decorator 274 A function returning another function, usually applied as a function 275 transformation using the ``@wrapper`` syntax. Common examples for 276 decorators are :func:`classmethod` and :func:`staticmethod`. 277 278 The decorator syntax is merely syntactic sugar, the following two 279 function definitions are semantically equivalent:: 280 281 def f(...): 282 ... 283 f = staticmethod(f) 284 285 @staticmethod 286 def f(...): 287 ... 288 289 The same concept exists for classes, but is less commonly used there. See 290 the documentation for :ref:`function definitions <function>` and 291 :ref:`class definitions <class>` for more about decorators. 292 293 descriptor 294 Any object which defines the methods :meth:`__get__`, :meth:`__set__`, or 295 :meth:`__delete__`. When a class attribute is a descriptor, its special 296 binding behavior is triggered upon attribute lookup. Normally, using 297 *a.b* to get, set or delete an attribute looks up the object named *b* in 298 the class dictionary for *a*, but if *b* is a descriptor, the respective 299 descriptor method gets called. Understanding descriptors is a key to a 300 deep understanding of Python because they are the basis for many features 301 including functions, methods, properties, class methods, static methods, 302 and reference to super classes. 303 304 For more information about descriptors' methods, see :ref:`descriptors` 305 or the :ref:`Descriptor How To Guide <descriptorhowto>`. 306 307 dictionary 308 An associative array, where arbitrary keys are mapped to values. The 309 keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods. 310 Called a hash in Perl. 311 312 dictionary comprehension 313 A compact way to process all or part of the elements in an iterable and 314 return a dictionary with the results. ``results = {n: n ** 2 for n in 315 range(10)}`` generates a dictionary containing key ``n`` mapped to 316 value ``n ** 2``. See :ref:`comprehensions`. 317 318 dictionary view 319 The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and 320 :meth:`dict.items` are called dictionary views. They provide a dynamic 321 view on the dictionary’s entries, which means that when the dictionary 322 changes, the view reflects these changes. To force the 323 dictionary view to become a full list use ``list(dictview)``. See 324 :ref:`dict-views`. 325 326 docstring 327 A string literal which appears as the first expression in a class, 328 function or module. While ignored when the suite is executed, it is 329 recognized by the compiler and put into the :attr:`__doc__` attribute 330 of the enclosing class, function or module. Since it is available via 331 introspection, it is the canonical place for documentation of the 332 object. 333 334 duck-typing 335 A programming style which does not look at an object's type to determine 336 if it has the right interface; instead, the method or attribute is simply 337 called or used ("If it looks like a duck and quacks like a duck, it 338 must be a duck.") By emphasizing interfaces rather than specific types, 339 well-designed code improves its flexibility by allowing polymorphic 340 substitution. Duck-typing avoids tests using :func:`type` or 341 :func:`isinstance`. (Note, however, that duck-typing can be complemented 342 with :term:`abstract base classes <abstract base class>`.) Instead, it 343 typically employs :func:`hasattr` tests or :term:`EAFP` programming. 344 345 EAFP 346 Easier to ask for forgiveness than permission. This common Python coding 347 style assumes the existence of valid keys or attributes and catches 348 exceptions if the assumption proves false. This clean and fast style is 349 characterized by the presence of many :keyword:`try` and :keyword:`except` 350 statements. The technique contrasts with the :term:`LBYL` style 351 common to many other languages such as C. 352 353 expression 354 A piece of syntax which can be evaluated to some value. In other words, 355 an expression is an accumulation of expression elements like literals, 356 names, attribute access, operators or function calls which all return a 357 value. In contrast to many other languages, not all language constructs 358 are expressions. There are also :term:`statement`\s which cannot be used 359 as expressions, such as :keyword:`while`. Assignments are also statements, 360 not expressions. 361 362 extension module 363 A module written in C or C++, using Python's C API to interact with the 364 core and with user code. 365 366 f-string 367 String literals prefixed with ``'f'`` or ``'F'`` are commonly called 368 "f-strings" which is short for 369 :ref:`formatted string literals <f-strings>`. See also :pep:`498`. 370 371 file object 372 An object exposing a file-oriented API (with methods such as 373 :meth:`read()` or :meth:`write()`) to an underlying resource. Depending 374 on the way it was created, a file object can mediate access to a real 375 on-disk file or to another type of storage or communication device 376 (for example standard input/output, in-memory buffers, sockets, pipes, 377 etc.). File objects are also called :dfn:`file-like objects` or 378 :dfn:`streams`. 379 380 There are actually three categories of file objects: raw 381 :term:`binary files <binary file>`, buffered 382 :term:`binary files <binary file>` and :term:`text files <text file>`. 383 Their interfaces are defined in the :mod:`io` module. The canonical 384 way to create a file object is by using the :func:`open` function. 385 386 file-like object 387 A synonym for :term:`file object`. 388 389 finder 390 An object that tries to find the :term:`loader` for a module that is 391 being imported. 392 393 Since Python 3.3, there are two types of finder: :term:`meta path finders 394 <meta path finder>` for use with :data:`sys.meta_path`, and :term:`path 395 entry finders <path entry finder>` for use with :data:`sys.path_hooks`. 396 397 See :pep:`302`, :pep:`420` and :pep:`451` for much more detail. 398 399 floor division 400 Mathematical division that rounds down to nearest integer. The floor 401 division operator is ``//``. For example, the expression ``11 // 4`` 402 evaluates to ``2`` in contrast to the ``2.75`` returned by float true 403 division. Note that ``(-11) // 4`` is ``-3`` because that is ``-2.75`` 404 rounded *downward*. See :pep:`238`. 405 406 function 407 A series of statements which returns some value to a caller. It can also 408 be passed zero or more :term:`arguments <argument>` which may be used in 409 the execution of the body. See also :term:`parameter`, :term:`method`, 410 and the :ref:`function` section. 411 412 function annotation 413 An :term:`annotation` of a function parameter or return value. 414 415 Function annotations are usually used for 416 :term:`type hints <type hint>`: for example, this function is expected to take two 417 :class:`int` arguments and is also expected to have an :class:`int` 418 return value:: 419 420 def sum_two_numbers(a: int, b: int) -> int: 421 return a + b 422 423 Function annotation syntax is explained in section :ref:`function`. 424 425 See :term:`variable annotation` and :pep:`484`, 426 which describe this functionality. 427 428 __future__ 429 A :ref:`future statement <future>`, ``from __future__ import <feature>``, 430 directs the compiler to compile the current module using syntax or 431 semantics that will become standard in a future release of Python. 432 The :mod:`__future__` module documents the possible values of 433 *feature*. By importing this module and evaluating its variables, 434 you can see when a new feature was first added to the language and 435 when it will (or did) become the default:: 436 437 >>> import __future__ 438 >>> __future__.division 439 _Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192) 440 441 garbage collection 442 The process of freeing memory when it is not used anymore. Python 443 performs garbage collection via reference counting and a cyclic garbage 444 collector that is able to detect and break reference cycles. The 445 garbage collector can be controlled using the :mod:`gc` module. 446 447 .. index:: single: generator 448 449 generator 450 A function which returns a :term:`generator iterator`. It looks like a 451 normal function except that it contains :keyword:`yield` expressions 452 for producing a series of values usable in a for-loop or that can be 453 retrieved one at a time with the :func:`next` function. 454 455 Usually refers to a generator function, but may refer to a 456 *generator iterator* in some contexts. In cases where the intended 457 meaning isn't clear, using the full terms avoids ambiguity. 458 459 generator iterator 460 An object created by a :term:`generator` function. 461 462 Each :keyword:`yield` temporarily suspends processing, remembering the 463 location execution state (including local variables and pending 464 try-statements). When the *generator iterator* resumes, it picks up where 465 it left off (in contrast to functions which start fresh on every 466 invocation). 467 468 .. index:: single: generator expression 469 470 generator expression 471 An expression that returns an iterator. It looks like a normal expression 472 followed by a :keyword:`!for` clause defining a loop variable, range, 473 and an optional :keyword:`!if` clause. The combined expression 474 generates values for an enclosing function:: 475 476 >>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81 477 285 478 479 generic function 480 A function composed of multiple functions implementing the same operation 481 for different types. Which implementation should be used during a call is 482 determined by the dispatch algorithm. 483 484 See also the :term:`single dispatch` glossary entry, the 485 :func:`functools.singledispatch` decorator, and :pep:`443`. 486 487 generic type 488 A :term:`type` that can be parameterized; typically a 489 :ref:`container class<sequence-types>` such as :class:`list` or 490 :class:`dict`. Used for :term:`type hints <type hint>` and 491 :term:`annotations <annotation>`. 492 493 For more details, see :ref:`generic alias types<types-genericalias>`, 494 :pep:`483`, :pep:`484`, :pep:`585`, and the :mod:`typing` module. 495 496 GIL 497 See :term:`global interpreter lock`. 498 499 global interpreter lock 500 The mechanism used by the :term:`CPython` interpreter to assure that 501 only one thread executes Python :term:`bytecode` at a time. 502 This simplifies the CPython implementation by making the object model 503 (including critical built-in types such as :class:`dict`) implicitly 504 safe against concurrent access. Locking the entire interpreter 505 makes it easier for the interpreter to be multi-threaded, at the 506 expense of much of the parallelism afforded by multi-processor 507 machines. 508 509 However, some extension modules, either standard or third-party, 510 are designed so as to release the GIL when doing computationally-intensive 511 tasks such as compression or hashing. Also, the GIL is always released 512 when doing I/O. 513 514 Past efforts to create a "free-threaded" interpreter (one which locks 515 shared data at a much finer granularity) have not been successful 516 because performance suffered in the common single-processor case. It 517 is believed that overcoming this performance issue would make the 518 implementation much more complicated and therefore costlier to maintain. 519 520 521 hash-based pyc 522 A bytecode cache file that uses the hash rather than the last-modified 523 time of the corresponding source file to determine its validity. See 524 :ref:`pyc-invalidation`. 525 526 hashable 527 An object is *hashable* if it has a hash value which never changes during 528 its lifetime (it needs a :meth:`__hash__` method), and can be compared to 529 other objects (it needs an :meth:`__eq__` method). Hashable objects which 530 compare equal must have the same hash value. 531 532 Hashability makes an object usable as a dictionary key and a set member, 533 because these data structures use the hash value internally. 534 535 Most of Python's immutable built-in objects are hashable; mutable 536 containers (such as lists or dictionaries) are not; immutable 537 containers (such as tuples and frozensets) are only hashable if 538 their elements are hashable. Objects which are 539 instances of user-defined classes are hashable by default. They all 540 compare unequal (except with themselves), and their hash value is derived 541 from their :func:`id`. 542 543 IDLE 544 An Integrated Development Environment for Python. IDLE is a basic editor 545 and interpreter environment which ships with the standard distribution of 546 Python. 547 548 immutable 549 An object with a fixed value. Immutable objects include numbers, strings and 550 tuples. Such an object cannot be altered. A new object has to 551 be created if a different value has to be stored. They play an important 552 role in places where a constant hash value is needed, for example as a key 553 in a dictionary. 554 555 import path 556 A list of locations (or :term:`path entries <path entry>`) that are 557 searched by the :term:`path based finder` for modules to import. During 558 import, this list of locations usually comes from :data:`sys.path`, but 559 for subpackages it may also come from the parent package's ``__path__`` 560 attribute. 561 562 importing 563 The process by which Python code in one module is made available to 564 Python code in another module. 565 566 importer 567 An object that both finds and loads a module; both a 568 :term:`finder` and :term:`loader` object. 569 570 interactive 571 Python has an interactive interpreter which means you can enter 572 statements and expressions at the interpreter prompt, immediately 573 execute them and see their results. Just launch ``python`` with no 574 arguments (possibly by selecting it from your computer's main 575 menu). It is a very powerful way to test out new ideas or inspect 576 modules and packages (remember ``help(x)``). 577 578 interpreted 579 Python is an interpreted language, as opposed to a compiled one, 580 though the distinction can be blurry because of the presence of the 581 bytecode compiler. This means that source files can be run directly 582 without explicitly creating an executable which is then run. 583 Interpreted languages typically have a shorter development/debug cycle 584 than compiled ones, though their programs generally also run more 585 slowly. See also :term:`interactive`. 586 587 interpreter shutdown 588 When asked to shut down, the Python interpreter enters a special phase 589 where it gradually releases all allocated resources, such as modules 590 and various critical internal structures. It also makes several calls 591 to the :term:`garbage collector <garbage collection>`. This can trigger 592 the execution of code in user-defined destructors or weakref callbacks. 593 Code executed during the shutdown phase can encounter various 594 exceptions as the resources it relies on may not function anymore 595 (common examples are library modules or the warnings machinery). 596 597 The main reason for interpreter shutdown is that the ``__main__`` module 598 or the script being run has finished executing. 599 600 iterable 601 An object capable of returning its members one at a time. Examples of 602 iterables include all sequence types (such as :class:`list`, :class:`str`, 603 and :class:`tuple`) and some non-sequence types like :class:`dict`, 604 :term:`file objects <file object>`, and objects of any classes you define 605 with an :meth:`__iter__` method or with a :meth:`__getitem__` method 606 that implements :term:`Sequence <sequence>` semantics. 607 608 Iterables can be 609 used in a :keyword:`for` loop and in many other places where a sequence is 610 needed (:func:`zip`, :func:`map`, ...). When an iterable object is passed 611 as an argument to the built-in function :func:`iter`, it returns an 612 iterator for the object. This iterator is good for one pass over the set 613 of values. When using iterables, it is usually not necessary to call 614 :func:`iter` or deal with iterator objects yourself. The ``for`` 615 statement does that automatically for you, creating a temporary unnamed 616 variable to hold the iterator for the duration of the loop. See also 617 :term:`iterator`, :term:`sequence`, and :term:`generator`. 618 619 iterator 620 An object representing a stream of data. Repeated calls to the iterator's 621 :meth:`~iterator.__next__` method (or passing it to the built-in function 622 :func:`next`) return successive items in the stream. When no more data 623 are available a :exc:`StopIteration` exception is raised instead. At this 624 point, the iterator object is exhausted and any further calls to its 625 :meth:`__next__` method just raise :exc:`StopIteration` again. Iterators 626 are required to have an :meth:`__iter__` method that returns the iterator 627 object itself so every iterator is also iterable and may be used in most 628 places where other iterables are accepted. One notable exception is code 629 which attempts multiple iteration passes. A container object (such as a 630 :class:`list`) produces a fresh new iterator each time you pass it to the 631 :func:`iter` function or use it in a :keyword:`for` loop. Attempting this 632 with an iterator will just return the same exhausted iterator object used 633 in the previous iteration pass, making it appear like an empty container. 634 635 More information can be found in :ref:`typeiter`. 636 637 key function 638 A key function or collation function is a callable that returns a value 639 used for sorting or ordering. For example, :func:`locale.strxfrm` is 640 used to produce a sort key that is aware of locale specific sort 641 conventions. 642 643 A number of tools in Python accept key functions to control how elements 644 are ordered or grouped. They include :func:`min`, :func:`max`, 645 :func:`sorted`, :meth:`list.sort`, :func:`heapq.merge`, 646 :func:`heapq.nsmallest`, :func:`heapq.nlargest`, and 647 :func:`itertools.groupby`. 648 649 There are several ways to create a key function. For example. the 650 :meth:`str.lower` method can serve as a key function for case insensitive 651 sorts. Alternatively, a key function can be built from a 652 :keyword:`lambda` expression such as ``lambda r: (r[0], r[2])``. Also, 653 the :mod:`operator` module provides three key function constructors: 654 :func:`~operator.attrgetter`, :func:`~operator.itemgetter`, and 655 :func:`~operator.methodcaller`. See the :ref:`Sorting HOW TO 656 <sortinghowto>` for examples of how to create and use key functions. 657 658 keyword argument 659 See :term:`argument`. 660 661 lambda 662 An anonymous inline function consisting of a single :term:`expression` 663 which is evaluated when the function is called. The syntax to create 664 a lambda function is ``lambda [parameters]: expression`` 665 666 LBYL 667 Look before you leap. This coding style explicitly tests for 668 pre-conditions before making calls or lookups. This style contrasts with 669 the :term:`EAFP` approach and is characterized by the presence of many 670 :keyword:`if` statements. 671 672 In a multi-threaded environment, the LBYL approach can risk introducing a 673 race condition between "the looking" and "the leaping". For example, the 674 code, ``if key in mapping: return mapping[key]`` can fail if another 675 thread removes *key* from *mapping* after the test, but before the lookup. 676 This issue can be solved with locks or by using the EAFP approach. 677 678 list 679 A built-in Python :term:`sequence`. Despite its name it is more akin 680 to an array in other languages than to a linked list since access to 681 elements is O(1). 682 683 list comprehension 684 A compact way to process all or part of the elements in a sequence and 685 return a list with the results. ``result = ['{:#04x}'.format(x) for x in 686 range(256) if x % 2 == 0]`` generates a list of strings containing 687 even hex numbers (0x..) in the range from 0 to 255. The :keyword:`if` 688 clause is optional. If omitted, all elements in ``range(256)`` are 689 processed. 690 691 loader 692 An object that loads a module. It must define a method named 693 :meth:`load_module`. A loader is typically returned by a 694 :term:`finder`. See :pep:`302` for details and 695 :class:`importlib.abc.Loader` for an :term:`abstract base class`. 696 697 magic method 698 .. index:: pair: magic; method 699 700 An informal synonym for :term:`special method`. 701 702 mapping 703 A container object that supports arbitrary key lookups and implements the 704 methods specified in the :class:`~collections.abc.Mapping` or 705 :class:`~collections.abc.MutableMapping` 706 :ref:`abstract base classes <collections-abstract-base-classes>`. Examples 707 include :class:`dict`, :class:`collections.defaultdict`, 708 :class:`collections.OrderedDict` and :class:`collections.Counter`. 709 710 meta path finder 711 A :term:`finder` returned by a search of :data:`sys.meta_path`. Meta path 712 finders are related to, but different from :term:`path entry finders 713 <path entry finder>`. 714 715 See :class:`importlib.abc.MetaPathFinder` for the methods that meta path 716 finders implement. 717 718 metaclass 719 The class of a class. Class definitions create a class name, a class 720 dictionary, and a list of base classes. The metaclass is responsible for 721 taking those three arguments and creating the class. Most object oriented 722 programming languages provide a default implementation. What makes Python 723 special is that it is possible to create custom metaclasses. Most users 724 never need this tool, but when the need arises, metaclasses can provide 725 powerful, elegant solutions. They have been used for logging attribute 726 access, adding thread-safety, tracking object creation, implementing 727 singletons, and many other tasks. 728 729 More information can be found in :ref:`metaclasses`. 730 731 method 732 A function which is defined inside a class body. If called as an attribute 733 of an instance of that class, the method will get the instance object as 734 its first :term:`argument` (which is usually called ``self``). 735 See :term:`function` and :term:`nested scope`. 736 737 method resolution order 738 Method Resolution Order is the order in which base classes are searched 739 for a member during lookup. See `The Python 2.3 Method Resolution Order 740 <https://www.python.org/download/releases/2.3/mro/>`_ for details of the 741 algorithm used by the Python interpreter since the 2.3 release. 742 743 module 744 An object that serves as an organizational unit of Python code. Modules 745 have a namespace containing arbitrary Python objects. Modules are loaded 746 into Python by the process of :term:`importing`. 747 748 See also :term:`package`. 749 750 module spec 751 A namespace containing the import-related information used to load a 752 module. An instance of :class:`importlib.machinery.ModuleSpec`. 753 754 MRO 755 See :term:`method resolution order`. 756 757 mutable 758 Mutable objects can change their value but keep their :func:`id`. See 759 also :term:`immutable`. 760 761 named tuple 762 The term "named tuple" applies to any type or class that inherits from 763 tuple and whose indexable elements are also accessible using named 764 attributes. The type or class may have other features as well. 765 766 Several built-in types are named tuples, including the values returned 767 by :func:`time.localtime` and :func:`os.stat`. Another example is 768 :data:`sys.float_info`:: 769 770 >>> sys.float_info[1] # indexed access 771 1024 772 >>> sys.float_info.max_exp # named field access 773 1024 774 >>> isinstance(sys.float_info, tuple) # kind of tuple 775 True 776 777 Some named tuples are built-in types (such as the above examples). 778 Alternatively, a named tuple can be created from a regular class 779 definition that inherits from :class:`tuple` and that defines named 780 fields. Such a class can be written by hand or it can be created with 781 the factory function :func:`collections.namedtuple`. The latter 782 technique also adds some extra methods that may not be found in 783 hand-written or built-in named tuples. 784 785 namespace 786 The place where a variable is stored. Namespaces are implemented as 787 dictionaries. There are the local, global and built-in namespaces as well 788 as nested namespaces in objects (in methods). Namespaces support 789 modularity by preventing naming conflicts. For instance, the functions 790 :func:`builtins.open <.open>` and :func:`os.open` are distinguished by 791 their namespaces. Namespaces also aid readability and maintainability by 792 making it clear which module implements a function. For instance, writing 793 :func:`random.seed` or :func:`itertools.islice` makes it clear that those 794 functions are implemented by the :mod:`random` and :mod:`itertools` 795 modules, respectively. 796 797 namespace package 798 A :pep:`420` :term:`package` which serves only as a container for 799 subpackages. Namespace packages may have no physical representation, 800 and specifically are not like a :term:`regular package` because they 801 have no ``__init__.py`` file. 802 803 See also :term:`module`. 804 805 nested scope 806 The ability to refer to a variable in an enclosing definition. For 807 instance, a function defined inside another function can refer to 808 variables in the outer function. Note that nested scopes by default work 809 only for reference and not for assignment. Local variables both read and 810 write in the innermost scope. Likewise, global variables read and write 811 to the global namespace. The :keyword:`nonlocal` allows writing to outer 812 scopes. 813 814 new-style class 815 Old name for the flavor of classes now used for all class objects. In 816 earlier Python versions, only new-style classes could use Python's newer, 817 versatile features like :attr:`~object.__slots__`, descriptors, 818 properties, :meth:`__getattribute__`, class methods, and static methods. 819 820 object 821 Any data with state (attributes or value) and defined behavior 822 (methods). Also the ultimate base class of any :term:`new-style 823 class`. 824 825 package 826 A Python :term:`module` which can contain submodules or recursively, 827 subpackages. Technically, a package is a Python module with an 828 ``__path__`` attribute. 829 830 See also :term:`regular package` and :term:`namespace package`. 831 832 parameter 833 A named entity in a :term:`function` (or method) definition that 834 specifies an :term:`argument` (or in some cases, arguments) that the 835 function can accept. There are five kinds of parameter: 836 837 * :dfn:`positional-or-keyword`: specifies an argument that can be passed 838 either :term:`positionally <argument>` or as a :term:`keyword argument 839 <argument>`. This is the default kind of parameter, for example *foo* 840 and *bar* in the following:: 841 842 def func(foo, bar=None): ... 843 844 .. _positional-only_parameter: 845 846 * :dfn:`positional-only`: specifies an argument that can be supplied only 847 by position. Positional-only parameters can be defined by including a 848 ``/`` character in the parameter list of the function definition after 849 them, for example *posonly1* and *posonly2* in the following:: 850 851 def func(posonly1, posonly2, /, positional_or_keyword): ... 852 853 .. _keyword-only_parameter: 854 855 * :dfn:`keyword-only`: specifies an argument that can be supplied only 856 by keyword. Keyword-only parameters can be defined by including a 857 single var-positional parameter or bare ``*`` in the parameter list 858 of the function definition before them, for example *kw_only1* and 859 *kw_only2* in the following:: 860 861 def func(arg, *, kw_only1, kw_only2): ... 862 863 * :dfn:`var-positional`: specifies that an arbitrary sequence of 864 positional arguments can be provided (in addition to any positional 865 arguments already accepted by other parameters). Such a parameter can 866 be defined by prepending the parameter name with ``*``, for example 867 *args* in the following:: 868 869 def func(*args, **kwargs): ... 870 871 * :dfn:`var-keyword`: specifies that arbitrarily many keyword arguments 872 can be provided (in addition to any keyword arguments already accepted 873 by other parameters). Such a parameter can be defined by prepending 874 the parameter name with ``**``, for example *kwargs* in the example 875 above. 876 877 Parameters can specify both optional and required arguments, as well as 878 default values for some optional arguments. 879 880 See also the :term:`argument` glossary entry, the FAQ question on 881 :ref:`the difference between arguments and parameters 882 <faq-argument-vs-parameter>`, the :class:`inspect.Parameter` class, the 883 :ref:`function` section, and :pep:`362`. 884 885 path entry 886 A single location on the :term:`import path` which the :term:`path 887 based finder` consults to find modules for importing. 888 889 path entry finder 890 A :term:`finder` returned by a callable on :data:`sys.path_hooks` 891 (i.e. a :term:`path entry hook`) which knows how to locate modules given 892 a :term:`path entry`. 893 894 See :class:`importlib.abc.PathEntryFinder` for the methods that path entry 895 finders implement. 896 897 path entry hook 898 A callable on the :data:`sys.path_hook` list which returns a :term:`path 899 entry finder` if it knows how to find modules on a specific :term:`path 900 entry`. 901 902 path based finder 903 One of the default :term:`meta path finders <meta path finder>` which 904 searches an :term:`import path` for modules. 905 906 path-like object 907 An object representing a file system path. A path-like object is either 908 a :class:`str` or :class:`bytes` object representing a path, or an object 909 implementing the :class:`os.PathLike` protocol. An object that supports 910 the :class:`os.PathLike` protocol can be converted to a :class:`str` or 911 :class:`bytes` file system path by calling the :func:`os.fspath` function; 912 :func:`os.fsdecode` and :func:`os.fsencode` can be used to guarantee a 913 :class:`str` or :class:`bytes` result instead, respectively. Introduced 914 by :pep:`519`. 915 916 PEP 917 Python Enhancement Proposal. A PEP is a design document 918 providing information to the Python community, or describing a new 919 feature for Python or its processes or environment. PEPs should 920 provide a concise technical specification and a rationale for proposed 921 features. 922 923 PEPs are intended to be the primary mechanisms for proposing major new 924 features, for collecting community input on an issue, and for documenting 925 the design decisions that have gone into Python. The PEP author is 926 responsible for building consensus within the community and documenting 927 dissenting opinions. 928 929 See :pep:`1`. 930 931 portion 932 A set of files in a single directory (possibly stored in a zip file) 933 that contribute to a namespace package, as defined in :pep:`420`. 934 935 positional argument 936 See :term:`argument`. 937 938 provisional API 939 A provisional API is one which has been deliberately excluded from 940 the standard library's backwards compatibility guarantees. While major 941 changes to such interfaces are not expected, as long as they are marked 942 provisional, backwards incompatible changes (up to and including removal 943 of the interface) may occur if deemed necessary by core developers. Such 944 changes will not be made gratuitously -- they will occur only if serious 945 fundamental flaws are uncovered that were missed prior to the inclusion 946 of the API. 947 948 Even for provisional APIs, backwards incompatible changes are seen as 949 a "solution of last resort" - every attempt will still be made to find 950 a backwards compatible resolution to any identified problems. 951 952 This process allows the standard library to continue to evolve over 953 time, without locking in problematic design errors for extended periods 954 of time. See :pep:`411` for more details. 955 956 provisional package 957 See :term:`provisional API`. 958 959 Python 3000 960 Nickname for the Python 3.x release line (coined long ago when the 961 release of version 3 was something in the distant future.) This is also 962 abbreviated "Py3k". 963 964 Pythonic 965 An idea or piece of code which closely follows the most common idioms 966 of the Python language, rather than implementing code using concepts 967 common to other languages. For example, a common idiom in Python is 968 to loop over all elements of an iterable using a :keyword:`for` 969 statement. Many other languages don't have this type of construct, so 970 people unfamiliar with Python sometimes use a numerical counter instead:: 971 972 for i in range(len(food)): 973 print(food[i]) 974 975 As opposed to the cleaner, Pythonic method:: 976 977 for piece in food: 978 print(piece) 979 980 qualified name 981 A dotted name showing the "path" from a module's global scope to a 982 class, function or method defined in that module, as defined in 983 :pep:`3155`. For top-level functions and classes, the qualified name 984 is the same as the object's name:: 985 986 >>> class C: 987 ... class D: 988 ... def meth(self): 989 ... pass 990 ... 991 >>> C.__qualname__ 992 'C' 993 >>> C.D.__qualname__ 994 'C.D' 995 >>> C.D.meth.__qualname__ 996 'C.D.meth' 997 998 When used to refer to modules, the *fully qualified name* means the 999 entire dotted path to the module, including any parent packages, 1000 e.g. ``email.mime.text``:: 1001 1002 >>> import email.mime.text 1003 >>> email.mime.text.__name__ 1004 'email.mime.text' 1005 1006 reference count 1007 The number of references to an object. When the reference count of an 1008 object drops to zero, it is deallocated. Reference counting is 1009 generally not visible to Python code, but it is a key element of the 1010 :term:`CPython` implementation. The :mod:`sys` module defines a 1011 :func:`~sys.getrefcount` function that programmers can call to return the 1012 reference count for a particular object. 1013 1014 regular package 1015 A traditional :term:`package`, such as a directory containing an 1016 ``__init__.py`` file. 1017 1018 See also :term:`namespace package`. 1019 1020 __slots__ 1021 A declaration inside a class that saves memory by pre-declaring space for 1022 instance attributes and eliminating instance dictionaries. Though 1023 popular, the technique is somewhat tricky to get right and is best 1024 reserved for rare cases where there are large numbers of instances in a 1025 memory-critical application. 1026 1027 sequence 1028 An :term:`iterable` which supports efficient element access using integer 1029 indices via the :meth:`__getitem__` special method and defines a 1030 :meth:`__len__` method that returns the length of the sequence. 1031 Some built-in sequence types are :class:`list`, :class:`str`, 1032 :class:`tuple`, and :class:`bytes`. Note that :class:`dict` also 1033 supports :meth:`__getitem__` and :meth:`__len__`, but is considered a 1034 mapping rather than a sequence because the lookups use arbitrary 1035 :term:`immutable` keys rather than integers. 1036 1037 The :class:`collections.abc.Sequence` abstract base class 1038 defines a much richer interface that goes beyond just 1039 :meth:`__getitem__` and :meth:`__len__`, adding :meth:`count`, 1040 :meth:`index`, :meth:`__contains__`, and 1041 :meth:`__reversed__`. Types that implement this expanded 1042 interface can be registered explicitly using 1043 :func:`~abc.ABCMeta.register`. 1044 1045 set comprehension 1046 A compact way to process all or part of the elements in an iterable and 1047 return a set with the results. ``results = {c for c in 'abracadabra' if 1048 c not in 'abc'}`` generates the set of strings ``{'r', 'd'}``. See 1049 :ref:`comprehensions`. 1050 1051 single dispatch 1052 A form of :term:`generic function` dispatch where the implementation is 1053 chosen based on the type of a single argument. 1054 1055 slice 1056 An object usually containing a portion of a :term:`sequence`. A slice is 1057 created using the subscript notation, ``[]`` with colons between numbers 1058 when several are given, such as in ``variable_name[1:3:5]``. The bracket 1059 (subscript) notation uses :class:`slice` objects internally. 1060 1061 special method 1062 .. index:: pair: special; method 1063 1064 A method that is called implicitly by Python to execute a certain 1065 operation on a type, such as addition. Such methods have names starting 1066 and ending with double underscores. Special methods are documented in 1067 :ref:`specialnames`. 1068 1069 statement 1070 A statement is part of a suite (a "block" of code). A statement is either 1071 an :term:`expression` or one of several constructs with a keyword, such 1072 as :keyword:`if`, :keyword:`while` or :keyword:`for`. 1073 1074 text encoding 1075 A codec which encodes Unicode strings to bytes. 1076 1077 text file 1078 A :term:`file object` able to read and write :class:`str` objects. 1079 Often, a text file actually accesses a byte-oriented datastream 1080 and handles the :term:`text encoding` automatically. 1081 Examples of text files are files opened in text mode (``'r'`` or ``'w'``), 1082 :data:`sys.stdin`, :data:`sys.stdout`, and instances of 1083 :class:`io.StringIO`. 1084 1085 See also :term:`binary file` for a file object able to read and write 1086 :term:`bytes-like objects <bytes-like object>`. 1087 1088 triple-quoted string 1089 A string which is bound by three instances of either a quotation mark 1090 (") or an apostrophe ('). While they don't provide any functionality 1091 not available with single-quoted strings, they are useful for a number 1092 of reasons. They allow you to include unescaped single and double 1093 quotes within a string and they can span multiple lines without the 1094 use of the continuation character, making them especially useful when 1095 writing docstrings. 1096 1097 type 1098 The type of a Python object determines what kind of object it is; every 1099 object has a type. An object's type is accessible as its 1100 :attr:`~instance.__class__` attribute or can be retrieved with 1101 ``type(obj)``. 1102 1103 type alias 1104 A synonym for a type, created by assigning the type to an identifier. 1105 1106 Type aliases are useful for simplifying :term:`type hints <type hint>`. 1107 For example:: 1108 1109 def remove_gray_shades( 1110 colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]: 1111 pass 1112 1113 could be made more readable like this:: 1114 1115 Color = tuple[int, int, int] 1116 1117 def remove_gray_shades(colors: list[Color]) -> list[Color]: 1118 pass 1119 1120 See :mod:`typing` and :pep:`484`, which describe this functionality. 1121 1122 type hint 1123 An :term:`annotation` that specifies the expected type for a variable, a class 1124 attribute, or a function parameter or return value. 1125 1126 Type hints are optional and are not enforced by Python but 1127 they are useful to static type analysis tools, and aid IDEs with code 1128 completion and refactoring. 1129 1130 Type hints of global variables, class attributes, and functions, 1131 but not local variables, can be accessed using 1132 :func:`typing.get_type_hints`. 1133 1134 See :mod:`typing` and :pep:`484`, which describe this functionality. 1135 1136 universal newlines 1137 A manner of interpreting text streams in which all of the following are 1138 recognized as ending a line: the Unix end-of-line convention ``'\n'``, 1139 the Windows convention ``'\r\n'``, and the old Macintosh convention 1140 ``'\r'``. See :pep:`278` and :pep:`3116`, as well as 1141 :func:`bytes.splitlines` for an additional use. 1142 1143 variable annotation 1144 An :term:`annotation` of a variable or a class attribute. 1145 1146 When annotating a variable or a class attribute, assignment is optional:: 1147 1148 class C: 1149 field: 'annotation' 1150 1151 Variable annotations are usually used for 1152 :term:`type hints <type hint>`: for example this variable is expected to take 1153 :class:`int` values:: 1154 1155 count: int = 0 1156 1157 Variable annotation syntax is explained in section :ref:`annassign`. 1158 1159 See :term:`function annotation`, :pep:`484` 1160 and :pep:`526`, which describe this functionality. 1161 1162 virtual environment 1163 A cooperatively isolated runtime environment that allows Python users 1164 and applications to install and upgrade Python distribution packages 1165 without interfering with the behaviour of other Python applications 1166 running on the same system. 1167 1168 See also :mod:`venv`. 1169 1170 virtual machine 1171 A computer defined entirely in software. Python's virtual machine 1172 executes the :term:`bytecode` emitted by the bytecode compiler. 1173 1174 Zen of Python 1175 Listing of Python design principles and philosophies that are helpful in 1176 understanding and using the language. The listing can be found by typing 1177 "``import this``" at the interactive prompt. 1178