blob: 55c3470d6705440338ab358ebe0caa77929d4d14 [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
Georg Brandl22b34312009-07-26 14:54:51 +000037 data structures (in the :mod:`collections` 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
44 function. There are two types of arguments:
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
79 <http://www.python.org/~guido/>`_, Python's creator.
Georg Brandl48310cd2009-01-03 21:18:54 +000080
Georg Brandl9afde1c2007-11-01 20:32:30 +000081 bytecode
82 Python source code is compiled into bytecode, the internal representation
Brett Cannon8315fd12010-07-02 22:03:00 +000083 of a Python program in the CPython interpreter. The bytecode is also
84 cached in ``.pyc`` and ``.pyo`` files so that executing the same file is
85 faster the second time (recompilation from source to bytecode can be
86 avoided). This "intermediate language" is said to run on a
87 :term:`virtual machine` that executes the machine code corresponding to
88 each bytecode. Do note that bytecodes are not expected to work between
89 different Python virtual machines, nor to be stable between Python
90 releases.
Benjamin Peterson5478b472008-09-17 22:25:09 +000091
Georg Brandl2cb72d32010-07-03 10:26:54 +000092 A list of bytecode instructions can be found in the documentation for
93 :ref:`the dis module <bytecodes>`.
94
Benjamin Peterson5478b472008-09-17 22:25:09 +000095 class
96 A template for creating user-defined objects. Class definitions
97 normally contain method definitions which operate on instances of the
98 class.
Georg Brandl48310cd2009-01-03 21:18:54 +000099
Benjamin Peterson5478b472008-09-17 22:25:09 +0000100 coercion
101 The implicit conversion of an instance of one type to another during an
102 operation which involves two arguments of the same type. For example,
103 ``int(3.15)`` converts the floating point number to the integer ``3``, but
104 in ``3+4.5``, each argument is of a different type (one int, one float),
105 and both must be converted to the same type before they can be added or it
Benjamin Peterson2d718222008-11-21 00:25:02 +0000106 will raise a ``TypeError``. Without coercion, all arguments of even
Benjamin Peterson5478b472008-09-17 22:25:09 +0000107 compatible types would have to be normalized to the same value by the
108 programmer, e.g., ``float(3)+4.5`` rather than just ``3+4.5``.
Georg Brandl48310cd2009-01-03 21:18:54 +0000109
Guido van Rossumf10aa982007-08-17 18:30:38 +0000110 complex number
111 An extension of the familiar real number system in which all numbers are
112 expressed as a sum of a real part and an imaginary part. Imaginary
113 numbers are real multiples of the imaginary unit (the square root of
114 ``-1``), often written ``i`` in mathematics or ``j`` in
Georg Brandl22b34312009-07-26 14:54:51 +0000115 engineering. Python has built-in support for complex numbers, which are
Guido van Rossumf10aa982007-08-17 18:30:38 +0000116 written with this latter notation; the imaginary part is written with a
117 ``j`` suffix, e.g., ``3+1j``. To get access to complex equivalents of the
118 :mod:`math` module, use :mod:`cmath`. Use of complex numbers is a fairly
119 advanced mathematical feature. If you're not aware of a need for them,
120 it's almost certain you can safely ignore them.
Georg Brandl48310cd2009-01-03 21:18:54 +0000121
Christian Heimes895627f2007-12-08 17:28:33 +0000122 context manager
Benjamin Peterson5478b472008-09-17 22:25:09 +0000123 An object which controls the environment seen in a :keyword:`with`
Christian Heimes895627f2007-12-08 17:28:33 +0000124 statement by defining :meth:`__enter__` and :meth:`__exit__` methods.
125 See :pep:`343`.
126
Benjamin Peterson5478b472008-09-17 22:25:09 +0000127 CPython
Antoine Pitrou00342812011-01-06 16:31:28 +0000128 The canonical implementation of the Python programming language, as
129 distributed on `python.org <http://python.org>`_. The term "CPython"
130 is used when necessary to distinguish this implementation from others
131 such as Jython or IronPython.
Benjamin Peterson5478b472008-09-17 22:25:09 +0000132
Christian Heimesd8654cf2007-12-02 15:22:16 +0000133 decorator
134 A function returning another function, usually applied as a function
135 transformation using the ``@wrapper`` syntax. Common examples for
136 decorators are :func:`classmethod` and :func:`staticmethod`.
137
138 The decorator syntax is merely syntactic sugar, the following two
139 function definitions are semantically equivalent::
140
141 def f(...):
142 ...
143 f = staticmethod(f)
144
145 @staticmethod
146 def f(...):
147 ...
148
Georg Brandlaf265f42008-12-07 15:06:20 +0000149 The same concept exists for classes, but is less commonly used there. See
150 the documentation for :ref:`function definitions <function>` and
151 :ref:`class definitions <class>` for more about decorators.
Georg Brandla09ca382007-12-02 18:20:12 +0000152
Guido van Rossumf10aa982007-08-17 18:30:38 +0000153 descriptor
Benjamin Peterson5478b472008-09-17 22:25:09 +0000154 Any object which defines the methods :meth:`__get__`, :meth:`__set__`, or
Georg Brandl85eb8c12007-08-31 16:33:38 +0000155 :meth:`__delete__`. When a class attribute is a descriptor, its special
Georg Brandl9afde1c2007-11-01 20:32:30 +0000156 binding behavior is triggered upon attribute lookup. Normally, using
157 *a.b* to get, set or delete an attribute looks up the object named *b* in
158 the class dictionary for *a*, but if *b* is a descriptor, the respective
159 descriptor method gets called. Understanding descriptors is a key to a
160 deep understanding of Python because they are the basis for many features
161 including functions, methods, properties, class methods, static methods,
162 and reference to super classes.
163
164 For more information about descriptors' methods, see :ref:`descriptors`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000165
Guido van Rossumf10aa982007-08-17 18:30:38 +0000166 dictionary
Senthil Kumaran6080db72012-03-12 10:05:34 -0700167 An associative array, where arbitrary keys are mapped to values. The
168 keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
169 Called a hash in Perl.
Georg Brandl3dbca812008-07-23 16:10:53 +0000170
171 docstring
Benjamin Peterson5478b472008-09-17 22:25:09 +0000172 A string literal which appears as the first expression in a class,
173 function or module. While ignored when the suite is executed, it is
174 recognized by the compiler and put into the :attr:`__doc__` attribute
175 of the enclosing class, function or module. Since it is available via
176 introspection, it is the canonical place for documentation of the
Georg Brandl3dbca812008-07-23 16:10:53 +0000177 object.
Georg Brandl48310cd2009-01-03 21:18:54 +0000178
179 duck-typing
Georg Brandl73b1c7b2010-07-10 10:39:57 +0000180 A programming style which does not look at an object's type to determine
181 if it has the right interface; instead, the method or attribute is simply
182 called or used ("If it looks like a duck and quacks like a duck, it
Guido van Rossumf10aa982007-08-17 18:30:38 +0000183 must be a duck.") By emphasizing interfaces rather than specific types,
184 well-designed code improves its flexibility by allowing polymorphic
185 substitution. Duck-typing avoids tests using :func:`type` or
Georg Brandl8a1c2542010-07-11 08:36:20 +0000186 :func:`isinstance`. (Note, however, that duck-typing can be complemented
Éric Araujo0519b092011-08-19 00:39:19 +0200187 with :term:`abstract base classes <abstract base class>`.) Instead, it
188 typically employs :func:`hasattr` tests or :term:`EAFP` programming.
Georg Brandl48310cd2009-01-03 21:18:54 +0000189
Guido van Rossumf10aa982007-08-17 18:30:38 +0000190 EAFP
191 Easier to ask for forgiveness than permission. This common Python coding
192 style assumes the existence of valid keys or attributes and catches
193 exceptions if the assumption proves false. This clean and fast style is
194 characterized by the presence of many :keyword:`try` and :keyword:`except`
Georg Brandl48310cd2009-01-03 21:18:54 +0000195 statements. The technique contrasts with the :term:`LBYL` style
Benjamin Peterson5478b472008-09-17 22:25:09 +0000196 common to many other languages such as C.
Guido van Rossumf10aa982007-08-17 18:30:38 +0000197
Christian Heimesd8654cf2007-12-02 15:22:16 +0000198 expression
199 A piece of syntax which can be evaluated to some value. In other words,
Benjamin Peterson5478b472008-09-17 22:25:09 +0000200 an expression is an accumulation of expression elements like literals,
201 names, attribute access, operators or function calls which all return a
202 value. In contrast to many other languages, not all language constructs
203 are expressions. There are also :term:`statement`\s which cannot be used
204 as expressions, such as :keyword:`if`. Assignments are also statements,
205 not expressions.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000206
Guido van Rossumf10aa982007-08-17 18:30:38 +0000207 extension module
Georg Brandl9d9848e2010-12-28 11:48:53 +0000208 A module written in C or C++, using Python's C API to interact with the
209 core and with user code.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000210
Antoine Pitrou0b65b0f2010-09-15 09:58:26 +0000211 file object
212 An object exposing a file-oriented API (with methods such as
Georg Brandl9d9848e2010-12-28 11:48:53 +0000213 :meth:`read()` or :meth:`write()`) to an underlying resource. Depending
214 on the way it was created, a file object can mediate access to a real
Sandro Tosi7f671332012-06-02 23:41:19 +0200215 on-disk file or to another type of storage or communication device
Georg Brandl9d9848e2010-12-28 11:48:53 +0000216 (for example standard input/output, in-memory buffers, sockets, pipes,
217 etc.). File objects are also called :dfn:`file-like objects` or
218 :dfn:`streams`.
Antoine Pitrou0b65b0f2010-09-15 09:58:26 +0000219
Georg Brandl9d9848e2010-12-28 11:48:53 +0000220 There are actually three categories of file objects: raw binary files,
221 buffered binary files and text files. Their interfaces are defined in the
222 :mod:`io` module. The canonical way to create a file object is by using
223 the :func:`open` function.
Antoine Pitrou0b65b0f2010-09-15 09:58:26 +0000224
225 file-like object
226 A synonym for :term:`file object`.
227
Brett Cannon51d4aab2009-01-25 04:21:39 +0000228 finder
229 An object that tries to find the :term:`loader` for a module. It must
230 implement a method named :meth:`find_module`. See :pep:`302` for
Brett Cannone43b0602009-03-21 03:11:16 +0000231 details and :class:`importlib.abc.Finder` for an
232 :term:`abstract base class`.
Brett Cannon51d4aab2009-01-25 04:21:39 +0000233
Benjamin Peterson2d718222008-11-21 00:25:02 +0000234 floor division
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000235 Mathematical division that rounds down to nearest integer. The floor
236 division operator is ``//``. For example, the expression ``11 // 4``
237 evaluates to ``2`` in contrast to the ``2.75`` returned by float true
238 division. Note that ``(-11) // 4`` is ``-3`` because that is ``-2.75``
239 rounded *downward*. See :pep:`238`.
Benjamin Peterson2d718222008-11-21 00:25:02 +0000240
Christian Heimesd8654cf2007-12-02 15:22:16 +0000241 function
242 A series of statements which returns some value to a caller. It can also
Chris Jerdonekb4309942012-12-25 14:54:44 -0800243 be passed zero or more :term:`arguments <argument>` which may be used in
244 the execution of the body. See also :term:`parameter`, :term:`method`,
245 and the :ref:`function` section.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000246
Guido van Rossumf10aa982007-08-17 18:30:38 +0000247 __future__
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000248 A pseudo-module which programmers can use to enable new language features
Benjamin Peterson2d718222008-11-21 00:25:02 +0000249 which are not compatible with the current interpreter.
250
251 By importing the :mod:`__future__` module and evaluating its variables,
252 you can see when a new feature was first added to the language and when it
253 becomes the default::
Georg Brandl48310cd2009-01-03 21:18:54 +0000254
Guido van Rossumf10aa982007-08-17 18:30:38 +0000255 >>> import __future__
256 >>> __future__.division
257 _Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)
258
259 garbage collection
260 The process of freeing memory when it is not used anymore. Python
261 performs garbage collection via reference counting and a cyclic garbage
262 collector that is able to detect and break reference cycles.
Georg Brandl48310cd2009-01-03 21:18:54 +0000263
Benjamin Peterson08bf91c2010-04-11 16:12:57 +0000264 .. index:: single: generator
265
Guido van Rossumf10aa982007-08-17 18:30:38 +0000266 generator
Benjamin Peterson5478b472008-09-17 22:25:09 +0000267 A function which returns an iterator. It looks like a normal function
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000268 except that it contains :keyword:`yield` statements for producing a series
269 a values usable in a for-loop or that can be retrieved one at a time with
270 the :func:`next` function. Each :keyword:`yield` temporarily suspends
271 processing, remembering the location execution state (including local
272 variables and pending try-statements). When the generator resumes, it
273 picks-up where it left-off (in contrast to functions which start fresh on
Éric Araujoe0854f92011-05-27 04:36:52 +0200274 every invocation).
Georg Brandl48310cd2009-01-03 21:18:54 +0000275
Guido van Rossumf10aa982007-08-17 18:30:38 +0000276 .. index:: single: generator expression
Georg Brandl48310cd2009-01-03 21:18:54 +0000277
Guido van Rossumf10aa982007-08-17 18:30:38 +0000278 generator expression
Benjamin Peterson08bf91c2010-04-11 16:12:57 +0000279 An expression that returns an iterator. It looks like a normal expression
Guido van Rossumf10aa982007-08-17 18:30:38 +0000280 followed by a :keyword:`for` expression defining a loop variable, range,
281 and an optional :keyword:`if` expression. The combined expression
282 generates values for an enclosing function::
Georg Brandl48310cd2009-01-03 21:18:54 +0000283
Guido van Rossumf10aa982007-08-17 18:30:38 +0000284 >>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81
285 285
Georg Brandl48310cd2009-01-03 21:18:54 +0000286
Guido van Rossumf10aa982007-08-17 18:30:38 +0000287 GIL
288 See :term:`global interpreter lock`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000289
Guido van Rossumf10aa982007-08-17 18:30:38 +0000290 global interpreter lock
Antoine Pitrou00342812011-01-06 16:31:28 +0000291 The mechanism used by the :term:`CPython` interpreter to assure that
292 only one thread executes Python :term:`bytecode` at a time.
293 This simplifies the CPython implementation by making the object model
294 (including critical built-in types such as :class:`dict`) implicitly
295 safe against concurrent access. Locking the entire interpreter
296 makes it easier for the interpreter to be multi-threaded, at the
297 expense of much of the parallelism afforded by multi-processor
298 machines.
299
300 However, some extension modules, either standard or third-party,
301 are designed so as to release the GIL when doing computationally-intensive
302 tasks such as compression or hashing. Also, the GIL is always released
303 when doing I/O.
304
305 Past efforts to create a "free-threaded" interpreter (one which locks
306 shared data at a much finer granularity) have not been successful
307 because performance suffered in the common single-processor case. It
308 is believed that overcoming this performance issue would make the
309 implementation much more complicated and therefore costlier to maintain.
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000310
311 hashable
Benjamin Peterson5478b472008-09-17 22:25:09 +0000312 An object is *hashable* if it has a hash value which never changes during
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000313 its lifetime (it needs a :meth:`__hash__` method), and can be compared to
Georg Brandl05f5ab72008-09-24 09:11:47 +0000314 other objects (it needs an :meth:`__eq__` method). Hashable objects which
315 compare equal must have the same hash value.
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000316
317 Hashability makes an object usable as a dictionary key and a set member,
318 because these data structures use the hash value internally.
319
Benjamin Peterson5478b472008-09-17 22:25:09 +0000320 All of Python's immutable built-in objects are hashable, while no mutable
321 containers (such as lists or dictionaries) are. Objects which are
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000322 instances of user-defined classes are hashable by default; they all
323 compare unequal, and their hash value is their :func:`id`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000324
Guido van Rossumf10aa982007-08-17 18:30:38 +0000325 IDLE
326 An Integrated Development Environment for Python. IDLE is a basic editor
Benjamin Peterson5478b472008-09-17 22:25:09 +0000327 and interpreter environment which ships with the standard distribution of
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000328 Python.
Georg Brandl48310cd2009-01-03 21:18:54 +0000329
Guido van Rossumf10aa982007-08-17 18:30:38 +0000330 immutable
Benjamin Peterson5478b472008-09-17 22:25:09 +0000331 An object with a fixed value. Immutable objects include numbers, strings and
332 tuples. Such an object cannot be altered. A new object has to
Guido van Rossumf10aa982007-08-17 18:30:38 +0000333 be created if a different value has to be stored. They play an important
334 role in places where a constant hash value is needed, for example as a key
335 in a dictionary.
Benjamin Peterson2d718222008-11-21 00:25:02 +0000336
Brett Cannon51d4aab2009-01-25 04:21:39 +0000337 importer
338 An object that both finds and loads a module; both a
339 :term:`finder` and :term:`loader` object.
340
Guido van Rossumf10aa982007-08-17 18:30:38 +0000341 interactive
Benjamin Peterson5478b472008-09-17 22:25:09 +0000342 Python has an interactive interpreter which means you can enter
343 statements and expressions at the interpreter prompt, immediately
344 execute them and see their results. Just launch ``python`` with no
345 arguments (possibly by selecting it from your computer's main
346 menu). It is a very powerful way to test out new ideas or inspect
347 modules and packages (remember ``help(x)``).
Georg Brandl48310cd2009-01-03 21:18:54 +0000348
Guido van Rossumf10aa982007-08-17 18:30:38 +0000349 interpreted
Benjamin Peterson5478b472008-09-17 22:25:09 +0000350 Python is an interpreted language, as opposed to a compiled one,
351 though the distinction can be blurry because of the presence of the
352 bytecode compiler. This means that source files can be run directly
353 without explicitly creating an executable which is then run.
354 Interpreted languages typically have a shorter development/debug cycle
355 than compiled ones, though their programs generally also run more
356 slowly. See also :term:`interactive`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000357
Guido van Rossumf10aa982007-08-17 18:30:38 +0000358 iterable
Ezio Melottid581fff2013-01-02 22:29:09 +0200359 An object capable of returning its members one at a time. Examples of
360 iterables include all sequence types (such as :class:`list`, :class:`str`,
361 and :class:`tuple`) and some non-sequence types like :class:`dict`,
362 :term:`file objects <file object>`, and objects of any classes you define
363 with an :meth:`__iter__` or :meth:`__getitem__` method. Iterables can be
364 used in a :keyword:`for` loop and in many other places where a sequence is
365 needed (:func:`zip`, :func:`map`, ...). When an iterable object is passed
366 as an argument to the built-in function :func:`iter`, it returns an
367 iterator for the object. This iterator is good for one pass over the set
368 of values. When using iterables, it is usually not necessary to call
369 :func:`iter` or deal with iterator objects yourself. The ``for``
Guido van Rossumf10aa982007-08-17 18:30:38 +0000370 statement does that automatically for you, creating a temporary unnamed
371 variable to hold the iterator for the duration of the loop. See also
372 :term:`iterator`, :term:`sequence`, and :term:`generator`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000373
Guido van Rossumf10aa982007-08-17 18:30:38 +0000374 iterator
375 An object representing a stream of data. Repeated calls to the iterator's
Ezio Melotti7fa82222012-10-12 13:42:08 +0300376 :meth:`~iterator.__next__` method (or passing it to the built-in function
Georg Brandlb30f3302011-01-06 09:23:56 +0000377 :func:`next`) return successive items in the stream. When no more data
378 are available a :exc:`StopIteration` exception is raised instead. At this
Benjamin Petersone7c78b22008-07-03 20:28:26 +0000379 point, the iterator object is exhausted and any further calls to its
Georg Brandlb30f3302011-01-06 09:23:56 +0000380 :meth:`__next__` method just raise :exc:`StopIteration` again. Iterators
381 are required to have an :meth:`__iter__` method that returns the iterator
Guido van Rossumf10aa982007-08-17 18:30:38 +0000382 object itself so every iterator is also iterable and may be used in most
383 places where other iterables are accepted. One notable exception is code
Benjamin Peterson5478b472008-09-17 22:25:09 +0000384 which attempts multiple iteration passes. A container object (such as a
Guido van Rossumf10aa982007-08-17 18:30:38 +0000385 :class:`list`) produces a fresh new iterator each time you pass it to the
386 :func:`iter` function or use it in a :keyword:`for` loop. Attempting this
387 with an iterator will just return the same exhausted iterator object used
388 in the previous iteration pass, making it appear like an empty container.
Georg Brandl48310cd2009-01-03 21:18:54 +0000389
Georg Brandl9afde1c2007-11-01 20:32:30 +0000390 More information can be found in :ref:`typeiter`.
391
Georg Brandlc275e152010-11-05 07:10:41 +0000392 key function
393 A key function or collation function is a callable that returns a value
394 used for sorting or ordering. For example, :func:`locale.strxfrm` is
395 used to produce a sort key that is aware of locale specific sort
396 conventions.
397
398 A number of tools in Python accept key functions to control how elements
399 are ordered or grouped. They include :func:`min`, :func:`max`,
400 :func:`sorted`, :meth:`list.sort`, :func:`heapq.nsmallest`,
401 :func:`heapq.nlargest`, and :func:`itertools.groupby`.
402
403 There are several ways to create a key function. For example. the
404 :meth:`str.lower` method can serve as a key function for case insensitive
405 sorts. Alternatively, an ad-hoc key function can be built from a
406 :keyword:`lambda` expression such as ``lambda r: (r[0], r[2])``. Also,
Sandro Tosi165a2c22012-04-01 01:50:00 +0200407 the :mod:`operator` module provides three key function constructors:
Georg Brandlc275e152010-11-05 07:10:41 +0000408 :func:`~operator.attrgetter`, :func:`~operator.itemgetter`, and
409 :func:`~operator.methodcaller`. See the :ref:`Sorting HOW TO
410 <sortinghowto>` for examples of how to create and use key functions.
411
Christian Heimesd8654cf2007-12-02 15:22:16 +0000412 keyword argument
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -0800413 See :term:`argument`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000414
415 lambda
416 An anonymous inline function consisting of a single :term:`expression`
417 which is evaluated when the function is called. The syntax to create
418 a lambda function is ``lambda [arguments]: expression``
419
Guido van Rossumf10aa982007-08-17 18:30:38 +0000420 LBYL
421 Look before you leap. This coding style explicitly tests for
422 pre-conditions before making calls or lookups. This style contrasts with
423 the :term:`EAFP` approach and is characterized by the presence of many
424 :keyword:`if` statements.
Benjamin Peterson5478b472008-09-17 22:25:09 +0000425
Raymond Hettinger09f44142010-12-17 20:19:50 +0000426 In a multi-threaded environment, the LBYL approach can risk introducing a
427 race condition between "the looking" and "the leaping". For example, the
428 code, ``if key in mapping: return mapping[key]`` can fail if another
429 thread removes *key* from *mapping* after the test, but before the lookup.
430 This issue can be solved with locks or by using the EAFP approach.
431
Benjamin Peterson5478b472008-09-17 22:25:09 +0000432 list
433 A built-in Python :term:`sequence`. Despite its name it is more akin
434 to an array in other languages than to a linked list since access to
435 elements are O(1).
Georg Brandl48310cd2009-01-03 21:18:54 +0000436
Guido van Rossumf10aa982007-08-17 18:30:38 +0000437 list comprehension
Benjamin Peterson5478b472008-09-17 22:25:09 +0000438 A compact way to process all or part of the elements in a sequence and
Georg Brandlede6c2a2010-01-05 10:22:04 +0000439 return a list with the results. ``result = ['{:#04x}'.format(x) for x in
Benjamin Peterson5478b472008-09-17 22:25:09 +0000440 range(256) if x % 2 == 0]`` generates a list of strings containing
441 even hex numbers (0x..) in the range from 0 to 255. The :keyword:`if`
442 clause is optional. If omitted, all elements in ``range(256)`` are
443 processed.
Georg Brandl48310cd2009-01-03 21:18:54 +0000444
Brett Cannon51d4aab2009-01-25 04:21:39 +0000445 loader
446 An object that loads a module. It must define a method named
447 :meth:`load_module`. A loader is typically returned by a
Brett Cannone43b0602009-03-21 03:11:16 +0000448 :term:`finder`. See :pep:`302` for details and
449 :class:`importlib.abc.Loader` for an :term:`abstract base class`.
Brett Cannon51d4aab2009-01-25 04:21:39 +0000450
Guido van Rossumf10aa982007-08-17 18:30:38 +0000451 mapping
Raymond Hettingere3ee66f2011-01-08 23:44:37 +0000452 A container object that supports arbitrary key lookups and implements the
Éric Araujo7c12bae2011-07-26 15:14:35 +0200453 methods specified in the :class:`~collections.Mapping` or
454 :class:`~collections.MutableMapping`
Éric Araujofa088db2011-06-04 18:42:38 +0200455 :ref:`abstract base classes <collections-abstract-base-classes>`. Examples
456 include :class:`dict`, :class:`collections.defaultdict`,
Raymond Hettingere3ee66f2011-01-08 23:44:37 +0000457 :class:`collections.OrderedDict` and :class:`collections.Counter`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000458
Guido van Rossumf10aa982007-08-17 18:30:38 +0000459 metaclass
460 The class of a class. Class definitions create a class name, a class
461 dictionary, and a list of base classes. The metaclass is responsible for
462 taking those three arguments and creating the class. Most object oriented
463 programming languages provide a default implementation. What makes Python
464 special is that it is possible to create custom metaclasses. Most users
465 never need this tool, but when the need arises, metaclasses can provide
466 powerful, elegant solutions. They have been used for logging attribute
467 access, adding thread-safety, tracking object creation, implementing
468 singletons, and many other tasks.
Georg Brandl9afde1c2007-11-01 20:32:30 +0000469
470 More information can be found in :ref:`metaclasses`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000471
472 method
Benjamin Peterson5478b472008-09-17 22:25:09 +0000473 A function which is defined inside a class body. If called as an attribute
Christian Heimesd8654cf2007-12-02 15:22:16 +0000474 of an instance of that class, the method will get the instance object as
475 its first :term:`argument` (which is usually called ``self``).
476 See :term:`function` and :term:`nested scope`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000477
Michael Foord95fc51d2010-11-20 15:07:30 +0000478 method resolution order
479 Method Resolution Order is the order in which base classes are searched
480 for a member during lookup. See `The Python 2.3 Method Resolution Order
481 <http://www.python.org/download/releases/2.3/mro/>`_.
482
483 MRO
484 See :term:`method resolution order`.
485
Guido van Rossumf10aa982007-08-17 18:30:38 +0000486 mutable
487 Mutable objects can change their value but keep their :func:`id`. See
488 also :term:`immutable`.
Christian Heimes25bb7832008-01-11 16:17:00 +0000489
490 named tuple
Raymond Hettingerd04fa312009-02-04 19:45:13 +0000491 Any tuple-like class whose indexable elements are also accessible using
Christian Heimesd32ed6f2008-01-14 18:49:24 +0000492 named attributes (for example, :func:`time.localtime` returns a
493 tuple-like object where the *year* is accessible either with an
494 index such as ``t[0]`` or with a named attribute like ``t.tm_year``).
495
496 A named tuple can be a built-in type such as :class:`time.struct_time`,
497 or it can be created with a regular class definition. A full featured
498 named tuple can also be created with the factory function
499 :func:`collections.namedtuple`. The latter approach automatically
500 provides extra features such as a self-documenting representation like
501 ``Employee(name='jones', title='programmer')``.
Georg Brandl48310cd2009-01-03 21:18:54 +0000502
Guido van Rossumf10aa982007-08-17 18:30:38 +0000503 namespace
504 The place where a variable is stored. Namespaces are implemented as
Georg Brandl22b34312009-07-26 14:54:51 +0000505 dictionaries. There are the local, global and built-in namespaces as well
Guido van Rossumf10aa982007-08-17 18:30:38 +0000506 as nested namespaces in objects (in methods). Namespaces support
507 modularity by preventing naming conflicts. For instance, the functions
Georg Brandl1a3284e2007-12-02 09:40:06 +0000508 :func:`builtins.open` and :func:`os.open` are distinguished by their
Guido van Rossumf10aa982007-08-17 18:30:38 +0000509 namespaces. Namespaces also aid readability and maintainability by making
510 it clear which module implements a function. For instance, writing
Éric Araujo7af8ebb2011-09-01 03:20:13 +0200511 :func:`random.seed` or :func:`itertools.islice` makes it clear that those
Guido van Rossumf10aa982007-08-17 18:30:38 +0000512 functions are implemented by the :mod:`random` and :mod:`itertools`
Benjamin Peterson5478b472008-09-17 22:25:09 +0000513 modules, respectively.
Georg Brandl48310cd2009-01-03 21:18:54 +0000514
Guido van Rossumf10aa982007-08-17 18:30:38 +0000515 nested scope
516 The ability to refer to a variable in an enclosing definition. For
517 instance, a function defined inside another function can refer to
Benjamin Peterson927ccd22010-06-29 18:36:39 +0000518 variables in the outer function. Note that nested scopes by default work
519 only for reference and not for assignment. Local variables both read and
520 write in the innermost scope. Likewise, global variables read and write
521 to the global namespace. The :keyword:`nonlocal` allows writing to outer
522 scopes.
Georg Brandl48310cd2009-01-03 21:18:54 +0000523
Guido van Rossumf10aa982007-08-17 18:30:38 +0000524 new-style class
Georg Brandl85eb8c12007-08-31 16:33:38 +0000525 Old name for the flavor of classes now used for all class objects. In
526 earlier Python versions, only new-style classes could use Python's newer,
527 versatile features like :attr:`__slots__`, descriptors, properties,
528 :meth:`__getattribute__`, class methods, and static methods.
Georg Brandl9afde1c2007-11-01 20:32:30 +0000529
Benjamin Peterson5478b472008-09-17 22:25:09 +0000530 object
531 Any data with state (attributes or value) and defined behavior
532 (methods). Also the ultimate base class of any :term:`new-style
533 class`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000534
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -0800535 parameter
536 A named entity in a :term:`function` (or method) definition that
537 specifies an :term:`argument` (or in some cases, arguments) that the
538 function can accept. There are five types of parameters:
539
540 * :dfn:`positional-or-keyword`: specifies an argument that can be passed
541 either :term:`positionally <argument>` or as a :term:`keyword argument
542 <argument>`. This is the default kind of parameter, for example *foo*
543 and *bar* in the following::
544
545 def func(foo, bar=None): ...
546
547 * :dfn:`positional-only`: specifies an argument that can be supplied only
548 by position. Python has no syntax for defining positional-only
549 parameters. However, some built-in functions have positional-only
550 parameters (e.g. :func:`abs`).
551
552 * :dfn:`keyword-only`: specifies an argument that can be supplied only
553 by keyword. Keyword-only parameters can be defined by including a
554 single var-positional parameter or bare ``*`` in the parameter list
555 of the function definition before them, for example *kw_only1* and
556 *kw_only2* in the following::
557
558 def func(arg, *, kw_only1, kw_only2): ...
559
560 * :dfn:`var-positional`: specifies that an arbitrary sequence of
561 positional arguments can be provided (in addition to any positional
562 arguments already accepted by other parameters). Such a parameter can
563 be defined by prepending the parameter name with ``*``, for example
564 *args* in the following::
565
566 def func(*args, **kwargs): ...
567
568 * :dfn:`var-keyword`: specifies that arbitrarily many keyword arguments
569 can be provided (in addition to any keyword arguments already accepted
570 by other parameters). Such a parameter can be defined by prepending
571 the parameter name with ``**``, for example *kwargs* in the example
572 above.
573
574 Parameters can specify both optional and required arguments, as well as
575 default values for some optional arguments.
576
577 See also the :term:`argument` glossary entry, the FAQ question on
578 :ref:`the difference between arguments and parameters
579 <faq-argument-vs-parameter>`, the :class:`inspect.Parameter` class, the
580 :ref:`function` section, and :pep:`362`.
581
Christian Heimesd8654cf2007-12-02 15:22:16 +0000582 positional argument
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -0800583 See :term:`argument`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000584
Guido van Rossumf10aa982007-08-17 18:30:38 +0000585 Python 3000
Benjamin Peterson1e2f0502008-05-26 12:52:02 +0000586 Nickname for the Python 3.x release line (coined long ago when the release
587 of version 3 was something in the distant future.) This is also
588 abbreviated "Py3k".
Guido van Rossumf10aa982007-08-17 18:30:38 +0000589
Christian Heimesd8654cf2007-12-02 15:22:16 +0000590 Pythonic
Benjamin Peterson5478b472008-09-17 22:25:09 +0000591 An idea or piece of code which closely follows the most common idioms
592 of the Python language, rather than implementing code using concepts
593 common to other languages. For example, a common idiom in Python is
594 to loop over all elements of an iterable using a :keyword:`for`
595 statement. Many other languages don't have this type of construct, so
596 people unfamiliar with Python sometimes use a numerical counter instead::
Georg Brandl48310cd2009-01-03 21:18:54 +0000597
Christian Heimesd8654cf2007-12-02 15:22:16 +0000598 for i in range(len(food)):
Georg Brandla09ca382007-12-02 18:20:12 +0000599 print(food[i])
Christian Heimesd8654cf2007-12-02 15:22:16 +0000600
601 As opposed to the cleaner, Pythonic method::
602
603 for piece in food:
Georg Brandla09ca382007-12-02 18:20:12 +0000604 print(piece)
Christian Heimesd8654cf2007-12-02 15:22:16 +0000605
Guido van Rossumf10aa982007-08-17 18:30:38 +0000606 reference count
Benjamin Peterson5478b472008-09-17 22:25:09 +0000607 The number of references to an object. When the reference count of an
608 object drops to zero, it is deallocated. Reference counting is
609 generally not visible to Python code, but it is a key element of the
610 :term:`CPython` implementation. The :mod:`sys` module defines a
Georg Brandlede6c2a2010-01-05 10:22:04 +0000611 :func:`~sys.getrefcount` function that programmers can call to return the
Benjamin Peterson5478b472008-09-17 22:25:09 +0000612 reference count for a particular object.
613
Guido van Rossumf10aa982007-08-17 18:30:38 +0000614 __slots__
Georg Brandl85eb8c12007-08-31 16:33:38 +0000615 A declaration inside a class that saves memory by pre-declaring space for
616 instance attributes and eliminating instance dictionaries. Though
617 popular, the technique is somewhat tricky to get right and is best
618 reserved for rare cases where there are large numbers of instances in a
619 memory-critical application.
Georg Brandl48310cd2009-01-03 21:18:54 +0000620
Guido van Rossumf10aa982007-08-17 18:30:38 +0000621 sequence
622 An :term:`iterable` which supports efficient element access using integer
Benjamin Peterson5478b472008-09-17 22:25:09 +0000623 indices via the :meth:`__getitem__` special method and defines a
Andrew Svetlov8cf1cc42012-10-05 13:26:10 +0300624 :meth:`__len__` method that returns the length of the sequence.
Guido van Rossumf10aa982007-08-17 18:30:38 +0000625 Some built-in sequence types are :class:`list`, :class:`str`,
Georg Brandl2ae8ac22009-02-05 10:40:48 +0000626 :class:`tuple`, and :class:`bytes`. Note that :class:`dict` also
Guido van Rossumf10aa982007-08-17 18:30:38 +0000627 supports :meth:`__getitem__` and :meth:`__len__`, but is considered a
628 mapping rather than a sequence because the lookups use arbitrary
629 :term:`immutable` keys rather than integers.
630
Christian Heimesd8654cf2007-12-02 15:22:16 +0000631 slice
Georg Brandlc6fe37b2007-12-03 21:07:25 +0000632 An object usually containing a portion of a :term:`sequence`. A slice is
Christian Heimesd8654cf2007-12-02 15:22:16 +0000633 created using the subscript notation, ``[]`` with colons between numbers
634 when several are given, such as in ``variable_name[1:3:5]``. The bracket
Georg Brandla09ca382007-12-02 18:20:12 +0000635 (subscript) notation uses :class:`slice` objects internally.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000636
Georg Brandlaf265f42008-12-07 15:06:20 +0000637 special method
638 A method that is called implicitly by Python to execute a certain
639 operation on a type, such as addition. Such methods have names starting
640 and ending with double underscores. Special methods are documented in
641 :ref:`specialnames`.
642
Christian Heimesd8654cf2007-12-02 15:22:16 +0000643 statement
644 A statement is part of a suite (a "block" of code). A statement is either
645 an :term:`expression` or a one of several constructs with a keyword, such
Georg Brandla09ca382007-12-02 18:20:12 +0000646 as :keyword:`if`, :keyword:`while` or :keyword:`for`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000647
Benjamin Peterson5478b472008-09-17 22:25:09 +0000648 triple-quoted string
649 A string which is bound by three instances of either a quotation mark
650 (") or an apostrophe ('). While they don't provide any functionality
651 not available with single-quoted strings, they are useful for a number
652 of reasons. They allow you to include unescaped single and double
653 quotes within a string and they can span multiple lines without the
654 use of the continuation character, making them especially useful when
655 writing docstrings.
656
Guido van Rossumf10aa982007-08-17 18:30:38 +0000657 type
658 The type of a Python object determines what kind of object it is; every
659 object has a type. An object's type is accessible as its
660 :attr:`__class__` attribute or can be retrieved with ``type(obj)``.
Benjamin Peterson5478b472008-09-17 22:25:09 +0000661
R David Murray1b00f252012-08-15 10:43:58 -0400662 universal newlines
663 A manner of interpreting text streams in which all of the following are
664 recognized as ending a line: the Unix end-of-line convention ``'\n'``,
665 the Windows convention ``'\r\n'``, and the old Macintosh convention
666 ``'\r'``. See :pep:`278` and :pep:`3116`, as well as
667 :func:`str.splitlines` for an additional use.
668
Benjamin Peterson656aa282008-11-21 23:22:00 +0000669 view
Ezio Melotti619de8f2009-06-25 18:39:31 +0000670 The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and
Benjamin Peterson656aa282008-11-21 23:22:00 +0000671 :meth:`dict.items` are called dictionary views. They are lazy sequences
672 that will see changes in the underlying dictionary. To force the
673 dictionary view to become a full list use ``list(dictview)``. See
674 :ref:`dict-views`.
675
Benjamin Peterson5478b472008-09-17 22:25:09 +0000676 virtual machine
677 A computer defined entirely in software. Python's virtual machine
678 executes the :term:`bytecode` emitted by the bytecode compiler.
Georg Brandl48310cd2009-01-03 21:18:54 +0000679
Guido van Rossumf10aa982007-08-17 18:30:38 +0000680 Zen of Python
681 Listing of Python design principles and philosophies that are helpful in
682 understanding and using the language. The listing can be found by typing
683 "``import this``" at the interactive prompt.