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