blob: d0b1922d109e9165375c325980ec1f821c298733 [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
Skip Montanarof02c5f32008-09-15 02:03:05 +000042 A value passed to a function or method, assigned to a named local
43 variable in the function body. A function or method may have both
44 positional arguments and keyword arguments in its definition.
45 Positional and keyword arguments may be variable-length: ``*`` accepts
46 or passes (if in the function definition or call) several positional
47 arguments in a list, while ``**`` does the same for keyword arguments
48 in a dictionary.
Georg Brandl584265b2007-12-02 14:58:50 +000049
50 Any expression may be used within the argument list, and the evaluated
51 value is passed to the local variable.
Skip Montanaro9feab312008-09-15 02:19:53 +000052
53 attribute
54 A value associated with an object which is referenced by name using
55 dotted expressions. For example, if an object *o* has an attribute
56 *a* it would be referenced as *o.a*.
Georg Brandlc62ef8b2009-01-03 20:55:06 +000057
Georg Brandl437e6a32007-08-17 06:27:11 +000058 BDFL
59 Benevolent Dictator For Life, a.k.a. `Guido van Rossum
60 <http://www.python.org/~guido/>`_, Python's creator.
Georg Brandlc62ef8b2009-01-03 20:55:06 +000061
Georg Brandl63fa1682007-10-21 10:24:20 +000062 bytecode
63 Python source code is compiled into bytecode, the internal representation
Éric Araujoa8f66dd2011-08-19 01:27:00 +020064 of a Python program in the CPython interpreter. The bytecode is also
65 cached in ``.pyc`` and ``.pyo`` files so that executing the same file is
66 faster the second time (recompilation from source to bytecode can be
67 avoided). This "intermediate language" is said to run on a
68 :term:`virtual machine` that executes the machine code corresponding to
69 each bytecode. Do note that bytecodes are not expected to work between
70 different Python virtual machines, nor to be stable between Python
71 releases.
Skip Montanaro9feab312008-09-15 02:19:53 +000072
Georg Brandl2b4eda42010-07-03 10:25:54 +000073 A list of bytecode instructions can be found in the documentation for
74 :ref:`the dis module <bytecodes>`.
75
Skip Montanaro9feab312008-09-15 02:19:53 +000076 class
77 A template for creating user-defined objects. Class definitions
78 normally contain method definitions which operate on instances of the
79 class.
Georg Brandlc62ef8b2009-01-03 20:55:06 +000080
Georg Brandl437e6a32007-08-17 06:27:11 +000081 classic class
82 Any class which does not inherit from :class:`object`. See
Ezio Melotti510ff542012-05-03 19:21:40 +030083 :term:`new-style class`. Classic classes have been removed in Python 3.
Georg Brandlc62ef8b2009-01-03 20:55:06 +000084
Georg Brandl437e6a32007-08-17 06:27:11 +000085 coercion
86 The implicit conversion of an instance of one type to another during an
87 operation which involves two arguments of the same type. For example,
88 ``int(3.15)`` converts the floating point number to the integer ``3``, but
89 in ``3+4.5``, each argument is of a different type (one int, one float),
90 and both must be converted to the same type before they can be added or it
91 will raise a ``TypeError``. Coercion between two operands can be
Georg Brandld7d4fd72009-07-26 14:37:28 +000092 performed with the ``coerce`` built-in function; thus, ``3+4.5`` is
Georg Brandl437e6a32007-08-17 06:27:11 +000093 equivalent to calling ``operator.add(*coerce(3, 4.5))`` and results in
94 ``operator.add(3.0, 4.5)``. Without coercion, all arguments of even
95 compatible types would have to be normalized to the same value by the
96 programmer, e.g., ``float(3)+4.5`` rather than just ``3+4.5``.
Georg Brandlc62ef8b2009-01-03 20:55:06 +000097
Georg Brandl437e6a32007-08-17 06:27:11 +000098 complex number
99 An extension of the familiar real number system in which all numbers are
100 expressed as a sum of a real part and an imaginary part. Imaginary
101 numbers are real multiples of the imaginary unit (the square root of
102 ``-1``), often written ``i`` in mathematics or ``j`` in
Georg Brandld7d4fd72009-07-26 14:37:28 +0000103 engineering. Python has built-in support for complex numbers, which are
Georg Brandl437e6a32007-08-17 06:27:11 +0000104 written with this latter notation; the imaginary part is written with a
105 ``j`` suffix, e.g., ``3+1j``. To get access to complex equivalents of the
106 :mod:`math` module, use :mod:`cmath`. Use of complex numbers is a fairly
107 advanced mathematical feature. If you're not aware of a need for them,
108 it's almost certain you can safely ignore them.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000109
Skip Montanaroffe455c2007-12-08 15:23:31 +0000110 context manager
Skip Montanarof02c5f32008-09-15 02:03:05 +0000111 An object which controls the environment seen in a :keyword:`with`
Skip Montanaroffe455c2007-12-08 15:23:31 +0000112 statement by defining :meth:`__enter__` and :meth:`__exit__` methods.
113 See :pep:`343`.
114
Skip Montanarof02c5f32008-09-15 02:03:05 +0000115 CPython
Antoine Pitrou9f41bb32011-01-06 16:35:14 +0000116 The canonical implementation of the Python programming language, as
117 distributed on `python.org <http://python.org>`_. The term "CPython"
118 is used when necessary to distinguish this implementation from others
119 such as Jython or IronPython.
Skip Montanarof02c5f32008-09-15 02:03:05 +0000120
Georg Brandl584265b2007-12-02 14:58:50 +0000121 decorator
122 A function returning another function, usually applied as a function
123 transformation using the ``@wrapper`` syntax. Common examples for
124 decorators are :func:`classmethod` and :func:`staticmethod`.
125
126 The decorator syntax is merely syntactic sugar, the following two
127 function definitions are semantically equivalent::
128
129 def f(...):
130 ...
131 f = staticmethod(f)
132
133 @staticmethod
134 def f(...):
135 ...
136
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200137 The same concept exists for classes, but is less commonly used there. See
138 the documentation for :ref:`function definitions <function>` and
139 :ref:`class definitions <class>` for more about decorators.
Georg Brandl5066c0c2008-12-05 18:00:06 +0000140
Georg Brandl437e6a32007-08-17 06:27:11 +0000141 descriptor
Skip Montanarof02c5f32008-09-15 02:03:05 +0000142 Any *new-style* object which defines the methods :meth:`__get__`,
Georg Brandl5e52db02007-10-21 10:45:46 +0000143 :meth:`__set__`, or :meth:`__delete__`. When a class attribute is a
Georg Brandl437e6a32007-08-17 06:27:11 +0000144 descriptor, its special binding behavior is triggered upon attribute
Georg Brandl5e52db02007-10-21 10:45:46 +0000145 lookup. Normally, using *a.b* to get, set or delete an attribute looks up
146 the object named *b* in the class dictionary for *a*, but if *b* is a
147 descriptor, the respective descriptor method gets called. Understanding
148 descriptors is a key to a deep understanding of Python because they are
149 the basis for many features including functions, methods, properties,
150 class methods, static methods, and reference to super classes.
151
152 For more information about descriptors' methods, see :ref:`descriptors`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000153
Georg Brandl437e6a32007-08-17 06:27:11 +0000154 dictionary
Senthil Kumaranc768d4c2012-03-12 10:05:04 -0700155 An associative array, where arbitrary keys are mapped to values. The
156 keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
157 Called a hash in Perl.
Georg Brandle64f7382008-07-20 11:50:29 +0000158
159 docstring
Skip Montanarof02c5f32008-09-15 02:03:05 +0000160 A string literal which appears as the first expression in a class,
161 function or module. While ignored when the suite is executed, it is
162 recognized by the compiler and put into the :attr:`__doc__` attribute
163 of the enclosing class, function or module. Since it is available via
164 introspection, it is the canonical place for documentation of the
Georg Brandle64f7382008-07-20 11:50:29 +0000165 object.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000166
167 duck-typing
Georg Brandle85e1ae2010-10-06 09:17:24 +0000168 A programming style which does not look at an object's type to determine
169 if it has the right interface; instead, the method or attribute is simply
170 called or used ("If it looks like a duck and quacks like a duck, it
Georg Brandl437e6a32007-08-17 06:27:11 +0000171 must be a duck.") By emphasizing interfaces rather than specific types,
172 well-designed code improves its flexibility by allowing polymorphic
173 substitution. Duck-typing avoids tests using :func:`type` or
Georg Brandl04eba2c2010-07-11 08:56:18 +0000174 :func:`isinstance`. (Note, however, that duck-typing can be complemented
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200175 with :term:`abstract base classes <abstract base class>`.) Instead, it
176 typically employs :func:`hasattr` tests or :term:`EAFP` programming.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000177
Georg Brandl437e6a32007-08-17 06:27:11 +0000178 EAFP
179 Easier to ask for forgiveness than permission. This common Python coding
180 style assumes the existence of valid keys or attributes and catches
181 exceptions if the assumption proves false. This clean and fast style is
182 characterized by the presence of many :keyword:`try` and :keyword:`except`
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000183 statements. The technique contrasts with the :term:`LBYL` style
Skip Montanarof02c5f32008-09-15 02:03:05 +0000184 common to many other languages such as C.
Georg Brandl437e6a32007-08-17 06:27:11 +0000185
Georg Brandl584265b2007-12-02 14:58:50 +0000186 expression
187 A piece of syntax which can be evaluated to some value. In other words,
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200188 an expression is an accumulation of expression elements like literals,
189 names, attribute access, operators or function calls which all return a
190 value. In contrast to many other languages, not all language constructs
191 are expressions. There are also :term:`statement`\s which cannot be used
192 as expressions, such as :keyword:`print` or :keyword:`if`. Assignments
193 are also statements, not expressions.
Georg Brandl584265b2007-12-02 14:58:50 +0000194
Georg Brandl437e6a32007-08-17 06:27:11 +0000195 extension module
Georg Brandl28dadd92011-02-25 10:50:32 +0000196 A module written in C or C++, using Python's C API to interact with the
197 core and with user code.
Georg Brandl584265b2007-12-02 14:58:50 +0000198
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200199 file object
200 An object exposing a file-oriented API (with methods such as
201 :meth:`read()` or :meth:`write()`) to an underlying resource. Depending
202 on the way it was created, a file object can mediate access to a real
Sandro Tosifd4c4b12012-06-02 23:40:59 +0200203 on-disk file or to another type of storage or communication device
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200204 (for example standard input/output, in-memory buffers, sockets, pipes,
205 etc.). File objects are also called :dfn:`file-like objects` or
206 :dfn:`streams`.
207
208 There are actually three categories of file objects: raw binary files,
209 buffered binary files and text files. Their interfaces are defined in the
210 :mod:`io` module. The canonical way to create a file object is by using
211 the :func:`open` function.
212
213 file-like object
214 A synonym for :term:`file object`.
215
Georg Brandl624f3372009-03-31 16:11:45 +0000216 finder
217 An object that tries to find the :term:`loader` for a module. It must
218 implement a method named :meth:`find_module`. See :pep:`302` for
219 details.
220
Raymond Hettingerf1b678d2010-09-01 22:25:41 +0000221 floor division
222 Mathematical division that rounds down to nearest integer. The floor
223 division operator is ``//``. For example, the expression ``11 // 4``
224 evaluates to ``2`` in contrast to the ``2.75`` returned by float true
225 division. Note that ``(-11) // 4`` is ``-3`` because that is ``-2.75``
226 rounded *downward*. See :pep:`238`.
227
Georg Brandl584265b2007-12-02 14:58:50 +0000228 function
229 A series of statements which returns some value to a caller. It can also
230 be passed zero or more arguments which may be used in the execution of
231 the body. See also :term:`argument` and :term:`method`.
232
Georg Brandl437e6a32007-08-17 06:27:11 +0000233 __future__
Raymond Hettingerf1b678d2010-09-01 22:25:41 +0000234 A pseudo-module which programmers can use to enable new language features
Georg Brandl437e6a32007-08-17 06:27:11 +0000235 which are not compatible with the current interpreter. For example, the
236 expression ``11/4`` currently evaluates to ``2``. If the module in which
237 it is executed had enabled *true division* by executing::
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000238
Georg Brandl437e6a32007-08-17 06:27:11 +0000239 from __future__ import division
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000240
Georg Brandl437e6a32007-08-17 06:27:11 +0000241 the expression ``11/4`` would evaluate to ``2.75``. By importing the
242 :mod:`__future__` module and evaluating its variables, you can see when a
243 new feature was first added to the language and when it will become the
244 default::
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000245
Georg Brandl437e6a32007-08-17 06:27:11 +0000246 >>> import __future__
247 >>> __future__.division
248 _Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)
249
250 garbage collection
251 The process of freeing memory when it is not used anymore. Python
252 performs garbage collection via reference counting and a cyclic garbage
253 collector that is able to detect and break reference cycles.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000254
Georg Brandlea2d3892010-04-02 09:11:49 +0000255 .. index:: single: generator
256
Georg Brandl437e6a32007-08-17 06:27:11 +0000257 generator
Skip Montanarof02c5f32008-09-15 02:03:05 +0000258 A function which returns an iterator. It looks like a normal function
Raymond Hettingerf1b678d2010-09-01 22:25:41 +0000259 except that it contains :keyword:`yield` statements for producing a series
260 a values usable in a for-loop or that can be retrieved one at a time with
261 the :func:`next` function. Each :keyword:`yield` temporarily suspends
262 processing, remembering the location execution state (including local
263 variables and pending try-statements). When the generator resumes, it
264 picks-up where it left-off (in contrast to functions which start fresh on
265 every invocation).
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000266
Georg Brandl437e6a32007-08-17 06:27:11 +0000267 .. index:: single: generator expression
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000268
Georg Brandl437e6a32007-08-17 06:27:11 +0000269 generator expression
Georg Brandlea2d3892010-04-02 09:11:49 +0000270 An expression that returns an iterator. It looks like a normal expression
Georg Brandl437e6a32007-08-17 06:27:11 +0000271 followed by a :keyword:`for` expression defining a loop variable, range,
272 and an optional :keyword:`if` expression. The combined expression
273 generates values for an enclosing function::
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000274
Georg Brandl437e6a32007-08-17 06:27:11 +0000275 >>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81
276 285
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000277
Georg Brandl437e6a32007-08-17 06:27:11 +0000278 GIL
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000279 See :term:`global interpreter lock`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000280
Georg Brandl437e6a32007-08-17 06:27:11 +0000281 global interpreter lock
Antoine Pitrou9f41bb32011-01-06 16:35:14 +0000282 The mechanism used by the :term:`CPython` interpreter to assure that
283 only one thread executes Python :term:`bytecode` at a time.
284 This simplifies the CPython implementation by making the object model
285 (including critical built-in types such as :class:`dict`) implicitly
286 safe against concurrent access. Locking the entire interpreter
287 makes it easier for the interpreter to be multi-threaded, at the
288 expense of much of the parallelism afforded by multi-processor
289 machines.
290
291 However, some extension modules, either standard or third-party,
292 are designed so as to release the GIL when doing computationally-intensive
293 tasks such as compression or hashing. Also, the GIL is always released
294 when doing I/O.
295
296 Past efforts to create a "free-threaded" interpreter (one which locks
297 shared data at a much finer granularity) have not been successful
298 because performance suffered in the common single-processor case. It
299 is believed that overcoming this performance issue would make the
300 implementation much more complicated and therefore costlier to maintain.
Georg Brandl7c3e79f2007-11-02 20:06:17 +0000301
302 hashable
Skip Montanarof02c5f32008-09-15 02:03:05 +0000303 An object is *hashable* if it has a hash value which never changes during
Georg Brandl7c3e79f2007-11-02 20:06:17 +0000304 its lifetime (it needs a :meth:`__hash__` method), and can be compared to
305 other objects (it needs an :meth:`__eq__` or :meth:`__cmp__` method).
Skip Montanarof02c5f32008-09-15 02:03:05 +0000306 Hashable objects which compare equal must have the same hash value.
Georg Brandl7c3e79f2007-11-02 20:06:17 +0000307
308 Hashability makes an object usable as a dictionary key and a set member,
309 because these data structures use the hash value internally.
310
Skip Montanarof02c5f32008-09-15 02:03:05 +0000311 All of Python's immutable built-in objects are hashable, while no mutable
312 containers (such as lists or dictionaries) are. Objects which are
Georg Brandl7c3e79f2007-11-02 20:06:17 +0000313 instances of user-defined classes are hashable by default; they all
314 compare unequal, and their hash value is their :func:`id`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000315
Georg Brandl437e6a32007-08-17 06:27:11 +0000316 IDLE
317 An Integrated Development Environment for Python. IDLE is a basic editor
Skip Montanarof02c5f32008-09-15 02:03:05 +0000318 and interpreter environment which ships with the standard distribution of
Raymond Hettingerf1b678d2010-09-01 22:25:41 +0000319 Python.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000320
Georg Brandl437e6a32007-08-17 06:27:11 +0000321 immutable
Skip Montanarof02c5f32008-09-15 02:03:05 +0000322 An object with a fixed value. Immutable objects include numbers, strings and
323 tuples. Such an object cannot be altered. A new object has to
Georg Brandl437e6a32007-08-17 06:27:11 +0000324 be created if a different value has to be stored. They play an important
325 role in places where a constant hash value is needed, for example as a key
326 in a dictionary.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000327
Georg Brandl437e6a32007-08-17 06:27:11 +0000328 integer division
329 Mathematical division discarding any remainder. For example, the
330 expression ``11/4`` currently evaluates to ``2`` in contrast to the
331 ``2.75`` returned by float division. Also called *floor division*.
332 When dividing two integers the outcome will always be another integer
333 (having the floor function applied to it). However, if one of the operands
334 is another numeric type (such as a :class:`float`), the result will be
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000335 coerced (see :term:`coercion`) to a common type. For example, an integer
Georg Brandl437e6a32007-08-17 06:27:11 +0000336 divided by a float will result in a float value, possibly with a decimal
337 fraction. Integer division can be forced by using the ``//`` operator
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000338 instead of the ``/`` operator. See also :term:`__future__`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000339
Georg Brandl624f3372009-03-31 16:11:45 +0000340 importer
341 An object that both finds and loads a module; both a
342 :term:`finder` and :term:`loader` object.
343
Georg Brandl437e6a32007-08-17 06:27:11 +0000344 interactive
Skip Montanarof02c5f32008-09-15 02:03:05 +0000345 Python has an interactive interpreter which means you can enter
346 statements and expressions at the interpreter prompt, immediately
347 execute them and see their results. Just launch ``python`` with no
348 arguments (possibly by selecting it from your computer's main
349 menu). It is a very powerful way to test out new ideas or inspect
350 modules and packages (remember ``help(x)``).
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000351
Georg Brandl437e6a32007-08-17 06:27:11 +0000352 interpreted
Skip Montanarof02c5f32008-09-15 02:03:05 +0000353 Python is an interpreted language, as opposed to a compiled one,
354 though the distinction can be blurry because of the presence of the
355 bytecode compiler. This means that source files can be run directly
356 without explicitly creating an executable which is then run.
357 Interpreted languages typically have a shorter development/debug cycle
358 than compiled ones, though their programs generally also run more
359 slowly. See also :term:`interactive`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000360
Georg Brandl437e6a32007-08-17 06:27:11 +0000361 iterable
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200362 An object capable of returning its members one at a
Georg Brandl437e6a32007-08-17 06:27:11 +0000363 time. Examples of iterables include all sequence types (such as
364 :class:`list`, :class:`str`, and :class:`tuple`) and some non-sequence
365 types like :class:`dict` and :class:`file` and objects of any classes you
366 define with an :meth:`__iter__` or :meth:`__getitem__` method. Iterables
367 can be used in a :keyword:`for` loop and in many other places where a
368 sequence is needed (:func:`zip`, :func:`map`, ...). When an iterable
Georg Brandld7d4fd72009-07-26 14:37:28 +0000369 object is passed as an argument to the built-in function :func:`iter`, it
Georg Brandl437e6a32007-08-17 06:27:11 +0000370 returns an iterator for the object. This iterator is good for one pass
371 over the set of values. When using iterables, it is usually not necessary
372 to call :func:`iter` or deal with iterator objects yourself. The ``for``
373 statement does that automatically for you, creating a temporary unnamed
374 variable to hold the iterator for the duration of the loop. See also
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000375 :term:`iterator`, :term:`sequence`, and :term:`generator`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000376
Georg Brandl437e6a32007-08-17 06:27:11 +0000377 iterator
378 An object representing a stream of data. Repeated calls to the iterator's
379 :meth:`next` method return successive items in the stream. When no more
Skip Montanarof02c5f32008-09-15 02:03:05 +0000380 data are available a :exc:`StopIteration` exception is raised instead. At
Georg Brandl437e6a32007-08-17 06:27:11 +0000381 this point, the iterator object is exhausted and any further calls to its
382 :meth:`next` method just raise :exc:`StopIteration` again. Iterators are
383 required to have an :meth:`__iter__` method that returns the iterator
384 object itself so every iterator is also iterable and may be used in most
385 places where other iterables are accepted. One notable exception is code
Skip Montanarof02c5f32008-09-15 02:03:05 +0000386 which attempts multiple iteration passes. A container object (such as a
Georg Brandl437e6a32007-08-17 06:27:11 +0000387 :class:`list`) produces a fresh new iterator each time you pass it to the
388 :func:`iter` function or use it in a :keyword:`for` loop. Attempting this
389 with an iterator will just return the same exhausted iterator object used
390 in the previous iteration pass, making it appear like an empty container.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000391
Georg Brandle7a09902007-10-21 12:10:28 +0000392 More information can be found in :ref:`typeiter`.
393
Georg Brandl3b85b9b2010-11-26 08:20:18 +0000394 key function
395 A key function or collation function is a callable that returns a value
396 used for sorting or ordering. For example, :func:`locale.strxfrm` is
397 used to produce a sort key that is aware of locale specific sort
398 conventions.
399
400 A number of tools in Python accept key functions to control how elements
401 are ordered or grouped. They include :func:`min`, :func:`max`,
402 :func:`sorted`, :meth:`list.sort`, :func:`heapq.nsmallest`,
403 :func:`heapq.nlargest`, and :func:`itertools.groupby`.
404
405 There are several ways to create a key function. For example. the
406 :meth:`str.lower` method can serve as a key function for case insensitive
407 sorts. Alternatively, an ad-hoc key function can be built from a
408 :keyword:`lambda` expression such as ``lambda r: (r[0], r[2])``. Also,
Sandro Tosid987c022012-04-01 01:49:46 +0200409 the :mod:`operator` module provides three key function constructors:
Georg Brandl3b85b9b2010-11-26 08:20:18 +0000410 :func:`~operator.attrgetter`, :func:`~operator.itemgetter`, and
411 :func:`~operator.methodcaller`. See the :ref:`Sorting HOW TO
412 <sortinghowto>` for examples of how to create and use key functions.
413
Georg Brandl584265b2007-12-02 14:58:50 +0000414 keyword argument
415 Arguments which are preceded with a ``variable_name=`` in the call.
416 The variable name designates the local name in the function to which the
417 value is assigned. ``**`` is used to accept or pass a dictionary of
418 keyword arguments. See :term:`argument`.
419
420 lambda
421 An anonymous inline function consisting of a single :term:`expression`
422 which is evaluated when the function is called. The syntax to create
423 a lambda function is ``lambda [arguments]: expression``
424
Georg Brandl437e6a32007-08-17 06:27:11 +0000425 LBYL
426 Look before you leap. This coding style explicitly tests for
427 pre-conditions before making calls or lookups. This style contrasts with
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000428 the :term:`EAFP` approach and is characterized by the presence of many
Georg Brandl437e6a32007-08-17 06:27:11 +0000429 :keyword:`if` statements.
Skip Montanaro9feab312008-09-15 02:19:53 +0000430
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200431 In a multi-threaded environment, the LBYL approach can risk introducing a
432 race condition between "the looking" and "the leaping". For example, the
433 code, ``if key in mapping: return mapping[key]`` can fail if another
434 thread removes *key* from *mapping* after the test, but before the lookup.
435 This issue can be solved with locks or by using the EAFP approach.
436
Skip Montanaro9feab312008-09-15 02:19:53 +0000437 list
438 A built-in Python :term:`sequence`. Despite its name it is more akin
439 to an array in other languages than to a linked list since access to
440 elements are O(1).
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000441
Georg Brandl437e6a32007-08-17 06:27:11 +0000442 list comprehension
Skip Montanarof02c5f32008-09-15 02:03:05 +0000443 A compact way to process all or part of the elements in a sequence and
Georg Brandl437e6a32007-08-17 06:27:11 +0000444 return a list with the results. ``result = ["0x%02x" % x for x in
Skip Montanarof02c5f32008-09-15 02:03:05 +0000445 range(256) if x % 2 == 0]`` generates a list of strings containing
446 even hex numbers (0x..) in the range from 0 to 255. The :keyword:`if`
447 clause is optional. If omitted, all elements in ``range(256)`` are
448 processed.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000449
Georg Brandl624f3372009-03-31 16:11:45 +0000450 loader
451 An object that loads a module. It must define a method named
452 :meth:`load_module`. A loader is typically returned by a
453 :term:`finder`. See :pep:`302` for details.
454
Georg Brandl437e6a32007-08-17 06:27:11 +0000455 mapping
Raymond Hettingerc4c52dd2011-01-08 23:50:39 +0000456 A container object that supports arbitrary key lookups and implements the
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200457 methods specified in the :class:`~collections.Mapping` or
458 :class:`~collections.MutableMapping`
Éric Araujo8fde9502011-07-29 11:34:17 +0200459 :ref:`abstract base classes <collections-abstract-base-classes>`. Examples
460 include :class:`dict`, :class:`collections.defaultdict`,
Raymond Hettingerc4c52dd2011-01-08 23:50:39 +0000461 :class:`collections.OrderedDict` and :class:`collections.Counter`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000462
Georg Brandl437e6a32007-08-17 06:27:11 +0000463 metaclass
464 The class of a class. Class definitions create a class name, a class
465 dictionary, and a list of base classes. The metaclass is responsible for
466 taking those three arguments and creating the class. Most object oriented
467 programming languages provide a default implementation. What makes Python
468 special is that it is possible to create custom metaclasses. Most users
469 never need this tool, but when the need arises, metaclasses can provide
470 powerful, elegant solutions. They have been used for logging attribute
471 access, adding thread-safety, tracking object creation, implementing
472 singletons, and many other tasks.
Georg Brandla7395032007-10-21 12:15:05 +0000473
474 More information can be found in :ref:`metaclasses`.
Georg Brandl584265b2007-12-02 14:58:50 +0000475
476 method
Skip Montanarof02c5f32008-09-15 02:03:05 +0000477 A function which is defined inside a class body. If called as an attribute
Georg Brandl584265b2007-12-02 14:58:50 +0000478 of an instance of that class, the method will get the instance object as
479 its first :term:`argument` (which is usually called ``self``).
480 See :term:`function` and :term:`nested scope`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000481
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200482 method resolution order
483 Method Resolution Order is the order in which base classes are searched
484 for a member during lookup. See `The Python 2.3 Method Resolution Order
485 <http://www.python.org/download/releases/2.3/mro/>`_.
486
487 MRO
488 See :term:`method resolution order`.
489
Georg Brandl437e6a32007-08-17 06:27:11 +0000490 mutable
491 Mutable objects can change their value but keep their :func:`id`. See
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000492 also :term:`immutable`.
Georg Brandle3c3db52008-01-11 09:55:53 +0000493
494 named tuple
Raymond Hettingeraff711d2009-02-04 19:25:17 +0000495 Any tuple-like class whose indexable elements are also accessible using
Raymond Hettingerc20ed512008-01-13 06:15:15 +0000496 named attributes (for example, :func:`time.localtime` returns a
Raymond Hettinger8bdd0442008-01-13 06:18:07 +0000497 tuple-like object where the *year* is accessible either with an
Raymond Hettingerc20ed512008-01-13 06:15:15 +0000498 index such as ``t[0]`` or with a named attribute like ``t.tm_year``).
499
500 A named tuple can be a built-in type such as :class:`time.struct_time`,
501 or it can be created with a regular class definition. A full featured
502 named tuple can also be created with the factory function
503 :func:`collections.namedtuple`. The latter approach automatically
504 provides extra features such as a self-documenting representation like
505 ``Employee(name='jones', title='programmer')``.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000506
Georg Brandl437e6a32007-08-17 06:27:11 +0000507 namespace
508 The place where a variable is stored. Namespaces are implemented as
Georg Brandld7d4fd72009-07-26 14:37:28 +0000509 dictionaries. There are the local, global and built-in namespaces as well
Georg Brandl437e6a32007-08-17 06:27:11 +0000510 as nested namespaces in objects (in methods). Namespaces support
511 modularity by preventing naming conflicts. For instance, the functions
512 :func:`__builtin__.open` and :func:`os.open` are distinguished by their
513 namespaces. Namespaces also aid readability and maintainability by making
514 it clear which module implements a function. For instance, writing
515 :func:`random.seed` or :func:`itertools.izip` makes it clear that those
516 functions are implemented by the :mod:`random` and :mod:`itertools`
Skip Montanarof02c5f32008-09-15 02:03:05 +0000517 modules, respectively.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000518
Georg Brandl437e6a32007-08-17 06:27:11 +0000519 nested scope
520 The ability to refer to a variable in an enclosing definition. For
521 instance, a function defined inside another function can refer to
Sandro Tosi03c61102012-01-17 18:32:02 +0100522 variables in the outer function. Note that nested scopes work only for
523 reference and not for assignment which will always write to the innermost
524 scope. In contrast, local variables both read and write in the innermost
525 scope. Likewise, global variables read and write to the global namespace.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000526
Georg Brandl437e6a32007-08-17 06:27:11 +0000527 new-style class
Skip Montanarof02c5f32008-09-15 02:03:05 +0000528 Any class which inherits from :class:`object`. This includes all built-in
Georg Brandl437e6a32007-08-17 06:27:11 +0000529 types like :class:`list` and :class:`dict`. Only new-style classes can
530 use Python's newer, versatile features like :attr:`__slots__`,
Skip Montanarof02c5f32008-09-15 02:03:05 +0000531 descriptors, properties, and :meth:`__getattribute__`.
Georg Brandla7395032007-10-21 12:15:05 +0000532
533 More information can be found in :ref:`newstyle`.
Skip Montanaro9feab312008-09-15 02:19:53 +0000534
535 object
536 Any data with state (attributes or value) and defined behavior
537 (methods). Also the ultimate base class of any :term:`new-style
538 class`.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000539
Georg Brandl584265b2007-12-02 14:58:50 +0000540 positional argument
541 The arguments assigned to local names inside a function or method,
542 determined by the order in which they were given in the call. ``*`` is
543 used to either accept multiple positional arguments (when in the
544 definition), or pass several arguments as a list to a function. See
545 :term:`argument`.
546
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000547 Python 3000
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200548 Nickname for the Python 3.x release line (coined long ago when the release
549 of version 3 was something in the distant future.) This is also
550 abbreviated "Py3k".
Georg Brandl437e6a32007-08-17 06:27:11 +0000551
Georg Brandl584265b2007-12-02 14:58:50 +0000552 Pythonic
Skip Montanarof02c5f32008-09-15 02:03:05 +0000553 An idea or piece of code which closely follows the most common idioms
554 of the Python language, rather than implementing code using concepts
555 common to other languages. For example, a common idiom in Python is
556 to loop over all elements of an iterable using a :keyword:`for`
557 statement. Many other languages don't have this type of construct, so
558 people unfamiliar with Python sometimes use a numerical counter instead::
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000559
Georg Brandl584265b2007-12-02 14:58:50 +0000560 for i in range(len(food)):
561 print food[i]
562
563 As opposed to the cleaner, Pythonic method::
564
565 for piece in food:
566 print piece
567
Georg Brandl437e6a32007-08-17 06:27:11 +0000568 reference count
Skip Montanarof02c5f32008-09-15 02:03:05 +0000569 The number of references to an object. When the reference count of an
570 object drops to zero, it is deallocated. Reference counting is
571 generally not visible to Python code, but it is a key element of the
572 :term:`CPython` implementation. The :mod:`sys` module defines a
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200573 :func:`~sys.getrefcount` function that programmers can call to return the
Skip Montanarof02c5f32008-09-15 02:03:05 +0000574 reference count for a particular object.
575
Georg Brandl437e6a32007-08-17 06:27:11 +0000576 __slots__
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000577 A declaration inside a :term:`new-style class` that saves memory by
Georg Brandl437e6a32007-08-17 06:27:11 +0000578 pre-declaring space for instance attributes and eliminating instance
579 dictionaries. Though popular, the technique is somewhat tricky to get
580 right and is best reserved for rare cases where there are large numbers of
581 instances in a memory-critical application.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000582
Georg Brandl437e6a32007-08-17 06:27:11 +0000583 sequence
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000584 An :term:`iterable` which supports efficient element access using integer
Skip Montanarof02c5f32008-09-15 02:03:05 +0000585 indices via the :meth:`__getitem__` special method and defines a
586 :meth:`len` method that returns the length of the sequence.
Georg Brandl437e6a32007-08-17 06:27:11 +0000587 Some built-in sequence types are :class:`list`, :class:`str`,
588 :class:`tuple`, and :class:`unicode`. Note that :class:`dict` also
589 supports :meth:`__getitem__` and :meth:`__len__`, but is considered a
590 mapping rather than a sequence because the lookups use arbitrary
Georg Brandl6c82b6c2007-08-17 16:54:59 +0000591 :term:`immutable` keys rather than integers.
Georg Brandl437e6a32007-08-17 06:27:11 +0000592
Georg Brandl584265b2007-12-02 14:58:50 +0000593 slice
Georg Brandl968a3e52007-12-02 18:17:50 +0000594 An object usually containing a portion of a :term:`sequence`. A slice is
Georg Brandl584265b2007-12-02 14:58:50 +0000595 created using the subscript notation, ``[]`` with colons between numbers
596 when several are given, such as in ``variable_name[1:3:5]``. The bracket
597 (subscript) notation uses :class:`slice` objects internally (or in older
598 versions, :meth:`__getslice__` and :meth:`__setslice__`).
599
Georg Brandl9a053732008-12-05 15:29:39 +0000600 special method
601 A method that is called implicitly by Python to execute a certain
602 operation on a type, such as addition. Such methods have names starting
603 and ending with double underscores. Special methods are documented in
604 :ref:`specialnames`.
605
Georg Brandl584265b2007-12-02 14:58:50 +0000606 statement
607 A statement is part of a suite (a "block" of code). A statement is either
608 an :term:`expression` or a one of several constructs with a keyword, such
Éric Araujoa8f66dd2011-08-19 01:27:00 +0200609 as :keyword:`if`, :keyword:`while` or :keyword:`for`.
610
611 struct sequence
612 A tuple with named elements. Struct sequences expose an interface similiar
613 to :term:`named tuple` in that elements can either be accessed either by
614 index or as an attribute. However, they do not have any of the named tuple
615 methods like :meth:`~collections.somenamedtuple._make` or
616 :meth:`~collections.somenamedtuple._asdict`. Examples of struct sequences
617 include :data:`sys.float_info` and the return value of :func:`os.stat`.
Georg Brandl584265b2007-12-02 14:58:50 +0000618
Skip Montanaro9feab312008-09-15 02:19:53 +0000619 triple-quoted string
620 A string which is bound by three instances of either a quotation mark
621 (") or an apostrophe ('). While they don't provide any functionality
622 not available with single-quoted strings, they are useful for a number
623 of reasons. They allow you to include unescaped single and double
624 quotes within a string and they can span multiple lines without the
625 use of the continuation character, making them especially useful when
626 writing docstrings.
627
Georg Brandl437e6a32007-08-17 06:27:11 +0000628 type
629 The type of a Python object determines what kind of object it is; every
630 object has a type. An object's type is accessible as its
631 :attr:`__class__` attribute or can be retrieved with ``type(obj)``.
Skip Montanarof02c5f32008-09-15 02:03:05 +0000632
R David Murray5618aaa2012-08-15 11:15:39 -0400633 universal newlines
634 A manner of interpreting text streams in which all of the following are
635 recognized as ending a line: the Unix end-of-line convention ``'\n'``,
636 the Windows convention ``'\r\n'``, and the old Macintosh convention
637 ``'\r'``. See :pep:`278` and :pep:`3116`, as well as
638 :func:`str.splitlines` for an additional use.
639
Alexandre Vassalotti69eb5162010-01-11 23:17:10 +0000640 view
641 The objects returned from :meth:`dict.viewkeys`, :meth:`dict.viewvalues`,
642 and :meth:`dict.viewitems` are called dictionary views. They are lazy
643 sequences that will see changes in the underlying dictionary. To force
644 the dictionary view to become a full list use ``list(dictview)``. See
645 :ref:`dict-views`.
646
Skip Montanarof02c5f32008-09-15 02:03:05 +0000647 virtual machine
648 A computer defined entirely in software. Python's virtual machine
649 executes the :term:`bytecode` emitted by the bytecode compiler.
Georg Brandlc62ef8b2009-01-03 20:55:06 +0000650
Georg Brandl437e6a32007-08-17 06:27:11 +0000651 Zen of Python
652 Listing of Python design principles and philosophies that are helpful in
653 understanding and using the language. The listing can be found by typing
654 "``import this``" at the interactive prompt.