blob: 3641e5c189d1e1720af3256c9d50dbdf0da98982 [file] [log] [blame]
Georg Brandl437e6a32007-08-17 06:27:11 +00001.. _glossary:
2
3********
4Glossary
5********
6
7.. if you add new entries, keep the alphabetical sorting!
8
9.. glossary::
10
11 ``>>>``
Skip Montanarof02c5f32008-09-15 02:03:05 +000012 The default Python prompt of the interactive shell. Often seen for code
13 examples which can be executed interactively in the interpreter.
Georg Brandlc62ef8b2009-01-03 20:55:06 +000014
Georg Brandl437e6a32007-08-17 06:27:11 +000015 ``...``
Skip Montanarof02c5f32008-09-15 02:03:05 +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).
Georg Brandl584265b2007-12-02 14:58:50 +000019
Georg Brandl5a42ca62008-05-20 07:20:12 +000020 2to3
21 A tool that tries to convert Python 2.x code to Python 3.x code by
Georg Brandl09302282010-10-06 09:32:48 +000022 handling most of the incompatibilities which can be detected by parsing the
Georg Brandl5a42ca62008-05-20 07:20:12 +000023 source and traversing the parse tree.
24
25 2to3 is available in the standard library as :mod:`lib2to3`; a standalone
Benjamin Peterson40202212008-07-24 02:45:37 +000026 entry point is provided as :file:`Tools/scripts/2to3`. See
27 :ref:`2to3-reference`.
Georg Brandl5a42ca62008-05-20 07:20:12 +000028
Benjamin Peterson9385b9d2008-07-03 12:57:35 +000029 abstract base class
Éric Araujo8fde9502011-07-29 11:34:17 +020030 Abstract base classes complement :term:`duck-typing` by
Georg Brandld7d4fd72009-07-26 14:37:28 +000031 providing a way to define interfaces when other techniques like
Éric Araujo8fde9502011-07-29 11:34:17 +020032 :func:`hasattr` would be clumsy or subtly wrong (for example with
Éric Araujoe0054c52011-08-19 09:15:47 +020033 :ref:`magic methods <new-style-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 Brandld7d4fd72009-07-26 14:37:28 +000037 data structures (in the :mod:`collections` module), numbers (in the
38 :mod:`numbers` module), and streams (in the :mod:`io` module). You can
Éric Araujo8fde9502011-07-29 11:34:17 +020039 create your own ABCs with the :mod:`abc` module.
Benjamin Petersonaac51b82008-07-01 23:33:06 +000040
Georg Brandl584265b2007-12-02 14:58:50 +000041 argument
Chris Jerdonek8da82682012-11-29 19:03:37 -080042 A value passed to a :term:`function` (or :term:`method`) when calling the
43 function. There are two types of arguments:
Georg Brandl584265b2007-12-02 14:58:50 +000044
Chris Jerdonek8da82682012-11-29 19:03:37 -080045 * :dfn:`keyword argument`: an argument preceded by an identifier (e.g.
46 ``name=``) in a function call or passed as a value in a dictionary
47 preceded by ``**``. For example, ``3`` and ``5`` are both keyword
48 arguments in the following calls to :func:`complex`::
49
50 complex(real=3, imag=5)
51 complex(**{'real': 3, 'imag': 5})
52
53 * :dfn:`positional argument`: an argument that is not a keyword argument.
54 Positional arguments can appear at the beginning of an argument list
55 and/or be passed as elements of an :term:`iterable` preceded by ``*``.
56 For example, ``3`` and ``5`` are both positional arguments in the
57 following calls::
58
59 complex(3, 5)
60 complex(*(3, 5))
61
62 Arguments are assigned to the named local variables in a function body.
63 See the :ref:`calls` section for the rules governing this assignment.
64 Syntactically, any expression can be used to represent an argument; the
65 evaluated value is assigned to the local variable.
66
67 See also the :term:`parameter` glossary entry and the FAQ question on
68 :ref:`the difference between arguments and parameters
69 <faq-argument-vs-parameter>`.
Skip Montanaro9feab312008-09-15 02:19:53 +000070
71 attribute
72 A value associated with an object which is referenced by name using
73 dotted expressions. For example, if an object *o* has an attribute
74 *a* it would be referenced as *o.a*.
Georg Brandlc62ef8b2009-01-03 20:55:06 +000075
Georg Brandl437e6a32007-08-17 06:27:11 +000076 BDFL
77 Benevolent Dictator For Life, a.k.a. `Guido van Rossum
78 <http://www.python.org/~guido/>`_, Python's creator.
Georg Brandlc62ef8b2009-01-03 20:55:06 +000079
Georg Brandl63fa1682007-10-21 10:24:20 +000080 bytecode
81 Python source code is compiled into bytecode, the internal representation
Éric Araujoa8f66dd2011-08-19 01:27:00 +020082 of a Python program in the CPython interpreter. The bytecode is also
83 cached in ``.pyc`` and ``.pyo`` files so that executing the same file is
84 faster the second time (recompilation from source to bytecode can be
85 avoided). This "intermediate language" is said to run on a
86 :term:`virtual machine` that executes the machine code corresponding to
87 each bytecode. Do note that bytecodes are not expected to work between
88 different Python virtual machines, nor to be stable between Python
89 releases.
Skip Montanaro9feab312008-09-15 02:19:53 +000090
Georg Brandl2b4eda42010-07-03 10:25:54 +000091 A list of bytecode instructions can be found in the documentation for
92 :ref:`the dis module <bytecodes>`.
93
Skip Montanaro9feab312008-09-15 02:19:53 +000094 class
95 A template for creating user-defined objects. Class definitions
96 normally contain method definitions which operate on instances of the
97 class.
Georg Brandlc62ef8b2009-01-03 20:55:06 +000098
Georg Brandl437e6a32007-08-17 06:27:11 +000099 classic class
100 Any class which does not inherit from :class:`object`. See
Ezio Melotti510ff542012-05-03 19:21:40 +0300101 :term:`new-style class`. Classic classes have been removed in Python 3.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000102
Georg Brandl437e6a32007-08-17 06:27:11 +0000103 coercion
104 The implicit conversion of an instance of one type to another during an
105 operation which involves two arguments of the same type. For example,
106 ``int(3.15)`` converts the floating point number to the integer ``3``, but
107 in ``3+4.5``, each argument is of a different type (one int, one float),
108 and both must be converted to the same type before they can be added or it
109 will raise a ``TypeError``. Coercion between two operands can be
Georg Brandld7d4fd72009-07-26 14:37:28 +0000110 performed with the ``coerce`` built-in function; thus, ``3+4.5`` is
Georg Brandl437e6a32007-08-17 06:27:11 +0000111 equivalent to calling ``operator.add(*coerce(3, 4.5))`` and results in
112 ``operator.add(3.0, 4.5)``. Without coercion, all arguments of even
113 compatible types would have to be normalized to the same value by the
114 programmer, e.g., ``float(3)+4.5`` rather than just ``3+4.5``.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000115
Georg Brandl437e6a32007-08-17 06:27:11 +0000116 complex number
117 An extension of the familiar real number system in which all numbers are
118 expressed as a sum of a real part and an imaginary part. Imaginary
119 numbers are real multiples of the imaginary unit (the square root of
120 ``-1``), often written ``i`` in mathematics or ``j`` in
Georg Brandld7d4fd72009-07-26 14:37:28 +0000121 engineering. Python has built-in support for complex numbers, which are
Georg Brandl437e6a32007-08-17 06:27:11 +0000122 written with this latter notation; the imaginary part is written with a
123 ``j`` suffix, e.g., ``3+1j``. To get access to complex equivalents of the
124 :mod:`math` module, use :mod:`cmath`. Use of complex numbers is a fairly
125 advanced mathematical feature. If you're not aware of a need for them,
126 it's almost certain you can safely ignore them.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000127
Skip Montanaroffe455c2007-12-08 15:23:31 +0000128 context manager
Skip Montanarof02c5f32008-09-15 02:03:05 +0000129 An object which controls the environment seen in a :keyword:`with`
Skip Montanaroffe455c2007-12-08 15:23:31 +0000130 statement by defining :meth:`__enter__` and :meth:`__exit__` methods.
131 See :pep:`343`.
132
Skip Montanarof02c5f32008-09-15 02:03:05 +0000133 CPython
Antoine Pitrou9f41bb32011-01-06 16:35:14 +0000134 The canonical implementation of the Python programming language, as
135 distributed on `python.org <http://python.org>`_. The term "CPython"
136 is used when necessary to distinguish this implementation from others
137 such as Jython or IronPython.
Skip Montanarof02c5f32008-09-15 02:03:05 +0000138
Georg Brandl584265b2007-12-02 14:58:50 +0000139 decorator
140 A function returning another function, usually applied as a function
141 transformation using the ``@wrapper`` syntax. Common examples for
142 decorators are :func:`classmethod` and :func:`staticmethod`.
143
144 The decorator syntax is merely syntactic sugar, the following two
145 function definitions are semantically equivalent::
146
147 def f(...):
148 ...
149 f = staticmethod(f)
150
151 @staticmethod
152 def f(...):
153 ...
154
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200155 The same concept exists for classes, but is less commonly used there. See
156 the documentation for :ref:`function definitions <function>` and
157 :ref:`class definitions <class>` for more about decorators.
Georg Brandl5066c0c2008-12-05 18:00:06 +0000158
Georg Brandl437e6a32007-08-17 06:27:11 +0000159 descriptor
Skip Montanarof02c5f32008-09-15 02:03:05 +0000160 Any *new-style* object which defines the methods :meth:`__get__`,
Georg Brandl5e52db02007-10-21 10:45:46 +0000161 :meth:`__set__`, or :meth:`__delete__`. When a class attribute is a
Georg Brandl437e6a32007-08-17 06:27:11 +0000162 descriptor, its special binding behavior is triggered upon attribute
Georg Brandl5e52db02007-10-21 10:45:46 +0000163 lookup. Normally, using *a.b* to get, set or delete an attribute looks up
164 the object named *b* in the class dictionary for *a*, but if *b* is a
165 descriptor, the respective descriptor method gets called. Understanding
166 descriptors is a key to a deep understanding of Python because they are
167 the basis for many features including functions, methods, properties,
168 class methods, static methods, and reference to super classes.
169
170 For more information about descriptors' methods, see :ref:`descriptors`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000171
Georg Brandl437e6a32007-08-17 06:27:11 +0000172 dictionary
Senthil Kumaranc768d4c2012-03-12 10:05:04 -0700173 An associative array, where arbitrary keys are mapped to values. The
174 keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
175 Called a hash in Perl.
Georg Brandle64f7382008-07-20 11:50:29 +0000176
177 docstring
Skip Montanarof02c5f32008-09-15 02:03:05 +0000178 A string literal which appears as the first expression in a class,
179 function or module. While ignored when the suite is executed, it is
180 recognized by the compiler and put into the :attr:`__doc__` attribute
181 of the enclosing class, function or module. Since it is available via
182 introspection, it is the canonical place for documentation of the
Georg Brandle64f7382008-07-20 11:50:29 +0000183 object.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000184
185 duck-typing
Georg Brandle85e1ae2010-10-06 09:17:24 +0000186 A programming style which does not look at an object's type to determine
187 if it has the right interface; instead, the method or attribute is simply
188 called or used ("If it looks like a duck and quacks like a duck, it
Georg Brandl437e6a32007-08-17 06:27:11 +0000189 must be a duck.") By emphasizing interfaces rather than specific types,
190 well-designed code improves its flexibility by allowing polymorphic
191 substitution. Duck-typing avoids tests using :func:`type` or
Georg Brandl04eba2c2010-07-11 08:56:18 +0000192 :func:`isinstance`. (Note, however, that duck-typing can be complemented
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200193 with :term:`abstract base classes <abstract base class>`.) Instead, it
194 typically employs :func:`hasattr` tests or :term:`EAFP` programming.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000195
Georg Brandl437e6a32007-08-17 06:27:11 +0000196 EAFP
197 Easier to ask for forgiveness than permission. This common Python coding
198 style assumes the existence of valid keys or attributes and catches
199 exceptions if the assumption proves false. This clean and fast style is
200 characterized by the presence of many :keyword:`try` and :keyword:`except`
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000201 statements. The technique contrasts with the :term:`LBYL` style
Skip Montanarof02c5f32008-09-15 02:03:05 +0000202 common to many other languages such as C.
Georg Brandl437e6a32007-08-17 06:27:11 +0000203
Georg Brandl584265b2007-12-02 14:58:50 +0000204 expression
205 A piece of syntax which can be evaluated to some value. In other words,
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200206 an expression is an accumulation of expression elements like literals,
207 names, attribute access, operators or function calls which all return a
208 value. In contrast to many other languages, not all language constructs
209 are expressions. There are also :term:`statement`\s which cannot be used
210 as expressions, such as :keyword:`print` or :keyword:`if`. Assignments
211 are also statements, not expressions.
Georg Brandl584265b2007-12-02 14:58:50 +0000212
Georg Brandl437e6a32007-08-17 06:27:11 +0000213 extension module
Georg Brandl28dadd92011-02-25 10:50:32 +0000214 A module written in C or C++, using Python's C API to interact with the
215 core and with user code.
Georg Brandl584265b2007-12-02 14:58:50 +0000216
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200217 file object
218 An object exposing a file-oriented API (with methods such as
219 :meth:`read()` or :meth:`write()`) to an underlying resource. Depending
220 on the way it was created, a file object can mediate access to a real
Sandro Tosifd4c4b12012-06-02 23:40:59 +0200221 on-disk file or to another type of storage or communication device
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200222 (for example standard input/output, in-memory buffers, sockets, pipes,
223 etc.). File objects are also called :dfn:`file-like objects` or
224 :dfn:`streams`.
225
226 There are actually three categories of file objects: raw binary files,
227 buffered binary files and text files. Their interfaces are defined in the
228 :mod:`io` module. The canonical way to create a file object is by using
229 the :func:`open` function.
230
231 file-like object
232 A synonym for :term:`file object`.
233
Georg Brandl624f3372009-03-31 16:11:45 +0000234 finder
235 An object that tries to find the :term:`loader` for a module. It must
236 implement a method named :meth:`find_module`. See :pep:`302` for
237 details.
238
Raymond Hettingerf1b678d2010-09-01 22:25:41 +0000239 floor division
240 Mathematical division that rounds down to nearest integer. The floor
241 division operator is ``//``. For example, the expression ``11 // 4``
242 evaluates to ``2`` in contrast to the ``2.75`` returned by float true
243 division. Note that ``(-11) // 4`` is ``-3`` because that is ``-2.75``
244 rounded *downward*. See :pep:`238`.
245
Georg Brandl584265b2007-12-02 14:58:50 +0000246 function
247 A series of statements which returns some value to a caller. It can also
Chris Jerdonekcf4710c2012-12-25 14:50:21 -0800248 be passed zero or more :term:`arguments <argument>` which may be used in
249 the execution of the body. See also :term:`parameter`, :term:`method`,
250 and the :ref:`function` section.
Georg Brandl584265b2007-12-02 14:58:50 +0000251
Georg Brandl437e6a32007-08-17 06:27:11 +0000252 __future__
Raymond Hettingerf1b678d2010-09-01 22:25:41 +0000253 A pseudo-module which programmers can use to enable new language features
Georg Brandl437e6a32007-08-17 06:27:11 +0000254 which are not compatible with the current interpreter. For example, the
255 expression ``11/4`` currently evaluates to ``2``. If the module in which
256 it is executed had enabled *true division* by executing::
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000257
Georg Brandl437e6a32007-08-17 06:27:11 +0000258 from __future__ import division
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000259
Georg Brandl437e6a32007-08-17 06:27:11 +0000260 the expression ``11/4`` would evaluate to ``2.75``. By importing the
261 :mod:`__future__` module and evaluating its variables, you can see when a
262 new feature was first added to the language and when it will become the
263 default::
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000264
Georg Brandl437e6a32007-08-17 06:27:11 +0000265 >>> import __future__
266 >>> __future__.division
267 _Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)
268
269 garbage collection
270 The process of freeing memory when it is not used anymore. Python
271 performs garbage collection via reference counting and a cyclic garbage
272 collector that is able to detect and break reference cycles.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000273
Georg Brandlea2d3892010-04-02 09:11:49 +0000274 .. index:: single: generator
275
Georg Brandl437e6a32007-08-17 06:27:11 +0000276 generator
Skip Montanarof02c5f32008-09-15 02:03:05 +0000277 A function which returns an iterator. It looks like a normal function
Raymond Hettingerf1b678d2010-09-01 22:25:41 +0000278 except that it contains :keyword:`yield` statements for producing a series
279 a values usable in a for-loop or that can be retrieved one at a time with
280 the :func:`next` function. Each :keyword:`yield` temporarily suspends
281 processing, remembering the location execution state (including local
282 variables and pending try-statements). When the generator resumes, it
283 picks-up where it left-off (in contrast to functions which start fresh on
284 every invocation).
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000285
Georg Brandl437e6a32007-08-17 06:27:11 +0000286 .. index:: single: generator expression
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000287
Georg Brandl437e6a32007-08-17 06:27:11 +0000288 generator expression
Georg Brandlea2d3892010-04-02 09:11:49 +0000289 An expression that returns an iterator. It looks like a normal expression
Georg Brandl437e6a32007-08-17 06:27:11 +0000290 followed by a :keyword:`for` expression defining a loop variable, range,
291 and an optional :keyword:`if` expression. The combined expression
292 generates values for an enclosing function::
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000293
Georg Brandl437e6a32007-08-17 06:27:11 +0000294 >>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81
295 285
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000296
Georg Brandl437e6a32007-08-17 06:27:11 +0000297 GIL
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000298 See :term:`global interpreter lock`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000299
Georg Brandl437e6a32007-08-17 06:27:11 +0000300 global interpreter lock
Antoine Pitrou9f41bb32011-01-06 16:35:14 +0000301 The mechanism used by the :term:`CPython` interpreter to assure that
302 only one thread executes Python :term:`bytecode` at a time.
303 This simplifies the CPython implementation by making the object model
304 (including critical built-in types such as :class:`dict`) implicitly
305 safe against concurrent access. Locking the entire interpreter
306 makes it easier for the interpreter to be multi-threaded, at the
307 expense of much of the parallelism afforded by multi-processor
308 machines.
309
310 However, some extension modules, either standard or third-party,
311 are designed so as to release the GIL when doing computationally-intensive
312 tasks such as compression or hashing. Also, the GIL is always released
313 when doing I/O.
314
315 Past efforts to create a "free-threaded" interpreter (one which locks
316 shared data at a much finer granularity) have not been successful
317 because performance suffered in the common single-processor case. It
318 is believed that overcoming this performance issue would make the
319 implementation much more complicated and therefore costlier to maintain.
Georg Brandl7c3e79f2007-11-02 20:06:17 +0000320
321 hashable
Skip Montanarof02c5f32008-09-15 02:03:05 +0000322 An object is *hashable* if it has a hash value which never changes during
Georg Brandl7c3e79f2007-11-02 20:06:17 +0000323 its lifetime (it needs a :meth:`__hash__` method), and can be compared to
324 other objects (it needs an :meth:`__eq__` or :meth:`__cmp__` method).
Skip Montanarof02c5f32008-09-15 02:03:05 +0000325 Hashable objects which compare equal must have the same hash value.
Georg Brandl7c3e79f2007-11-02 20:06:17 +0000326
327 Hashability makes an object usable as a dictionary key and a set member,
328 because these data structures use the hash value internally.
329
Skip Montanarof02c5f32008-09-15 02:03:05 +0000330 All of Python's immutable built-in objects are hashable, while no mutable
331 containers (such as lists or dictionaries) are. Objects which are
Georg Brandl7c3e79f2007-11-02 20:06:17 +0000332 instances of user-defined classes are hashable by default; they all
Ezio Melotti139e4452013-02-01 05:18:44 +0200333 compare unequal (except with themselves), and their hash value is their
334 :func:`id`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000335
Georg Brandl437e6a32007-08-17 06:27:11 +0000336 IDLE
337 An Integrated Development Environment for Python. IDLE is a basic editor
Skip Montanarof02c5f32008-09-15 02:03:05 +0000338 and interpreter environment which ships with the standard distribution of
Raymond Hettingerf1b678d2010-09-01 22:25:41 +0000339 Python.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000340
Georg Brandl437e6a32007-08-17 06:27:11 +0000341 immutable
Skip Montanarof02c5f32008-09-15 02:03:05 +0000342 An object with a fixed value. Immutable objects include numbers, strings and
343 tuples. Such an object cannot be altered. A new object has to
Georg Brandl437e6a32007-08-17 06:27:11 +0000344 be created if a different value has to be stored. They play an important
345 role in places where a constant hash value is needed, for example as a key
346 in a dictionary.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000347
Georg Brandl437e6a32007-08-17 06:27:11 +0000348 integer division
349 Mathematical division discarding any remainder. For example, the
350 expression ``11/4`` currently evaluates to ``2`` in contrast to the
351 ``2.75`` returned by float division. Also called *floor division*.
352 When dividing two integers the outcome will always be another integer
353 (having the floor function applied to it). However, if one of the operands
354 is another numeric type (such as a :class:`float`), the result will be
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000355 coerced (see :term:`coercion`) to a common type. For example, an integer
Georg Brandl437e6a32007-08-17 06:27:11 +0000356 divided by a float will result in a float value, possibly with a decimal
357 fraction. Integer division can be forced by using the ``//`` operator
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000358 instead of the ``/`` operator. See also :term:`__future__`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000359
Georg Brandl624f3372009-03-31 16:11:45 +0000360 importer
361 An object that both finds and loads a module; both a
362 :term:`finder` and :term:`loader` object.
363
Georg Brandl437e6a32007-08-17 06:27:11 +0000364 interactive
Skip Montanarof02c5f32008-09-15 02:03:05 +0000365 Python has an interactive interpreter which means you can enter
366 statements and expressions at the interpreter prompt, immediately
367 execute them and see their results. Just launch ``python`` with no
368 arguments (possibly by selecting it from your computer's main
369 menu). It is a very powerful way to test out new ideas or inspect
370 modules and packages (remember ``help(x)``).
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000371
Georg Brandl437e6a32007-08-17 06:27:11 +0000372 interpreted
Skip Montanarof02c5f32008-09-15 02:03:05 +0000373 Python is an interpreted language, as opposed to a compiled one,
374 though the distinction can be blurry because of the presence of the
375 bytecode compiler. This means that source files can be run directly
376 without explicitly creating an executable which is then run.
377 Interpreted languages typically have a shorter development/debug cycle
378 than compiled ones, though their programs generally also run more
379 slowly. See also :term:`interactive`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000380
Georg Brandl437e6a32007-08-17 06:27:11 +0000381 iterable
Chris Jerdonek717e50e2013-01-04 04:41:34 -0800382 An object capable of returning its members one at a time. Examples of
383 iterables include all sequence types (such as :class:`list`, :class:`str`,
384 and :class:`tuple`) and some non-sequence types like :class:`dict`
385 and :class:`file` and objects of any classes you define
386 with an :meth:`__iter__` or :meth:`__getitem__` method. Iterables can be
387 used in a :keyword:`for` loop and in many other places where a sequence is
388 needed (:func:`zip`, :func:`map`, ...). When an iterable object is passed
389 as an argument to the built-in function :func:`iter`, it returns an
390 iterator for the object. This iterator is good for one pass over the set
391 of values. When using iterables, it is usually not necessary to call
392 :func:`iter` or deal with iterator objects yourself. The ``for``
Georg Brandl437e6a32007-08-17 06:27:11 +0000393 statement does that automatically for you, creating a temporary unnamed
394 variable to hold the iterator for the duration of the loop. See also
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000395 :term:`iterator`, :term:`sequence`, and :term:`generator`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000396
Georg Brandl437e6a32007-08-17 06:27:11 +0000397 iterator
398 An object representing a stream of data. Repeated calls to the iterator's
399 :meth:`next` method return successive items in the stream. When no more
Skip Montanarof02c5f32008-09-15 02:03:05 +0000400 data are available a :exc:`StopIteration` exception is raised instead. At
Georg Brandl437e6a32007-08-17 06:27:11 +0000401 this point, the iterator object is exhausted and any further calls to its
402 :meth:`next` method just raise :exc:`StopIteration` again. Iterators are
403 required to have an :meth:`__iter__` method that returns the iterator
404 object itself so every iterator is also iterable and may be used in most
405 places where other iterables are accepted. One notable exception is code
Skip Montanarof02c5f32008-09-15 02:03:05 +0000406 which attempts multiple iteration passes. A container object (such as a
Georg Brandl437e6a32007-08-17 06:27:11 +0000407 :class:`list`) produces a fresh new iterator each time you pass it to the
408 :func:`iter` function or use it in a :keyword:`for` loop. Attempting this
409 with an iterator will just return the same exhausted iterator object used
410 in the previous iteration pass, making it appear like an empty container.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000411
Georg Brandle7a09902007-10-21 12:10:28 +0000412 More information can be found in :ref:`typeiter`.
413
Georg Brandl3b85b9b2010-11-26 08:20:18 +0000414 key function
415 A key function or collation function is a callable that returns a value
416 used for sorting or ordering. For example, :func:`locale.strxfrm` is
417 used to produce a sort key that is aware of locale specific sort
418 conventions.
419
420 A number of tools in Python accept key functions to control how elements
421 are ordered or grouped. They include :func:`min`, :func:`max`,
422 :func:`sorted`, :meth:`list.sort`, :func:`heapq.nsmallest`,
423 :func:`heapq.nlargest`, and :func:`itertools.groupby`.
424
425 There are several ways to create a key function. For example. the
426 :meth:`str.lower` method can serve as a key function for case insensitive
427 sorts. Alternatively, an ad-hoc key function can be built from a
428 :keyword:`lambda` expression such as ``lambda r: (r[0], r[2])``. Also,
Sandro Tosid987c022012-04-01 01:49:46 +0200429 the :mod:`operator` module provides three key function constructors:
Georg Brandl3b85b9b2010-11-26 08:20:18 +0000430 :func:`~operator.attrgetter`, :func:`~operator.itemgetter`, and
431 :func:`~operator.methodcaller`. See the :ref:`Sorting HOW TO
432 <sortinghowto>` for examples of how to create and use key functions.
433
Georg Brandl584265b2007-12-02 14:58:50 +0000434 keyword argument
Chris Jerdonek8da82682012-11-29 19:03:37 -0800435 See :term:`argument`.
Georg Brandl584265b2007-12-02 14:58:50 +0000436
437 lambda
438 An anonymous inline function consisting of a single :term:`expression`
439 which is evaluated when the function is called. The syntax to create
440 a lambda function is ``lambda [arguments]: expression``
441
Georg Brandl437e6a32007-08-17 06:27:11 +0000442 LBYL
443 Look before you leap. This coding style explicitly tests for
444 pre-conditions before making calls or lookups. This style contrasts with
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000445 the :term:`EAFP` approach and is characterized by the presence of many
Georg Brandl437e6a32007-08-17 06:27:11 +0000446 :keyword:`if` statements.
Skip Montanaro9feab312008-09-15 02:19:53 +0000447
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200448 In a multi-threaded environment, the LBYL approach can risk introducing a
449 race condition between "the looking" and "the leaping". For example, the
450 code, ``if key in mapping: return mapping[key]`` can fail if another
451 thread removes *key* from *mapping* after the test, but before the lookup.
452 This issue can be solved with locks or by using the EAFP approach.
453
Skip Montanaro9feab312008-09-15 02:19:53 +0000454 list
455 A built-in Python :term:`sequence`. Despite its name it is more akin
456 to an array in other languages than to a linked list since access to
457 elements are O(1).
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000458
Georg Brandl437e6a32007-08-17 06:27:11 +0000459 list comprehension
Skip Montanarof02c5f32008-09-15 02:03:05 +0000460 A compact way to process all or part of the elements in a sequence and
Georg Brandl437e6a32007-08-17 06:27:11 +0000461 return a list with the results. ``result = ["0x%02x" % x for x in
Skip Montanarof02c5f32008-09-15 02:03:05 +0000462 range(256) if x % 2 == 0]`` generates a list of strings containing
463 even hex numbers (0x..) in the range from 0 to 255. The :keyword:`if`
464 clause is optional. If omitted, all elements in ``range(256)`` are
465 processed.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000466
Georg Brandl624f3372009-03-31 16:11:45 +0000467 loader
468 An object that loads a module. It must define a method named
469 :meth:`load_module`. A loader is typically returned by a
470 :term:`finder`. See :pep:`302` for details.
471
Georg Brandl437e6a32007-08-17 06:27:11 +0000472 mapping
Raymond Hettingerc4c52dd2011-01-08 23:50:39 +0000473 A container object that supports arbitrary key lookups and implements the
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200474 methods specified in the :class:`~collections.Mapping` or
475 :class:`~collections.MutableMapping`
Éric Araujo8fde9502011-07-29 11:34:17 +0200476 :ref:`abstract base classes <collections-abstract-base-classes>`. Examples
477 include :class:`dict`, :class:`collections.defaultdict`,
Raymond Hettingerc4c52dd2011-01-08 23:50:39 +0000478 :class:`collections.OrderedDict` and :class:`collections.Counter`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000479
Georg Brandl437e6a32007-08-17 06:27:11 +0000480 metaclass
481 The class of a class. Class definitions create a class name, a class
482 dictionary, and a list of base classes. The metaclass is responsible for
483 taking those three arguments and creating the class. Most object oriented
484 programming languages provide a default implementation. What makes Python
485 special is that it is possible to create custom metaclasses. Most users
486 never need this tool, but when the need arises, metaclasses can provide
487 powerful, elegant solutions. They have been used for logging attribute
488 access, adding thread-safety, tracking object creation, implementing
489 singletons, and many other tasks.
Georg Brandla7395032007-10-21 12:15:05 +0000490
491 More information can be found in :ref:`metaclasses`.
Georg Brandl584265b2007-12-02 14:58:50 +0000492
493 method
Skip Montanarof02c5f32008-09-15 02:03:05 +0000494 A function which is defined inside a class body. If called as an attribute
Georg Brandl584265b2007-12-02 14:58:50 +0000495 of an instance of that class, the method will get the instance object as
496 its first :term:`argument` (which is usually called ``self``).
497 See :term:`function` and :term:`nested scope`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000498
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200499 method resolution order
500 Method Resolution Order is the order in which base classes are searched
501 for a member during lookup. See `The Python 2.3 Method Resolution Order
502 <http://www.python.org/download/releases/2.3/mro/>`_.
503
504 MRO
505 See :term:`method resolution order`.
506
Georg Brandl437e6a32007-08-17 06:27:11 +0000507 mutable
508 Mutable objects can change their value but keep their :func:`id`. See
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000509 also :term:`immutable`.
Georg Brandle3c3db52008-01-11 09:55:53 +0000510
511 named tuple
Raymond Hettingeraff711d2009-02-04 19:25:17 +0000512 Any tuple-like class whose indexable elements are also accessible using
Raymond Hettingerc20ed512008-01-13 06:15:15 +0000513 named attributes (for example, :func:`time.localtime` returns a
Raymond Hettinger8bdd0442008-01-13 06:18:07 +0000514 tuple-like object where the *year* is accessible either with an
Raymond Hettingerc20ed512008-01-13 06:15:15 +0000515 index such as ``t[0]`` or with a named attribute like ``t.tm_year``).
516
517 A named tuple can be a built-in type such as :class:`time.struct_time`,
518 or it can be created with a regular class definition. A full featured
519 named tuple can also be created with the factory function
520 :func:`collections.namedtuple`. The latter approach automatically
521 provides extra features such as a self-documenting representation like
522 ``Employee(name='jones', title='programmer')``.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000523
Georg Brandl437e6a32007-08-17 06:27:11 +0000524 namespace
525 The place where a variable is stored. Namespaces are implemented as
Georg Brandld7d4fd72009-07-26 14:37:28 +0000526 dictionaries. There are the local, global and built-in namespaces as well
Georg Brandl437e6a32007-08-17 06:27:11 +0000527 as nested namespaces in objects (in methods). Namespaces support
528 modularity by preventing naming conflicts. For instance, the functions
529 :func:`__builtin__.open` and :func:`os.open` are distinguished by their
530 namespaces. Namespaces also aid readability and maintainability by making
531 it clear which module implements a function. For instance, writing
532 :func:`random.seed` or :func:`itertools.izip` makes it clear that those
533 functions are implemented by the :mod:`random` and :mod:`itertools`
Skip Montanarof02c5f32008-09-15 02:03:05 +0000534 modules, respectively.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000535
Georg Brandl437e6a32007-08-17 06:27:11 +0000536 nested scope
537 The ability to refer to a variable in an enclosing definition. For
538 instance, a function defined inside another function can refer to
Sandro Tosi03c61102012-01-17 18:32:02 +0100539 variables in the outer function. Note that nested scopes work only for
540 reference and not for assignment which will always write to the innermost
541 scope. In contrast, local variables both read and write in the innermost
542 scope. Likewise, global variables read and write to the global namespace.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000543
Georg Brandl437e6a32007-08-17 06:27:11 +0000544 new-style class
Skip Montanarof02c5f32008-09-15 02:03:05 +0000545 Any class which inherits from :class:`object`. This includes all built-in
Georg Brandl437e6a32007-08-17 06:27:11 +0000546 types like :class:`list` and :class:`dict`. Only new-style classes can
547 use Python's newer, versatile features like :attr:`__slots__`,
Skip Montanarof02c5f32008-09-15 02:03:05 +0000548 descriptors, properties, and :meth:`__getattribute__`.
Georg Brandla7395032007-10-21 12:15:05 +0000549
550 More information can be found in :ref:`newstyle`.
Skip Montanaro9feab312008-09-15 02:19:53 +0000551
552 object
553 Any data with state (attributes or value) and defined behavior
554 (methods). Also the ultimate base class of any :term:`new-style
555 class`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000556
Chris Jerdonek8da82682012-11-29 19:03:37 -0800557 parameter
558 A named entity in a :term:`function` (or method) definition that
559 specifies an :term:`argument` (or in some cases, arguments) that the
560 function can accept. There are four types of parameters:
561
562 * :dfn:`positional-or-keyword`: specifies an argument that can be passed
563 either :term:`positionally <argument>` or as a :term:`keyword argument
564 <argument>`. This is the default kind of parameter, for example *foo*
565 and *bar* in the following::
566
567 def func(foo, bar=None): ...
568
569 * :dfn:`positional-only`: specifies an argument that can be supplied only
570 by position. Python has no syntax for defining positional-only
571 parameters. However, some built-in functions have positional-only
572 parameters (e.g. :func:`abs`).
573
574 * :dfn:`var-positional`: specifies that an arbitrary sequence of
575 positional arguments can be provided (in addition to any positional
576 arguments already accepted by other parameters). Such a parameter can
577 be defined by prepending the parameter name with ``*``, for example
578 *args* in the following::
579
580 def func(*args, **kwargs): ...
581
582 * :dfn:`var-keyword`: specifies that arbitrarily many keyword arguments
583 can be provided (in addition to any keyword arguments already accepted
584 by other parameters). Such a parameter can be defined by prepending
585 the parameter name with ``**``, for example *kwargs* in the example
586 above.
587
588 Parameters can specify both optional and required arguments, as well as
589 default values for some optional arguments.
590
591 See also the :term:`argument` glossary entry, the FAQ question on
592 :ref:`the difference between arguments and parameters
593 <faq-argument-vs-parameter>`, and the :ref:`function` section.
594
Georg Brandl584265b2007-12-02 14:58:50 +0000595 positional argument
Chris Jerdonek8da82682012-11-29 19:03:37 -0800596 See :term:`argument`.
Georg Brandl584265b2007-12-02 14:58:50 +0000597
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000598 Python 3000
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200599 Nickname for the Python 3.x release line (coined long ago when the release
600 of version 3 was something in the distant future.) This is also
601 abbreviated "Py3k".
Georg Brandl437e6a32007-08-17 06:27:11 +0000602
Georg Brandl584265b2007-12-02 14:58:50 +0000603 Pythonic
Skip Montanarof02c5f32008-09-15 02:03:05 +0000604 An idea or piece of code which closely follows the most common idioms
605 of the Python language, rather than implementing code using concepts
606 common to other languages. For example, a common idiom in Python is
607 to loop over all elements of an iterable using a :keyword:`for`
608 statement. Many other languages don't have this type of construct, so
609 people unfamiliar with Python sometimes use a numerical counter instead::
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000610
Georg Brandl584265b2007-12-02 14:58:50 +0000611 for i in range(len(food)):
612 print food[i]
613
614 As opposed to the cleaner, Pythonic method::
615
616 for piece in food:
617 print piece
618
Georg Brandl437e6a32007-08-17 06:27:11 +0000619 reference count
Skip Montanarof02c5f32008-09-15 02:03:05 +0000620 The number of references to an object. When the reference count of an
621 object drops to zero, it is deallocated. Reference counting is
622 generally not visible to Python code, but it is a key element of the
623 :term:`CPython` implementation. The :mod:`sys` module defines a
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200624 :func:`~sys.getrefcount` function that programmers can call to return the
Skip Montanarof02c5f32008-09-15 02:03:05 +0000625 reference count for a particular object.
626
Georg Brandl437e6a32007-08-17 06:27:11 +0000627 __slots__
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000628 A declaration inside a :term:`new-style class` that saves memory by
Georg Brandl437e6a32007-08-17 06:27:11 +0000629 pre-declaring space for instance attributes and eliminating instance
630 dictionaries. Though popular, the technique is somewhat tricky to get
631 right and is best reserved for rare cases where there are large numbers of
632 instances in a memory-critical application.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000633
Georg Brandl437e6a32007-08-17 06:27:11 +0000634 sequence
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000635 An :term:`iterable` which supports efficient element access using integer
Skip Montanarof02c5f32008-09-15 02:03:05 +0000636 indices via the :meth:`__getitem__` special method and defines a
637 :meth:`len` method that returns the length of the sequence.
Georg Brandl437e6a32007-08-17 06:27:11 +0000638 Some built-in sequence types are :class:`list`, :class:`str`,
639 :class:`tuple`, and :class:`unicode`. Note that :class:`dict` also
640 supports :meth:`__getitem__` and :meth:`__len__`, but is considered a
641 mapping rather than a sequence because the lookups use arbitrary
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000642 :term:`immutable` keys rather than integers.
Georg Brandl437e6a32007-08-17 06:27:11 +0000643
Georg Brandl584265b2007-12-02 14:58:50 +0000644 slice
Georg Brandl968a3e52007-12-02 18:17:50 +0000645 An object usually containing a portion of a :term:`sequence`. A slice is
Georg Brandl584265b2007-12-02 14:58:50 +0000646 created using the subscript notation, ``[]`` with colons between numbers
647 when several are given, such as in ``variable_name[1:3:5]``. The bracket
648 (subscript) notation uses :class:`slice` objects internally (or in older
649 versions, :meth:`__getslice__` and :meth:`__setslice__`).
650
Georg Brandl9a053732008-12-05 15:29:39 +0000651 special method
652 A method that is called implicitly by Python to execute a certain
653 operation on a type, such as addition. Such methods have names starting
654 and ending with double underscores. Special methods are documented in
655 :ref:`specialnames`.
656
Georg Brandl584265b2007-12-02 14:58:50 +0000657 statement
658 A statement is part of a suite (a "block" of code). A statement is either
659 an :term:`expression` or a one of several constructs with a keyword, such
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200660 as :keyword:`if`, :keyword:`while` or :keyword:`for`.
661
662 struct sequence
663 A tuple with named elements. Struct sequences expose an interface similiar
664 to :term:`named tuple` in that elements can either be accessed either by
665 index or as an attribute. However, they do not have any of the named tuple
666 methods like :meth:`~collections.somenamedtuple._make` or
667 :meth:`~collections.somenamedtuple._asdict`. Examples of struct sequences
668 include :data:`sys.float_info` and the return value of :func:`os.stat`.
Georg Brandl584265b2007-12-02 14:58:50 +0000669
Skip Montanaro9feab312008-09-15 02:19:53 +0000670 triple-quoted string
671 A string which is bound by three instances of either a quotation mark
672 (") or an apostrophe ('). While they don't provide any functionality
673 not available with single-quoted strings, they are useful for a number
674 of reasons. They allow you to include unescaped single and double
675 quotes within a string and they can span multiple lines without the
676 use of the continuation character, making them especially useful when
677 writing docstrings.
678
Georg Brandl437e6a32007-08-17 06:27:11 +0000679 type
680 The type of a Python object determines what kind of object it is; every
681 object has a type. An object's type is accessible as its
682 :attr:`__class__` attribute or can be retrieved with ``type(obj)``.
Skip Montanarof02c5f32008-09-15 02:03:05 +0000683
R David Murray5618aaa2012-08-15 11:15:39 -0400684 universal newlines
685 A manner of interpreting text streams in which all of the following are
686 recognized as ending a line: the Unix end-of-line convention ``'\n'``,
687 the Windows convention ``'\r\n'``, and the old Macintosh convention
688 ``'\r'``. See :pep:`278` and :pep:`3116`, as well as
689 :func:`str.splitlines` for an additional use.
690
Alexandre Vassalotti69eb5162010-01-11 23:17:10 +0000691 view
692 The objects returned from :meth:`dict.viewkeys`, :meth:`dict.viewvalues`,
693 and :meth:`dict.viewitems` are called dictionary views. They are lazy
694 sequences that will see changes in the underlying dictionary. To force
695 the dictionary view to become a full list use ``list(dictview)``. See
696 :ref:`dict-views`.
697
Skip Montanarof02c5f32008-09-15 02:03:05 +0000698 virtual machine
699 A computer defined entirely in software. Python's virtual machine
700 executes the :term:`bytecode` emitted by the bytecode compiler.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000701
Georg Brandl437e6a32007-08-17 06:27:11 +0000702 Zen of Python
703 Listing of Python design principles and philosophies that are helpful in
704 understanding and using the language. The listing can be found by typing
705 "``import this``" at the interactive prompt.