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