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