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