blob: 36832a33d483aca6eece505ae7b37b6a64696326 [file] [log] [blame]
Guido van Rossumf10aa982007-08-17 18:30:38 +00001.. _glossary:
2
3********
4Glossary
5********
6
7.. if you add new entries, keep the alphabetical sorting!
8
9.. glossary::
10
11 ``>>>``
Benjamin Peterson5478b472008-09-17 22:25:09 +000012 The default Python prompt of the interactive shell. Often seen for code
13 examples which can be executed interactively in the interpreter.
Georg Brandl48310cd2009-01-03 21:18:54 +000014
Guido van Rossumf10aa982007-08-17 18:30:38 +000015 ``...``
Benjamin Peterson5478b472008-09-17 22:25:09 +000016 The default Python prompt of the interactive shell when entering code for
17 an indented code block or within a pair of matching left and right
18 delimiters (parentheses, square brackets or curly braces).
Christian Heimesd8654cf2007-12-02 15:22:16 +000019
Benjamin Petersond6313712008-07-31 16:23:04 +000020 2to3
21 A tool that tries to convert Python 2.x code to Python 3.x code by
Georg Brandl6faee4e2010-09-21 14:48:28 +000022 handling most of the incompatibilities which can be detected by parsing the
Benjamin Petersond6313712008-07-31 16:23:04 +000023 source and traversing the parse tree.
24
25 2to3 is available in the standard library as :mod:`lib2to3`; a standalone
26 entry point is provided as :file:`Tools/scripts/2to3`. See
27 :ref:`2to3-reference`.
28
Georg Brandl86b2fb92008-07-16 03:43:04 +000029 abstract base class
Éric Araujofa088db2011-06-04 18:42:38 +020030 Abstract base classes complement :term:`duck-typing` by
Georg Brandl22b34312009-07-26 14:54:51 +000031 providing a way to define interfaces when other techniques like
Éric Araujofa088db2011-06-04 18:42:38 +020032 :func:`hasattr` would be clumsy or subtly wrong (for example with
Éric Araujo04ac59a2011-08-19 09:07:46 +020033 :ref:`magic methods <special-lookup>`). ABCs introduce virtual
34 subclasses, which are classes that don't inherit from a class but are
35 still recognized by :func:`isinstance` and :func:`issubclass`; see the
36 :mod:`abc` module documentation. Python comes with many built-in ABCs for
Éric Araujo459b4522011-06-04 21:16:42 +020037 data structures (in the :mod:`collections.abc` module), numbers (in the
Éric Araujofa088db2011-06-04 18:42:38 +020038 :mod:`numbers` module), streams (in the :mod:`io` module), import finders
39 and loaders (in the :mod:`importlib.abc` module). You can create your own
40 ABCs with the :mod:`abc` module.
Benjamin Peterson41181742008-07-02 20:22:54 +000041
Christian Heimesd8654cf2007-12-02 15:22:16 +000042 argument
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -080043 A value passed to a :term:`function` (or :term:`method`) when calling the
Zachary Waree1391a02013-11-22 13:58:34 -060044 function. There are two kinds of argument:
Christian Heimesd8654cf2007-12-02 15:22:16 +000045
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -080046 * :dfn:`keyword argument`: an argument preceded by an identifier (e.g.
47 ``name=``) in a function call or passed as a value in a dictionary
48 preceded by ``**``. For example, ``3`` and ``5`` are both keyword
49 arguments in the following calls to :func:`complex`::
50
51 complex(real=3, imag=5)
52 complex(**{'real': 3, 'imag': 5})
53
54 * :dfn:`positional argument`: an argument that is not a keyword argument.
55 Positional arguments can appear at the beginning of an argument list
56 and/or be passed as elements of an :term:`iterable` preceded by ``*``.
57 For example, ``3`` and ``5`` are both positional arguments in the
58 following calls::
59
60 complex(3, 5)
61 complex(*(3, 5))
62
63 Arguments are assigned to the named local variables in a function body.
64 See the :ref:`calls` section for the rules governing this assignment.
65 Syntactically, any expression can be used to represent an argument; the
66 evaluated value is assigned to the local variable.
67
68 See also the :term:`parameter` glossary entry, the FAQ question on
69 :ref:`the difference between arguments and parameters
70 <faq-argument-vs-parameter>`, and :pep:`362`.
Benjamin Peterson5478b472008-09-17 22:25:09 +000071
72 attribute
73 A value associated with an object which is referenced by name using
74 dotted expressions. For example, if an object *o* has an attribute
75 *a* it would be referenced as *o.a*.
Georg Brandl48310cd2009-01-03 21:18:54 +000076
Guido van Rossumf10aa982007-08-17 18:30:38 +000077 BDFL
78 Benevolent Dictator For Life, a.k.a. `Guido van Rossum
Georg Brandle73778c2014-10-29 08:36:35 +010079 <https://www.python.org/~guido/>`_, Python's creator.
Georg Brandl48310cd2009-01-03 21:18:54 +000080
Antoine Pitroudd799d22013-12-05 23:46:32 +010081 binary file
82 A :term:`file object` able to read and write
83 :term:`bytes-like objects <bytes-like object>`.
84
85 .. seealso::
86 A :term:`text file` reads and writes :class:`str` objects.
87
Ezio Melottiaa54e2f2013-04-30 23:33:31 +030088 bytes-like object
Antoine Pitrou5de183a2013-05-04 20:18:34 +020089 An object that supports the :ref:`bufferobjects`, like :class:`bytes`,
90 :class:`bytearray` or :class:`memoryview`. Bytes-like objects can
91 be used for various operations that expect binary data, such as
92 compression, saving to a binary file or sending over a socket.
93 Some operations need the binary data to be mutable, in which case
94 not all bytes-like objects can apply.
Ezio Melottiaa54e2f2013-04-30 23:33:31 +030095
Georg Brandl9afde1c2007-11-01 20:32:30 +000096 bytecode
97 Python source code is compiled into bytecode, the internal representation
Brett Cannon8315fd12010-07-02 22:03:00 +000098 of a Python program in the CPython interpreter. The bytecode is also
99 cached in ``.pyc`` and ``.pyo`` files so that executing the same file is
100 faster the second time (recompilation from source to bytecode can be
101 avoided). This "intermediate language" is said to run on a
102 :term:`virtual machine` that executes the machine code corresponding to
103 each bytecode. Do note that bytecodes are not expected to work between
104 different Python virtual machines, nor to be stable between Python
105 releases.
Benjamin Peterson5478b472008-09-17 22:25:09 +0000106
Georg Brandl2cb72d32010-07-03 10:26:54 +0000107 A list of bytecode instructions can be found in the documentation for
108 :ref:`the dis module <bytecodes>`.
109
Benjamin Peterson5478b472008-09-17 22:25:09 +0000110 class
111 A template for creating user-defined objects. Class definitions
112 normally contain method definitions which operate on instances of the
113 class.
Georg Brandl48310cd2009-01-03 21:18:54 +0000114
Benjamin Peterson5478b472008-09-17 22:25:09 +0000115 coercion
116 The implicit conversion of an instance of one type to another during an
117 operation which involves two arguments of the same type. For example,
118 ``int(3.15)`` converts the floating point number to the integer ``3``, but
119 in ``3+4.5``, each argument is of a different type (one int, one float),
120 and both must be converted to the same type before they can be added or it
Benjamin Peterson2d718222008-11-21 00:25:02 +0000121 will raise a ``TypeError``. Without coercion, all arguments of even
Benjamin Peterson5478b472008-09-17 22:25:09 +0000122 compatible types would have to be normalized to the same value by the
123 programmer, e.g., ``float(3)+4.5`` rather than just ``3+4.5``.
Georg Brandl48310cd2009-01-03 21:18:54 +0000124
Guido van Rossumf10aa982007-08-17 18:30:38 +0000125 complex number
126 An extension of the familiar real number system in which all numbers are
127 expressed as a sum of a real part and an imaginary part. Imaginary
128 numbers are real multiples of the imaginary unit (the square root of
129 ``-1``), often written ``i`` in mathematics or ``j`` in
Georg Brandl22b34312009-07-26 14:54:51 +0000130 engineering. Python has built-in support for complex numbers, which are
Guido van Rossumf10aa982007-08-17 18:30:38 +0000131 written with this latter notation; the imaginary part is written with a
132 ``j`` suffix, e.g., ``3+1j``. To get access to complex equivalents of the
133 :mod:`math` module, use :mod:`cmath`. Use of complex numbers is a fairly
134 advanced mathematical feature. If you're not aware of a need for them,
135 it's almost certain you can safely ignore them.
Georg Brandl48310cd2009-01-03 21:18:54 +0000136
Christian Heimes895627f2007-12-08 17:28:33 +0000137 context manager
Benjamin Peterson5478b472008-09-17 22:25:09 +0000138 An object which controls the environment seen in a :keyword:`with`
Christian Heimes895627f2007-12-08 17:28:33 +0000139 statement by defining :meth:`__enter__` and :meth:`__exit__` methods.
140 See :pep:`343`.
141
Benjamin Peterson5478b472008-09-17 22:25:09 +0000142 CPython
Antoine Pitrou00342812011-01-06 16:31:28 +0000143 The canonical implementation of the Python programming language, as
Georg Brandle73778c2014-10-29 08:36:35 +0100144 distributed on `python.org <https://www.python.org>`_. The term "CPython"
Antoine Pitrou00342812011-01-06 16:31:28 +0000145 is used when necessary to distinguish this implementation from others
146 such as Jython or IronPython.
Benjamin Peterson5478b472008-09-17 22:25:09 +0000147
Christian Heimesd8654cf2007-12-02 15:22:16 +0000148 decorator
149 A function returning another function, usually applied as a function
150 transformation using the ``@wrapper`` syntax. Common examples for
151 decorators are :func:`classmethod` and :func:`staticmethod`.
152
153 The decorator syntax is merely syntactic sugar, the following two
154 function definitions are semantically equivalent::
155
156 def f(...):
157 ...
158 f = staticmethod(f)
159
160 @staticmethod
161 def f(...):
162 ...
163
Georg Brandlaf265f42008-12-07 15:06:20 +0000164 The same concept exists for classes, but is less commonly used there. See
165 the documentation for :ref:`function definitions <function>` and
166 :ref:`class definitions <class>` for more about decorators.
Georg Brandla09ca382007-12-02 18:20:12 +0000167
Guido van Rossumf10aa982007-08-17 18:30:38 +0000168 descriptor
Benjamin Peterson5478b472008-09-17 22:25:09 +0000169 Any object which defines the methods :meth:`__get__`, :meth:`__set__`, or
Georg Brandl85eb8c12007-08-31 16:33:38 +0000170 :meth:`__delete__`. When a class attribute is a descriptor, its special
Georg Brandl9afde1c2007-11-01 20:32:30 +0000171 binding behavior is triggered upon attribute lookup. Normally, using
172 *a.b* to get, set or delete an attribute looks up the object named *b* in
173 the class dictionary for *a*, but if *b* is a descriptor, the respective
174 descriptor method gets called. Understanding descriptors is a key to a
175 deep understanding of Python because they are the basis for many features
176 including functions, methods, properties, class methods, static methods,
177 and reference to super classes.
178
179 For more information about descriptors' methods, see :ref:`descriptors`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000180
Guido van Rossumf10aa982007-08-17 18:30:38 +0000181 dictionary
Senthil Kumaran6080db72012-03-12 10:05:34 -0700182 An associative array, where arbitrary keys are mapped to values. The
183 keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
184 Called a hash in Perl.
Georg Brandl3dbca812008-07-23 16:10:53 +0000185
Martin Panter85b8f452015-10-07 09:56:46 +0000186 dictionary view
187 The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and
188 :meth:`dict.items` are called dictionary views. They provide a dynamic
189 view on the dictionary’s entries, which means that when the dictionary
190 changes, the view reflects these changes. To force the
191 dictionary view to become a full list use ``list(dictview)``. See
192 :ref:`dict-views`.
193
Georg Brandl3dbca812008-07-23 16:10:53 +0000194 docstring
Benjamin Peterson5478b472008-09-17 22:25:09 +0000195 A string literal which appears as the first expression in a class,
196 function or module. While ignored when the suite is executed, it is
197 recognized by the compiler and put into the :attr:`__doc__` attribute
198 of the enclosing class, function or module. Since it is available via
199 introspection, it is the canonical place for documentation of the
Georg Brandl3dbca812008-07-23 16:10:53 +0000200 object.
Georg Brandl48310cd2009-01-03 21:18:54 +0000201
202 duck-typing
Georg Brandl73b1c7b2010-07-10 10:39:57 +0000203 A programming style which does not look at an object's type to determine
204 if it has the right interface; instead, the method or attribute is simply
205 called or used ("If it looks like a duck and quacks like a duck, it
Guido van Rossumf10aa982007-08-17 18:30:38 +0000206 must be a duck.") By emphasizing interfaces rather than specific types,
207 well-designed code improves its flexibility by allowing polymorphic
208 substitution. Duck-typing avoids tests using :func:`type` or
Georg Brandl8a1c2542010-07-11 08:36:20 +0000209 :func:`isinstance`. (Note, however, that duck-typing can be complemented
Éric Araujo0519b092011-08-19 00:39:19 +0200210 with :term:`abstract base classes <abstract base class>`.) Instead, it
211 typically employs :func:`hasattr` tests or :term:`EAFP` programming.
Georg Brandl48310cd2009-01-03 21:18:54 +0000212
Guido van Rossumf10aa982007-08-17 18:30:38 +0000213 EAFP
214 Easier to ask for forgiveness than permission. This common Python coding
215 style assumes the existence of valid keys or attributes and catches
216 exceptions if the assumption proves false. This clean and fast style is
217 characterized by the presence of many :keyword:`try` and :keyword:`except`
Georg Brandl48310cd2009-01-03 21:18:54 +0000218 statements. The technique contrasts with the :term:`LBYL` style
Benjamin Peterson5478b472008-09-17 22:25:09 +0000219 common to many other languages such as C.
Guido van Rossumf10aa982007-08-17 18:30:38 +0000220
Christian Heimesd8654cf2007-12-02 15:22:16 +0000221 expression
222 A piece of syntax which can be evaluated to some value. In other words,
Benjamin Peterson5478b472008-09-17 22:25:09 +0000223 an expression is an accumulation of expression elements like literals,
224 names, attribute access, operators or function calls which all return a
225 value. In contrast to many other languages, not all language constructs
226 are expressions. There are also :term:`statement`\s which cannot be used
227 as expressions, such as :keyword:`if`. Assignments are also statements,
228 not expressions.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000229
Guido van Rossumf10aa982007-08-17 18:30:38 +0000230 extension module
Georg Brandl9d9848e2010-12-28 11:48:53 +0000231 A module written in C or C++, using Python's C API to interact with the
232 core and with user code.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000233
Antoine Pitrou0b65b0f2010-09-15 09:58:26 +0000234 file object
235 An object exposing a file-oriented API (with methods such as
Georg Brandl9d9848e2010-12-28 11:48:53 +0000236 :meth:`read()` or :meth:`write()`) to an underlying resource. Depending
237 on the way it was created, a file object can mediate access to a real
Eli Benderskydbaedb82012-03-30 11:02:05 +0300238 on-disk file or to another type of storage or communication device
Georg Brandl9d9848e2010-12-28 11:48:53 +0000239 (for example standard input/output, in-memory buffers, sockets, pipes,
240 etc.). File objects are also called :dfn:`file-like objects` or
241 :dfn:`streams`.
Antoine Pitrou0b65b0f2010-09-15 09:58:26 +0000242
Antoine Pitroudd799d22013-12-05 23:46:32 +0100243 There are actually three categories of file objects: raw
244 :term:`binary files <binary file>`, buffered
245 :term:`binary files <binary file>` and :term:`text files <text file>`.
246 Their interfaces are defined in the :mod:`io` module. The canonical
247 way to create a file object is by using the :func:`open` function.
Antoine Pitrou0b65b0f2010-09-15 09:58:26 +0000248
249 file-like object
250 A synonym for :term:`file object`.
251
Brett Cannon51d4aab2009-01-25 04:21:39 +0000252 finder
253 An object that tries to find the :term:`loader` for a module. It must
Barry Warsawd7d21942012-07-29 16:36:17 -0400254 implement either a method named :meth:`find_loader` or a method named
255 :meth:`find_module`. See :pep:`302` and :pep:`420` for details and
256 :class:`importlib.abc.Finder` for an :term:`abstract base class`.
Brett Cannon51d4aab2009-01-25 04:21:39 +0000257
Benjamin Peterson2d718222008-11-21 00:25:02 +0000258 floor division
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000259 Mathematical division that rounds down to nearest integer. The floor
260 division operator is ``//``. For example, the expression ``11 // 4``
261 evaluates to ``2`` in contrast to the ``2.75`` returned by float true
262 division. Note that ``(-11) // 4`` is ``-3`` because that is ``-2.75``
263 rounded *downward*. See :pep:`238`.
Benjamin Peterson2d718222008-11-21 00:25:02 +0000264
Christian Heimesd8654cf2007-12-02 15:22:16 +0000265 function
266 A series of statements which returns some value to a caller. It can also
Chris Jerdonekb4309942012-12-25 14:54:44 -0800267 be passed zero or more :term:`arguments <argument>` which may be used in
268 the execution of the body. See also :term:`parameter`, :term:`method`,
269 and the :ref:`function` section.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000270
R David Murray25cd0912013-05-06 12:58:16 -0400271 function annotation
272 An arbitrary metadata value associated with a function parameter or return
273 value. Its syntax is explained in section :ref:`function`. Annotations
274 may be accessed via the :attr:`__annotations__` special attribute of a
275 function object.
276
277 Python itself does not assign any particular meaning to function
278 annotations. They are intended to be interpreted by third-party libraries
279 or tools. See :pep:`3107`, which describes some of their potential uses.
280
Guido van Rossumf10aa982007-08-17 18:30:38 +0000281 __future__
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000282 A pseudo-module which programmers can use to enable new language features
Benjamin Peterson2d718222008-11-21 00:25:02 +0000283 which are not compatible with the current interpreter.
284
285 By importing the :mod:`__future__` module and evaluating its variables,
286 you can see when a new feature was first added to the language and when it
287 becomes the default::
Georg Brandl48310cd2009-01-03 21:18:54 +0000288
Guido van Rossumf10aa982007-08-17 18:30:38 +0000289 >>> import __future__
290 >>> __future__.division
291 _Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)
292
293 garbage collection
294 The process of freeing memory when it is not used anymore. Python
295 performs garbage collection via reference counting and a cyclic garbage
296 collector that is able to detect and break reference cycles.
Georg Brandl48310cd2009-01-03 21:18:54 +0000297
Benjamin Peterson08bf91c2010-04-11 16:12:57 +0000298 .. index:: single: generator
299
Guido van Rossumf10aa982007-08-17 18:30:38 +0000300 generator
Benjamin Peterson5478b472008-09-17 22:25:09 +0000301 A function which returns an iterator. It looks like a normal function
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000302 except that it contains :keyword:`yield` statements for producing a series
Georg Brandlcaa12da2015-01-15 08:16:01 +0100303 of values usable in a for-loop or that can be retrieved one at a time with
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000304 the :func:`next` function. Each :keyword:`yield` temporarily suspends
305 processing, remembering the location execution state (including local
306 variables and pending try-statements). When the generator resumes, it
307 picks-up where it left-off (in contrast to functions which start fresh on
Éric Araujoe0854f92011-05-27 04:36:52 +0200308 every invocation).
Georg Brandl48310cd2009-01-03 21:18:54 +0000309
Guido van Rossumf10aa982007-08-17 18:30:38 +0000310 .. index:: single: generator expression
Georg Brandl48310cd2009-01-03 21:18:54 +0000311
Guido van Rossumf10aa982007-08-17 18:30:38 +0000312 generator expression
Benjamin Peterson08bf91c2010-04-11 16:12:57 +0000313 An expression that returns an iterator. It looks like a normal expression
Guido van Rossumf10aa982007-08-17 18:30:38 +0000314 followed by a :keyword:`for` expression defining a loop variable, range,
315 and an optional :keyword:`if` expression. The combined expression
316 generates values for an enclosing function::
Georg Brandl48310cd2009-01-03 21:18:54 +0000317
Guido van Rossumf10aa982007-08-17 18:30:38 +0000318 >>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81
319 285
Georg Brandl48310cd2009-01-03 21:18:54 +0000320
Łukasz Langafdcf2b72013-06-07 22:54:03 +0200321 generic function
322 A function composed of multiple functions implementing the same operation
323 for different types. Which implementation should be used during a call is
324 determined by the dispatch algorithm.
325
326 See also the :term:`single dispatch` glossary entry, the
327 :func:`functools.singledispatch` decorator, and :pep:`443`.
328
329
Guido van Rossumf10aa982007-08-17 18:30:38 +0000330 GIL
331 See :term:`global interpreter lock`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000332
Guido van Rossumf10aa982007-08-17 18:30:38 +0000333 global interpreter lock
Antoine Pitrou00342812011-01-06 16:31:28 +0000334 The mechanism used by the :term:`CPython` interpreter to assure that
335 only one thread executes Python :term:`bytecode` at a time.
336 This simplifies the CPython implementation by making the object model
337 (including critical built-in types such as :class:`dict`) implicitly
338 safe against concurrent access. Locking the entire interpreter
339 makes it easier for the interpreter to be multi-threaded, at the
340 expense of much of the parallelism afforded by multi-processor
341 machines.
342
343 However, some extension modules, either standard or third-party,
344 are designed so as to release the GIL when doing computationally-intensive
345 tasks such as compression or hashing. Also, the GIL is always released
346 when doing I/O.
347
348 Past efforts to create a "free-threaded" interpreter (one which locks
349 shared data at a much finer granularity) have not been successful
350 because performance suffered in the common single-processor case. It
351 is believed that overcoming this performance issue would make the
352 implementation much more complicated and therefore costlier to maintain.
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000353
354 hashable
Benjamin Peterson5478b472008-09-17 22:25:09 +0000355 An object is *hashable* if it has a hash value which never changes during
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000356 its lifetime (it needs a :meth:`__hash__` method), and can be compared to
Georg Brandl05f5ab72008-09-24 09:11:47 +0000357 other objects (it needs an :meth:`__eq__` method). Hashable objects which
358 compare equal must have the same hash value.
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000359
360 Hashability makes an object usable as a dictionary key and a set member,
361 because these data structures use the hash value internally.
362
Benjamin Peterson5478b472008-09-17 22:25:09 +0000363 All of Python's immutable built-in objects are hashable, while no mutable
364 containers (such as lists or dictionaries) are. Objects which are
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000365 instances of user-defined classes are hashable by default; they all
Georg Brandl4dd27a32014-10-06 16:45:23 +0200366 compare unequal (except with themselves), and their hash value is derived
367 from their :func:`id`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000368
Guido van Rossumf10aa982007-08-17 18:30:38 +0000369 IDLE
370 An Integrated Development Environment for Python. IDLE is a basic editor
Benjamin Peterson5478b472008-09-17 22:25:09 +0000371 and interpreter environment which ships with the standard distribution of
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000372 Python.
Georg Brandl48310cd2009-01-03 21:18:54 +0000373
Guido van Rossumf10aa982007-08-17 18:30:38 +0000374 immutable
Benjamin Peterson5478b472008-09-17 22:25:09 +0000375 An object with a fixed value. Immutable objects include numbers, strings and
376 tuples. Such an object cannot be altered. A new object has to
Guido van Rossumf10aa982007-08-17 18:30:38 +0000377 be created if a different value has to be stored. They play an important
378 role in places where a constant hash value is needed, for example as a key
379 in a dictionary.
Benjamin Peterson2d718222008-11-21 00:25:02 +0000380
Barry Warsawdadebab2012-07-31 16:03:09 -0400381 import path
382 A list of locations (or :term:`path entries <path entry>`) that are
Nick Coghlan1685db02012-08-20 13:49:08 +1000383 searched by the :term:`path based finder` for modules to import. During
Barry Warsawdadebab2012-07-31 16:03:09 -0400384 import, this list of locations usually comes from :data:`sys.path`, but
385 for subpackages it may also come from the parent package's ``__path__``
386 attribute.
387
Barry Warsawd7d21942012-07-29 16:36:17 -0400388 importing
389 The process by which Python code in one module is made available to
390 Python code in another module.
391
Brett Cannon51d4aab2009-01-25 04:21:39 +0000392 importer
393 An object that both finds and loads a module; both a
394 :term:`finder` and :term:`loader` object.
395
Guido van Rossumf10aa982007-08-17 18:30:38 +0000396 interactive
Benjamin Peterson5478b472008-09-17 22:25:09 +0000397 Python has an interactive interpreter which means you can enter
398 statements and expressions at the interpreter prompt, immediately
399 execute them and see their results. Just launch ``python`` with no
400 arguments (possibly by selecting it from your computer's main
401 menu). It is a very powerful way to test out new ideas or inspect
402 modules and packages (remember ``help(x)``).
Georg Brandl48310cd2009-01-03 21:18:54 +0000403
Guido van Rossumf10aa982007-08-17 18:30:38 +0000404 interpreted
Benjamin Peterson5478b472008-09-17 22:25:09 +0000405 Python is an interpreted language, as opposed to a compiled one,
406 though the distinction can be blurry because of the presence of the
407 bytecode compiler. This means that source files can be run directly
408 without explicitly creating an executable which is then run.
409 Interpreted languages typically have a shorter development/debug cycle
410 than compiled ones, though their programs generally also run more
411 slowly. See also :term:`interactive`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000412
Guido van Rossumf10aa982007-08-17 18:30:38 +0000413 iterable
Ezio Melottid581fff2013-01-02 22:29:09 +0200414 An object capable of returning its members one at a time. Examples of
415 iterables include all sequence types (such as :class:`list`, :class:`str`,
416 and :class:`tuple`) and some non-sequence types like :class:`dict`,
417 :term:`file objects <file object>`, and objects of any classes you define
418 with an :meth:`__iter__` or :meth:`__getitem__` method. Iterables can be
419 used in a :keyword:`for` loop and in many other places where a sequence is
420 needed (:func:`zip`, :func:`map`, ...). When an iterable object is passed
421 as an argument to the built-in function :func:`iter`, it returns an
422 iterator for the object. This iterator is good for one pass over the set
423 of values. When using iterables, it is usually not necessary to call
424 :func:`iter` or deal with iterator objects yourself. The ``for``
Guido van Rossumf10aa982007-08-17 18:30:38 +0000425 statement does that automatically for you, creating a temporary unnamed
426 variable to hold the iterator for the duration of the loop. See also
427 :term:`iterator`, :term:`sequence`, and :term:`generator`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000428
Guido van Rossumf10aa982007-08-17 18:30:38 +0000429 iterator
430 An object representing a stream of data. Repeated calls to the iterator's
Ezio Melotti7fa82222012-10-12 13:42:08 +0300431 :meth:`~iterator.__next__` method (or passing it to the built-in function
Georg Brandlb30f3302011-01-06 09:23:56 +0000432 :func:`next`) return successive items in the stream. When no more data
433 are available a :exc:`StopIteration` exception is raised instead. At this
Benjamin Petersone7c78b22008-07-03 20:28:26 +0000434 point, the iterator object is exhausted and any further calls to its
Georg Brandlb30f3302011-01-06 09:23:56 +0000435 :meth:`__next__` method just raise :exc:`StopIteration` again. Iterators
436 are required to have an :meth:`__iter__` method that returns the iterator
Guido van Rossumf10aa982007-08-17 18:30:38 +0000437 object itself so every iterator is also iterable and may be used in most
438 places where other iterables are accepted. One notable exception is code
Benjamin Peterson5478b472008-09-17 22:25:09 +0000439 which attempts multiple iteration passes. A container object (such as a
Guido van Rossumf10aa982007-08-17 18:30:38 +0000440 :class:`list`) produces a fresh new iterator each time you pass it to the
441 :func:`iter` function or use it in a :keyword:`for` loop. Attempting this
442 with an iterator will just return the same exhausted iterator object used
443 in the previous iteration pass, making it appear like an empty container.
Georg Brandl48310cd2009-01-03 21:18:54 +0000444
Georg Brandl9afde1c2007-11-01 20:32:30 +0000445 More information can be found in :ref:`typeiter`.
446
Georg Brandlc275e152010-11-05 07:10:41 +0000447 key function
448 A key function or collation function is a callable that returns a value
449 used for sorting or ordering. For example, :func:`locale.strxfrm` is
450 used to produce a sort key that is aware of locale specific sort
451 conventions.
452
453 A number of tools in Python accept key functions to control how elements
454 are ordered or grouped. They include :func:`min`, :func:`max`,
455 :func:`sorted`, :meth:`list.sort`, :func:`heapq.nsmallest`,
456 :func:`heapq.nlargest`, and :func:`itertools.groupby`.
457
458 There are several ways to create a key function. For example. the
459 :meth:`str.lower` method can serve as a key function for case insensitive
460 sorts. Alternatively, an ad-hoc key function can be built from a
461 :keyword:`lambda` expression such as ``lambda r: (r[0], r[2])``. Also,
Sandro Tosi165a2c22012-04-01 01:50:00 +0200462 the :mod:`operator` module provides three key function constructors:
Georg Brandlc275e152010-11-05 07:10:41 +0000463 :func:`~operator.attrgetter`, :func:`~operator.itemgetter`, and
464 :func:`~operator.methodcaller`. See the :ref:`Sorting HOW TO
465 <sortinghowto>` for examples of how to create and use key functions.
466
Christian Heimesd8654cf2007-12-02 15:22:16 +0000467 keyword argument
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -0800468 See :term:`argument`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000469
470 lambda
471 An anonymous inline function consisting of a single :term:`expression`
472 which is evaluated when the function is called. The syntax to create
473 a lambda function is ``lambda [arguments]: expression``
474
Guido van Rossumf10aa982007-08-17 18:30:38 +0000475 LBYL
476 Look before you leap. This coding style explicitly tests for
477 pre-conditions before making calls or lookups. This style contrasts with
478 the :term:`EAFP` approach and is characterized by the presence of many
479 :keyword:`if` statements.
Benjamin Peterson5478b472008-09-17 22:25:09 +0000480
Raymond Hettinger09f44142010-12-17 20:19:50 +0000481 In a multi-threaded environment, the LBYL approach can risk introducing a
482 race condition between "the looking" and "the leaping". For example, the
483 code, ``if key in mapping: return mapping[key]`` can fail if another
484 thread removes *key* from *mapping* after the test, but before the lookup.
485 This issue can be solved with locks or by using the EAFP approach.
486
Benjamin Peterson5478b472008-09-17 22:25:09 +0000487 list
488 A built-in Python :term:`sequence`. Despite its name it is more akin
489 to an array in other languages than to a linked list since access to
490 elements are O(1).
Georg Brandl48310cd2009-01-03 21:18:54 +0000491
Guido van Rossumf10aa982007-08-17 18:30:38 +0000492 list comprehension
Benjamin Peterson5478b472008-09-17 22:25:09 +0000493 A compact way to process all or part of the elements in a sequence and
Georg Brandlede6c2a2010-01-05 10:22:04 +0000494 return a list with the results. ``result = ['{:#04x}'.format(x) for x in
Benjamin Peterson5478b472008-09-17 22:25:09 +0000495 range(256) if x % 2 == 0]`` generates a list of strings containing
496 even hex numbers (0x..) in the range from 0 to 255. The :keyword:`if`
497 clause is optional. If omitted, all elements in ``range(256)`` are
498 processed.
Georg Brandl48310cd2009-01-03 21:18:54 +0000499
Brett Cannon51d4aab2009-01-25 04:21:39 +0000500 loader
501 An object that loads a module. It must define a method named
502 :meth:`load_module`. A loader is typically returned by a
Brett Cannone43b0602009-03-21 03:11:16 +0000503 :term:`finder`. See :pep:`302` for details and
504 :class:`importlib.abc.Loader` for an :term:`abstract base class`.
Brett Cannon51d4aab2009-01-25 04:21:39 +0000505
Guido van Rossumf10aa982007-08-17 18:30:38 +0000506 mapping
Raymond Hettingere3ee66f2011-01-08 23:44:37 +0000507 A container object that supports arbitrary key lookups and implements the
Éric Araujob8edbdf2011-09-01 05:57:12 +0200508 methods specified in the :class:`~collections.abc.Mapping` or
509 :class:`~collections.abc.MutableMapping`
Éric Araujofa088db2011-06-04 18:42:38 +0200510 :ref:`abstract base classes <collections-abstract-base-classes>`. Examples
511 include :class:`dict`, :class:`collections.defaultdict`,
Raymond Hettingere3ee66f2011-01-08 23:44:37 +0000512 :class:`collections.OrderedDict` and :class:`collections.Counter`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000513
Barry Warsawd7d21942012-07-29 16:36:17 -0400514 meta path finder
515 A finder returned by a search of :data:`sys.meta_path`. Meta path
Barry Warsawdadebab2012-07-31 16:03:09 -0400516 finders are related to, but different from :term:`path entry finders
517 <path entry finder>`.
Barry Warsawd7d21942012-07-29 16:36:17 -0400518
Guido van Rossumf10aa982007-08-17 18:30:38 +0000519 metaclass
520 The class of a class. Class definitions create a class name, a class
521 dictionary, and a list of base classes. The metaclass is responsible for
522 taking those three arguments and creating the class. Most object oriented
523 programming languages provide a default implementation. What makes Python
524 special is that it is possible to create custom metaclasses. Most users
525 never need this tool, but when the need arises, metaclasses can provide
526 powerful, elegant solutions. They have been used for logging attribute
527 access, adding thread-safety, tracking object creation, implementing
528 singletons, and many other tasks.
Georg Brandl9afde1c2007-11-01 20:32:30 +0000529
530 More information can be found in :ref:`metaclasses`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000531
532 method
Benjamin Peterson5478b472008-09-17 22:25:09 +0000533 A function which is defined inside a class body. If called as an attribute
Christian Heimesd8654cf2007-12-02 15:22:16 +0000534 of an instance of that class, the method will get the instance object as
535 its first :term:`argument` (which is usually called ``self``).
536 See :term:`function` and :term:`nested scope`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000537
Michael Foord95fc51d2010-11-20 15:07:30 +0000538 method resolution order
539 Method Resolution Order is the order in which base classes are searched
540 for a member during lookup. See `The Python 2.3 Method Resolution Order
Georg Brandle73778c2014-10-29 08:36:35 +0100541 <https://www.python.org/download/releases/2.3/mro/>`_.
Michael Foord95fc51d2010-11-20 15:07:30 +0000542
Barry Warsawd7d21942012-07-29 16:36:17 -0400543 module
544 An object that serves as an organizational unit of Python code. Modules
Barry Warsawc1e721b2012-07-30 16:24:12 -0400545 have a namespace containing arbitrary Python objects. Modules are loaded
Barry Warsawd7d21942012-07-29 16:36:17 -0400546 into Python by the process of :term:`importing`.
547
Georg Brandlbcce1252013-10-08 08:06:18 +0200548 See also :term:`package`.
549
Eric Snowca2d8542013-12-16 23:06:52 -0700550 module spec
551 A namespace containing the import-related information used to load a
552 module.
553
Michael Foord95fc51d2010-11-20 15:07:30 +0000554 MRO
555 See :term:`method resolution order`.
556
Guido van Rossumf10aa982007-08-17 18:30:38 +0000557 mutable
558 Mutable objects can change their value but keep their :func:`id`. See
559 also :term:`immutable`.
Christian Heimes25bb7832008-01-11 16:17:00 +0000560
561 named tuple
Raymond Hettingerd04fa312009-02-04 19:45:13 +0000562 Any tuple-like class whose indexable elements are also accessible using
Christian Heimesd32ed6f2008-01-14 18:49:24 +0000563 named attributes (for example, :func:`time.localtime` returns a
564 tuple-like object where the *year* is accessible either with an
565 index such as ``t[0]`` or with a named attribute like ``t.tm_year``).
566
567 A named tuple can be a built-in type such as :class:`time.struct_time`,
568 or it can be created with a regular class definition. A full featured
569 named tuple can also be created with the factory function
570 :func:`collections.namedtuple`. The latter approach automatically
571 provides extra features such as a self-documenting representation like
572 ``Employee(name='jones', title='programmer')``.
Georg Brandl48310cd2009-01-03 21:18:54 +0000573
Guido van Rossumf10aa982007-08-17 18:30:38 +0000574 namespace
575 The place where a variable is stored. Namespaces are implemented as
Georg Brandl22b34312009-07-26 14:54:51 +0000576 dictionaries. There are the local, global and built-in namespaces as well
Guido van Rossumf10aa982007-08-17 18:30:38 +0000577 as nested namespaces in objects (in methods). Namespaces support
578 modularity by preventing naming conflicts. For instance, the functions
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +0300579 :func:`builtins.open <.open>` and :func:`os.open` are distinguished by
580 their namespaces. Namespaces also aid readability and maintainability by
581 making it clear which module implements a function. For instance, writing
Éric Araujo7af8ebb2011-09-01 03:20:13 +0200582 :func:`random.seed` or :func:`itertools.islice` makes it clear that those
Guido van Rossumf10aa982007-08-17 18:30:38 +0000583 functions are implemented by the :mod:`random` and :mod:`itertools`
Benjamin Peterson5478b472008-09-17 22:25:09 +0000584 modules, respectively.
Georg Brandl48310cd2009-01-03 21:18:54 +0000585
Barry Warsawd7d21942012-07-29 16:36:17 -0400586 namespace package
587 A :pep:`420` :term:`package` which serves only as a container for
588 subpackages. Namespace packages may have no physical representation,
589 and specifically are not like a :term:`regular package` because they
590 have no ``__init__.py`` file.
591
Georg Brandlbcce1252013-10-08 08:06:18 +0200592 See also :term:`module`.
593
Guido van Rossumf10aa982007-08-17 18:30:38 +0000594 nested scope
595 The ability to refer to a variable in an enclosing definition. For
596 instance, a function defined inside another function can refer to
Benjamin Peterson927ccd22010-06-29 18:36:39 +0000597 variables in the outer function. Note that nested scopes by default work
598 only for reference and not for assignment. Local variables both read and
599 write in the innermost scope. Likewise, global variables read and write
600 to the global namespace. The :keyword:`nonlocal` allows writing to outer
601 scopes.
Georg Brandl48310cd2009-01-03 21:18:54 +0000602
Guido van Rossumf10aa982007-08-17 18:30:38 +0000603 new-style class
Georg Brandl85eb8c12007-08-31 16:33:38 +0000604 Old name for the flavor of classes now used for all class objects. In
605 earlier Python versions, only new-style classes could use Python's newer,
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +0300606 versatile features like :attr:`~object.__slots__`, descriptors,
607 properties, :meth:`__getattribute__`, class methods, and static methods.
Georg Brandl9afde1c2007-11-01 20:32:30 +0000608
Benjamin Peterson5478b472008-09-17 22:25:09 +0000609 object
610 Any data with state (attributes or value) and defined behavior
611 (methods). Also the ultimate base class of any :term:`new-style
612 class`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000613
Barry Warsawd7d21942012-07-29 16:36:17 -0400614 package
Georg Brandlbcce1252013-10-08 08:06:18 +0200615 A Python :term:`module` which can contain submodules or recursively,
Barry Warsawd7d21942012-07-29 16:36:17 -0400616 subpackages. Technically, a package is a Python module with an
617 ``__path__`` attribute.
618
Georg Brandlbcce1252013-10-08 08:06:18 +0200619 See also :term:`regular package` and :term:`namespace package`.
620
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -0800621 parameter
622 A named entity in a :term:`function` (or method) definition that
623 specifies an :term:`argument` (or in some cases, arguments) that the
Zachary Waree1391a02013-11-22 13:58:34 -0600624 function can accept. There are five kinds of parameter:
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -0800625
626 * :dfn:`positional-or-keyword`: specifies an argument that can be passed
627 either :term:`positionally <argument>` or as a :term:`keyword argument
628 <argument>`. This is the default kind of parameter, for example *foo*
629 and *bar* in the following::
630
631 def func(foo, bar=None): ...
632
633 * :dfn:`positional-only`: specifies an argument that can be supplied only
634 by position. Python has no syntax for defining positional-only
635 parameters. However, some built-in functions have positional-only
636 parameters (e.g. :func:`abs`).
637
Zachary Waree1391a02013-11-22 13:58:34 -0600638 .. _keyword-only_parameter:
639
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -0800640 * :dfn:`keyword-only`: specifies an argument that can be supplied only
641 by keyword. Keyword-only parameters can be defined by including a
642 single var-positional parameter or bare ``*`` in the parameter list
643 of the function definition before them, for example *kw_only1* and
644 *kw_only2* in the following::
645
646 def func(arg, *, kw_only1, kw_only2): ...
647
648 * :dfn:`var-positional`: specifies that an arbitrary sequence of
649 positional arguments can be provided (in addition to any positional
650 arguments already accepted by other parameters). Such a parameter can
651 be defined by prepending the parameter name with ``*``, for example
652 *args* in the following::
653
654 def func(*args, **kwargs): ...
655
656 * :dfn:`var-keyword`: specifies that arbitrarily many keyword arguments
657 can be provided (in addition to any keyword arguments already accepted
658 by other parameters). Such a parameter can be defined by prepending
659 the parameter name with ``**``, for example *kwargs* in the example
660 above.
661
662 Parameters can specify both optional and required arguments, as well as
663 default values for some optional arguments.
664
665 See also the :term:`argument` glossary entry, the FAQ question on
666 :ref:`the difference between arguments and parameters
667 <faq-argument-vs-parameter>`, the :class:`inspect.Parameter` class, the
668 :ref:`function` section, and :pep:`362`.
669
Barry Warsawdadebab2012-07-31 16:03:09 -0400670 path entry
671 A single location on the :term:`import path` which the :term:`path
Nick Coghlan1685db02012-08-20 13:49:08 +1000672 based finder` consults to find modules for importing.
Barry Warsawdadebab2012-07-31 16:03:09 -0400673
674 path entry finder
675 A :term:`finder` returned by a callable on :data:`sys.path_hooks`
676 (i.e. a :term:`path entry hook`) which knows how to locate modules given
677 a :term:`path entry`.
678
679 path entry hook
680 A callable on the :data:`sys.path_hook` list which returns a :term:`path
681 entry finder` if it knows how to find modules on a specific :term:`path
682 entry`.
683
Nick Coghlan1685db02012-08-20 13:49:08 +1000684 path based finder
Barry Warsawdadebab2012-07-31 16:03:09 -0400685 One of the default :term:`meta path finders <meta path finder>` which
686 searches an :term:`import path` for modules.
Barry Warsawd7d21942012-07-29 16:36:17 -0400687
688 portion
689 A set of files in a single directory (possibly stored in a zip file)
690 that contribute to a namespace package, as defined in :pep:`420`.
691
Christian Heimesd8654cf2007-12-02 15:22:16 +0000692 positional argument
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -0800693 See :term:`argument`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000694
Nick Coghlan4dae27a2013-10-20 13:22:04 +1000695 provisional API
696 A provisional API is one which has been deliberately excluded from
Barry Warsawd7d21942012-07-29 16:36:17 -0400697 the standard library's backwards compatibility guarantees. While major
Nick Coghlan4dae27a2013-10-20 13:22:04 +1000698 changes to such interfaces are not expected, as long as they are marked
Eli Bendersky6bdb6502012-03-30 10:52:25 +0300699 provisional, backwards incompatible changes (up to and including removal
Nick Coghlan4dae27a2013-10-20 13:22:04 +1000700 of the interface) may occur if deemed necessary by core developers. Such
Eli Bendersky6bdb6502012-03-30 10:52:25 +0300701 changes will not be made gratuitously -- they will occur only if serious
Nick Coghlan4dae27a2013-10-20 13:22:04 +1000702 fundamental flaws are uncovered that were missed prior to the inclusion
703 of the API.
704
705 Even for provisional APIs, backwards incompatible changes are seen as
706 a "solution of last resort" - every attempt will still be made to find
707 a backwards compatible resolution to any identified problems.
Eli Bendersky6bdb6502012-03-30 10:52:25 +0300708
Barry Warsawd7d21942012-07-29 16:36:17 -0400709 This process allows the standard library to continue to evolve over
710 time, without locking in problematic design errors for extended periods
711 of time. See :pep:`411` for more details.
Eli Bendersky6bdb6502012-03-30 10:52:25 +0300712
Nick Coghlan4dae27a2013-10-20 13:22:04 +1000713 provisional package
714 See :term:`provisional API`.
715
Guido van Rossumf10aa982007-08-17 18:30:38 +0000716 Python 3000
Barry Warsawd7d21942012-07-29 16:36:17 -0400717 Nickname for the Python 3.x release line (coined long ago when the
718 release of version 3 was something in the distant future.) This is also
Benjamin Peterson1e2f0502008-05-26 12:52:02 +0000719 abbreviated "Py3k".
Guido van Rossumf10aa982007-08-17 18:30:38 +0000720
Christian Heimesd8654cf2007-12-02 15:22:16 +0000721 Pythonic
Benjamin Peterson5478b472008-09-17 22:25:09 +0000722 An idea or piece of code which closely follows the most common idioms
723 of the Python language, rather than implementing code using concepts
724 common to other languages. For example, a common idiom in Python is
725 to loop over all elements of an iterable using a :keyword:`for`
726 statement. Many other languages don't have this type of construct, so
727 people unfamiliar with Python sometimes use a numerical counter instead::
Georg Brandl48310cd2009-01-03 21:18:54 +0000728
Christian Heimesd8654cf2007-12-02 15:22:16 +0000729 for i in range(len(food)):
Georg Brandla09ca382007-12-02 18:20:12 +0000730 print(food[i])
Christian Heimesd8654cf2007-12-02 15:22:16 +0000731
732 As opposed to the cleaner, Pythonic method::
733
734 for piece in food:
Georg Brandla09ca382007-12-02 18:20:12 +0000735 print(piece)
Christian Heimesd8654cf2007-12-02 15:22:16 +0000736
Antoine Pitrou86a36b52011-11-25 18:56:07 +0100737 qualified name
738 A dotted name showing the "path" from a module's global scope to a
739 class, function or method defined in that module, as defined in
740 :pep:`3155`. For top-level functions and classes, the qualified name
741 is the same as the object's name::
742
743 >>> class C:
744 ... class D:
745 ... def meth(self):
746 ... pass
747 ...
748 >>> C.__qualname__
749 'C'
750 >>> C.D.__qualname__
751 'C.D'
752 >>> C.D.meth.__qualname__
753 'C.D.meth'
754
Barry Warsawd7d21942012-07-29 16:36:17 -0400755 When used to refer to modules, the *fully qualified name* means the
756 entire dotted path to the module, including any parent packages,
757 e.g. ``email.mime.text``::
758
759 >>> import email.mime.text
760 >>> email.mime.text.__name__
761 'email.mime.text'
762
Guido van Rossumf10aa982007-08-17 18:30:38 +0000763 reference count
Benjamin Peterson5478b472008-09-17 22:25:09 +0000764 The number of references to an object. When the reference count of an
765 object drops to zero, it is deallocated. Reference counting is
766 generally not visible to Python code, but it is a key element of the
767 :term:`CPython` implementation. The :mod:`sys` module defines a
Georg Brandlede6c2a2010-01-05 10:22:04 +0000768 :func:`~sys.getrefcount` function that programmers can call to return the
Benjamin Peterson5478b472008-09-17 22:25:09 +0000769 reference count for a particular object.
770
Barry Warsawd7d21942012-07-29 16:36:17 -0400771 regular package
772 A traditional :term:`package`, such as a directory containing an
773 ``__init__.py`` file.
774
Georg Brandlbcce1252013-10-08 08:06:18 +0200775 See also :term:`namespace package`.
776
Guido van Rossumf10aa982007-08-17 18:30:38 +0000777 __slots__
Georg Brandl85eb8c12007-08-31 16:33:38 +0000778 A declaration inside a class that saves memory by pre-declaring space for
779 instance attributes and eliminating instance dictionaries. Though
780 popular, the technique is somewhat tricky to get right and is best
781 reserved for rare cases where there are large numbers of instances in a
782 memory-critical application.
Georg Brandl48310cd2009-01-03 21:18:54 +0000783
Guido van Rossumf10aa982007-08-17 18:30:38 +0000784 sequence
785 An :term:`iterable` which supports efficient element access using integer
Benjamin Peterson5478b472008-09-17 22:25:09 +0000786 indices via the :meth:`__getitem__` special method and defines a
Andrew Svetlov8cf1cc42012-10-05 13:26:10 +0300787 :meth:`__len__` method that returns the length of the sequence.
Guido van Rossumf10aa982007-08-17 18:30:38 +0000788 Some built-in sequence types are :class:`list`, :class:`str`,
Georg Brandl2ae8ac22009-02-05 10:40:48 +0000789 :class:`tuple`, and :class:`bytes`. Note that :class:`dict` also
Guido van Rossumf10aa982007-08-17 18:30:38 +0000790 supports :meth:`__getitem__` and :meth:`__len__`, but is considered a
791 mapping rather than a sequence because the lookups use arbitrary
792 :term:`immutable` keys rather than integers.
793
Larry Hastings3732ed22014-03-15 21:13:56 -0700794 The :class:`collections.abc.Sequence` abstract base class
795 defines a much richer interface that goes beyond just
796 :meth:`__getitem__` and :meth:`__len__`, adding :meth:`count`,
797 :meth:`index`, :meth:`__contains__`, and
798 :meth:`__reversed__`. Types that implement this expanded
799 interface can be registered explicitly using
800 :func:`~abc.register`.
801
Łukasz Langafdcf2b72013-06-07 22:54:03 +0200802 single dispatch
803 A form of :term:`generic function` dispatch where the implementation is
804 chosen based on the type of a single argument.
805
Christian Heimesd8654cf2007-12-02 15:22:16 +0000806 slice
Georg Brandlc6fe37b2007-12-03 21:07:25 +0000807 An object usually containing a portion of a :term:`sequence`. A slice is
Christian Heimesd8654cf2007-12-02 15:22:16 +0000808 created using the subscript notation, ``[]`` with colons between numbers
809 when several are given, such as in ``variable_name[1:3:5]``. The bracket
Georg Brandla09ca382007-12-02 18:20:12 +0000810 (subscript) notation uses :class:`slice` objects internally.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000811
Georg Brandlaf265f42008-12-07 15:06:20 +0000812 special method
813 A method that is called implicitly by Python to execute a certain
814 operation on a type, such as addition. Such methods have names starting
815 and ending with double underscores. Special methods are documented in
816 :ref:`specialnames`.
817
Christian Heimesd8654cf2007-12-02 15:22:16 +0000818 statement
819 A statement is part of a suite (a "block" of code). A statement is either
Georg Brandl60e602d2013-10-06 11:57:13 +0200820 an :term:`expression` or one of several constructs with a keyword, such
Georg Brandla09ca382007-12-02 18:20:12 +0000821 as :keyword:`if`, :keyword:`while` or :keyword:`for`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000822
Benjamin Peterson82f614b2011-04-20 18:27:32 -0500823 struct sequence
Florent Xiclunaf8240d62011-11-11 19:58:53 +0100824 A tuple with named elements. Struct sequences expose an interface similar
Benjamin Peterson82f614b2011-04-20 18:27:32 -0500825 to :term:`named tuple` in that elements can either be accessed either by
826 index or as an attribute. However, they do not have any of the named tuple
827 methods like :meth:`~collections.somenamedtuple._make` or
828 :meth:`~collections.somenamedtuple._asdict`. Examples of struct sequences
829 include :data:`sys.float_info` and the return value of :func:`os.stat`.
830
Nick Coghlanb9fdb7a2015-01-07 00:22:00 +1000831 text encoding
832 A codec which encodes Unicode strings to bytes.
833
Antoine Pitroudd799d22013-12-05 23:46:32 +0100834 text file
835 A :term:`file object` able to read and write :class:`str` objects.
836 Often, a text file actually accesses a byte-oriented datastream
Nick Coghlanb9fdb7a2015-01-07 00:22:00 +1000837 and handles the :term:`text encoding` automatically.
Antoine Pitroudd799d22013-12-05 23:46:32 +0100838
839 .. seealso::
840 A :term:`binary file` reads and write :class:`bytes` objects.
841
Benjamin Peterson5478b472008-09-17 22:25:09 +0000842 triple-quoted string
843 A string which is bound by three instances of either a quotation mark
844 (") or an apostrophe ('). While they don't provide any functionality
845 not available with single-quoted strings, they are useful for a number
846 of reasons. They allow you to include unescaped single and double
847 quotes within a string and they can span multiple lines without the
848 use of the continuation character, making them especially useful when
849 writing docstrings.
850
Guido van Rossumf10aa982007-08-17 18:30:38 +0000851 type
852 The type of a Python object determines what kind of object it is; every
853 object has a type. An object's type is accessible as its
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +0300854 :attr:`~instance.__class__` attribute or can be retrieved with
855 ``type(obj)``.
Benjamin Peterson5478b472008-09-17 22:25:09 +0000856
R David Murray1b00f252012-08-15 10:43:58 -0400857 universal newlines
858 A manner of interpreting text streams in which all of the following are
859 recognized as ending a line: the Unix end-of-line convention ``'\n'``,
860 the Windows convention ``'\r\n'``, and the old Macintosh convention
861 ``'\r'``. See :pep:`278` and :pep:`3116`, as well as
Terry Jan Reedy004e8702014-08-23 18:28:44 -0400862 :func:`bytes.splitlines` for an additional use.
R David Murray1b00f252012-08-15 10:43:58 -0400863
Nick Coghlan1d520962014-09-06 20:38:23 +1000864 virtual environment
865 A cooperatively isolated runtime environment that allows Python users
866 and applications to install and upgrade Python distribution packages
867 without interfering with the behaviour of other Python applications
868 running on the same system.
869
Martin Panterd21e0b52015-10-10 10:36:22 +0000870 See also :ref:`scripts-pyvenv`.
Nick Coghlan1d520962014-09-06 20:38:23 +1000871
Benjamin Peterson5478b472008-09-17 22:25:09 +0000872 virtual machine
873 A computer defined entirely in software. Python's virtual machine
874 executes the :term:`bytecode` emitted by the bytecode compiler.
Georg Brandl48310cd2009-01-03 21:18:54 +0000875
Guido van Rossumf10aa982007-08-17 18:30:38 +0000876 Zen of Python
877 Listing of Python design principles and philosophies that are helpful in
878 understanding and using the language. The listing can be found by typing
879 "``import this``" at the interactive prompt.