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