blob: 1100b1f3157af35945ffc02120b0e4cc6c6024bb [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
Ezio Melotti188ad852013-02-01 05:18:44 +0200323 compare unequal (except with themselves), and their hash value is their
324 :func:`id`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000325
Guido van Rossumf10aa982007-08-17 18:30:38 +0000326 IDLE
327 An Integrated Development Environment for Python. IDLE is a basic editor
Benjamin Peterson5478b472008-09-17 22:25:09 +0000328 and interpreter environment which ships with the standard distribution of
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000329 Python.
Georg Brandl48310cd2009-01-03 21:18:54 +0000330
Guido van Rossumf10aa982007-08-17 18:30:38 +0000331 immutable
Benjamin Peterson5478b472008-09-17 22:25:09 +0000332 An object with a fixed value. Immutable objects include numbers, strings and
333 tuples. Such an object cannot be altered. A new object has to
Guido van Rossumf10aa982007-08-17 18:30:38 +0000334 be created if a different value has to be stored. They play an important
335 role in places where a constant hash value is needed, for example as a key
336 in a dictionary.
Benjamin Peterson2d718222008-11-21 00:25:02 +0000337
Brett Cannon51d4aab2009-01-25 04:21:39 +0000338 importer
339 An object that both finds and loads a module; both a
340 :term:`finder` and :term:`loader` object.
341
Guido van Rossumf10aa982007-08-17 18:30:38 +0000342 interactive
Benjamin Peterson5478b472008-09-17 22:25:09 +0000343 Python has an interactive interpreter which means you can enter
344 statements and expressions at the interpreter prompt, immediately
345 execute them and see their results. Just launch ``python`` with no
346 arguments (possibly by selecting it from your computer's main
347 menu). It is a very powerful way to test out new ideas or inspect
348 modules and packages (remember ``help(x)``).
Georg Brandl48310cd2009-01-03 21:18:54 +0000349
Guido van Rossumf10aa982007-08-17 18:30:38 +0000350 interpreted
Benjamin Peterson5478b472008-09-17 22:25:09 +0000351 Python is an interpreted language, as opposed to a compiled one,
352 though the distinction can be blurry because of the presence of the
353 bytecode compiler. This means that source files can be run directly
354 without explicitly creating an executable which is then run.
355 Interpreted languages typically have a shorter development/debug cycle
356 than compiled ones, though their programs generally also run more
357 slowly. See also :term:`interactive`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000358
Guido van Rossumf10aa982007-08-17 18:30:38 +0000359 iterable
Ezio Melottid581fff2013-01-02 22:29:09 +0200360 An object capable of returning its members one at a time. Examples of
361 iterables include all sequence types (such as :class:`list`, :class:`str`,
362 and :class:`tuple`) and some non-sequence types like :class:`dict`,
363 :term:`file objects <file object>`, and objects of any classes you define
364 with an :meth:`__iter__` or :meth:`__getitem__` method. Iterables can be
365 used in a :keyword:`for` loop and in many other places where a sequence is
366 needed (:func:`zip`, :func:`map`, ...). When an iterable object is passed
367 as an argument to the built-in function :func:`iter`, it returns an
368 iterator for the object. This iterator is good for one pass over the set
369 of values. When using iterables, it is usually not necessary to call
370 :func:`iter` or deal with iterator objects yourself. The ``for``
Guido van Rossumf10aa982007-08-17 18:30:38 +0000371 statement does that automatically for you, creating a temporary unnamed
372 variable to hold the iterator for the duration of the loop. See also
373 :term:`iterator`, :term:`sequence`, and :term:`generator`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000374
Guido van Rossumf10aa982007-08-17 18:30:38 +0000375 iterator
376 An object representing a stream of data. Repeated calls to the iterator's
Ezio Melotti7fa82222012-10-12 13:42:08 +0300377 :meth:`~iterator.__next__` method (or passing it to the built-in function
Georg Brandlb30f3302011-01-06 09:23:56 +0000378 :func:`next`) return successive items in the stream. When no more data
379 are available a :exc:`StopIteration` exception is raised instead. At this
Benjamin Petersone7c78b22008-07-03 20:28:26 +0000380 point, the iterator object is exhausted and any further calls to its
Georg Brandlb30f3302011-01-06 09:23:56 +0000381 :meth:`__next__` method just raise :exc:`StopIteration` again. Iterators
382 are required to have an :meth:`__iter__` method that returns the iterator
Guido van Rossumf10aa982007-08-17 18:30:38 +0000383 object itself so every iterator is also iterable and may be used in most
384 places where other iterables are accepted. One notable exception is code
Benjamin Peterson5478b472008-09-17 22:25:09 +0000385 which attempts multiple iteration passes. A container object (such as a
Guido van Rossumf10aa982007-08-17 18:30:38 +0000386 :class:`list`) produces a fresh new iterator each time you pass it to the
387 :func:`iter` function or use it in a :keyword:`for` loop. Attempting this
388 with an iterator will just return the same exhausted iterator object used
389 in the previous iteration pass, making it appear like an empty container.
Georg Brandl48310cd2009-01-03 21:18:54 +0000390
Georg Brandl9afde1c2007-11-01 20:32:30 +0000391 More information can be found in :ref:`typeiter`.
392
Georg Brandlc275e152010-11-05 07:10:41 +0000393 key function
394 A key function or collation function is a callable that returns a value
395 used for sorting or ordering. For example, :func:`locale.strxfrm` is
396 used to produce a sort key that is aware of locale specific sort
397 conventions.
398
399 A number of tools in Python accept key functions to control how elements
400 are ordered or grouped. They include :func:`min`, :func:`max`,
401 :func:`sorted`, :meth:`list.sort`, :func:`heapq.nsmallest`,
402 :func:`heapq.nlargest`, and :func:`itertools.groupby`.
403
404 There are several ways to create a key function. For example. the
405 :meth:`str.lower` method can serve as a key function for case insensitive
406 sorts. Alternatively, an ad-hoc key function can be built from a
407 :keyword:`lambda` expression such as ``lambda r: (r[0], r[2])``. Also,
Sandro Tosi165a2c22012-04-01 01:50:00 +0200408 the :mod:`operator` module provides three key function constructors:
Georg Brandlc275e152010-11-05 07:10:41 +0000409 :func:`~operator.attrgetter`, :func:`~operator.itemgetter`, and
410 :func:`~operator.methodcaller`. See the :ref:`Sorting HOW TO
411 <sortinghowto>` for examples of how to create and use key functions.
412
Christian Heimesd8654cf2007-12-02 15:22:16 +0000413 keyword argument
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -0800414 See :term:`argument`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000415
416 lambda
417 An anonymous inline function consisting of a single :term:`expression`
418 which is evaluated when the function is called. The syntax to create
419 a lambda function is ``lambda [arguments]: expression``
420
Guido van Rossumf10aa982007-08-17 18:30:38 +0000421 LBYL
422 Look before you leap. This coding style explicitly tests for
423 pre-conditions before making calls or lookups. This style contrasts with
424 the :term:`EAFP` approach and is characterized by the presence of many
425 :keyword:`if` statements.
Benjamin Peterson5478b472008-09-17 22:25:09 +0000426
Raymond Hettinger09f44142010-12-17 20:19:50 +0000427 In a multi-threaded environment, the LBYL approach can risk introducing a
428 race condition between "the looking" and "the leaping". For example, the
429 code, ``if key in mapping: return mapping[key]`` can fail if another
430 thread removes *key* from *mapping* after the test, but before the lookup.
431 This issue can be solved with locks or by using the EAFP approach.
432
Benjamin Peterson5478b472008-09-17 22:25:09 +0000433 list
434 A built-in Python :term:`sequence`. Despite its name it is more akin
435 to an array in other languages than to a linked list since access to
436 elements are O(1).
Georg Brandl48310cd2009-01-03 21:18:54 +0000437
Guido van Rossumf10aa982007-08-17 18:30:38 +0000438 list comprehension
Benjamin Peterson5478b472008-09-17 22:25:09 +0000439 A compact way to process all or part of the elements in a sequence and
Georg Brandlede6c2a2010-01-05 10:22:04 +0000440 return a list with the results. ``result = ['{:#04x}'.format(x) for x in
Benjamin Peterson5478b472008-09-17 22:25:09 +0000441 range(256) if x % 2 == 0]`` generates a list of strings containing
442 even hex numbers (0x..) in the range from 0 to 255. The :keyword:`if`
443 clause is optional. If omitted, all elements in ``range(256)`` are
444 processed.
Georg Brandl48310cd2009-01-03 21:18:54 +0000445
Brett Cannon51d4aab2009-01-25 04:21:39 +0000446 loader
447 An object that loads a module. It must define a method named
448 :meth:`load_module`. A loader is typically returned by a
Brett Cannone43b0602009-03-21 03:11:16 +0000449 :term:`finder`. See :pep:`302` for details and
450 :class:`importlib.abc.Loader` for an :term:`abstract base class`.
Brett Cannon51d4aab2009-01-25 04:21:39 +0000451
Guido van Rossumf10aa982007-08-17 18:30:38 +0000452 mapping
Raymond Hettingere3ee66f2011-01-08 23:44:37 +0000453 A container object that supports arbitrary key lookups and implements the
Éric Araujo7c12bae2011-07-26 15:14:35 +0200454 methods specified in the :class:`~collections.Mapping` or
455 :class:`~collections.MutableMapping`
Éric Araujofa088db2011-06-04 18:42:38 +0200456 :ref:`abstract base classes <collections-abstract-base-classes>`. Examples
457 include :class:`dict`, :class:`collections.defaultdict`,
Raymond Hettingere3ee66f2011-01-08 23:44:37 +0000458 :class:`collections.OrderedDict` and :class:`collections.Counter`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000459
Guido van Rossumf10aa982007-08-17 18:30:38 +0000460 metaclass
461 The class of a class. Class definitions create a class name, a class
462 dictionary, and a list of base classes. The metaclass is responsible for
463 taking those three arguments and creating the class. Most object oriented
464 programming languages provide a default implementation. What makes Python
465 special is that it is possible to create custom metaclasses. Most users
466 never need this tool, but when the need arises, metaclasses can provide
467 powerful, elegant solutions. They have been used for logging attribute
468 access, adding thread-safety, tracking object creation, implementing
469 singletons, and many other tasks.
Georg Brandl9afde1c2007-11-01 20:32:30 +0000470
471 More information can be found in :ref:`metaclasses`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000472
473 method
Benjamin Peterson5478b472008-09-17 22:25:09 +0000474 A function which is defined inside a class body. If called as an attribute
Christian Heimesd8654cf2007-12-02 15:22:16 +0000475 of an instance of that class, the method will get the instance object as
476 its first :term:`argument` (which is usually called ``self``).
477 See :term:`function` and :term:`nested scope`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000478
Michael Foord95fc51d2010-11-20 15:07:30 +0000479 method resolution order
480 Method Resolution Order is the order in which base classes are searched
481 for a member during lookup. See `The Python 2.3 Method Resolution Order
482 <http://www.python.org/download/releases/2.3/mro/>`_.
483
484 MRO
485 See :term:`method resolution order`.
486
Guido van Rossumf10aa982007-08-17 18:30:38 +0000487 mutable
488 Mutable objects can change their value but keep their :func:`id`. See
489 also :term:`immutable`.
Christian Heimes25bb7832008-01-11 16:17:00 +0000490
491 named tuple
Raymond Hettingerd04fa312009-02-04 19:45:13 +0000492 Any tuple-like class whose indexable elements are also accessible using
Christian Heimesd32ed6f2008-01-14 18:49:24 +0000493 named attributes (for example, :func:`time.localtime` returns a
494 tuple-like object where the *year* is accessible either with an
495 index such as ``t[0]`` or with a named attribute like ``t.tm_year``).
496
497 A named tuple can be a built-in type such as :class:`time.struct_time`,
498 or it can be created with a regular class definition. A full featured
499 named tuple can also be created with the factory function
500 :func:`collections.namedtuple`. The latter approach automatically
501 provides extra features such as a self-documenting representation like
502 ``Employee(name='jones', title='programmer')``.
Georg Brandl48310cd2009-01-03 21:18:54 +0000503
Guido van Rossumf10aa982007-08-17 18:30:38 +0000504 namespace
505 The place where a variable is stored. Namespaces are implemented as
Georg Brandl22b34312009-07-26 14:54:51 +0000506 dictionaries. There are the local, global and built-in namespaces as well
Guido van Rossumf10aa982007-08-17 18:30:38 +0000507 as nested namespaces in objects (in methods). Namespaces support
508 modularity by preventing naming conflicts. For instance, the functions
Georg Brandl1a3284e2007-12-02 09:40:06 +0000509 :func:`builtins.open` and :func:`os.open` are distinguished by their
Guido van Rossumf10aa982007-08-17 18:30:38 +0000510 namespaces. Namespaces also aid readability and maintainability by making
511 it clear which module implements a function. For instance, writing
Éric Araujo7af8ebb2011-09-01 03:20:13 +0200512 :func:`random.seed` or :func:`itertools.islice` makes it clear that those
Guido van Rossumf10aa982007-08-17 18:30:38 +0000513 functions are implemented by the :mod:`random` and :mod:`itertools`
Benjamin Peterson5478b472008-09-17 22:25:09 +0000514 modules, respectively.
Georg Brandl48310cd2009-01-03 21:18:54 +0000515
Guido van Rossumf10aa982007-08-17 18:30:38 +0000516 nested scope
517 The ability to refer to a variable in an enclosing definition. For
518 instance, a function defined inside another function can refer to
Benjamin Peterson927ccd22010-06-29 18:36:39 +0000519 variables in the outer function. Note that nested scopes by default work
520 only for reference and not for assignment. Local variables both read and
521 write in the innermost scope. Likewise, global variables read and write
522 to the global namespace. The :keyword:`nonlocal` allows writing to outer
523 scopes.
Georg Brandl48310cd2009-01-03 21:18:54 +0000524
Guido van Rossumf10aa982007-08-17 18:30:38 +0000525 new-style class
Georg Brandl85eb8c12007-08-31 16:33:38 +0000526 Old name for the flavor of classes now used for all class objects. In
527 earlier Python versions, only new-style classes could use Python's newer,
528 versatile features like :attr:`__slots__`, descriptors, properties,
529 :meth:`__getattribute__`, class methods, and static methods.
Georg Brandl9afde1c2007-11-01 20:32:30 +0000530
Benjamin Peterson5478b472008-09-17 22:25:09 +0000531 object
532 Any data with state (attributes or value) and defined behavior
533 (methods). Also the ultimate base class of any :term:`new-style
534 class`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000535
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -0800536 parameter
537 A named entity in a :term:`function` (or method) definition that
538 specifies an :term:`argument` (or in some cases, arguments) that the
539 function can accept. There are five types of parameters:
540
541 * :dfn:`positional-or-keyword`: specifies an argument that can be passed
542 either :term:`positionally <argument>` or as a :term:`keyword argument
543 <argument>`. This is the default kind of parameter, for example *foo*
544 and *bar* in the following::
545
546 def func(foo, bar=None): ...
547
548 * :dfn:`positional-only`: specifies an argument that can be supplied only
549 by position. Python has no syntax for defining positional-only
550 parameters. However, some built-in functions have positional-only
551 parameters (e.g. :func:`abs`).
552
553 * :dfn:`keyword-only`: specifies an argument that can be supplied only
554 by keyword. Keyword-only parameters can be defined by including a
555 single var-positional parameter or bare ``*`` in the parameter list
556 of the function definition before them, for example *kw_only1* and
557 *kw_only2* in the following::
558
559 def func(arg, *, kw_only1, kw_only2): ...
560
561 * :dfn:`var-positional`: specifies that an arbitrary sequence of
562 positional arguments can be provided (in addition to any positional
563 arguments already accepted by other parameters). Such a parameter can
564 be defined by prepending the parameter name with ``*``, for example
565 *args* in the following::
566
567 def func(*args, **kwargs): ...
568
569 * :dfn:`var-keyword`: specifies that arbitrarily many keyword arguments
570 can be provided (in addition to any keyword arguments already accepted
571 by other parameters). Such a parameter can be defined by prepending
572 the parameter name with ``**``, for example *kwargs* in the example
573 above.
574
575 Parameters can specify both optional and required arguments, as well as
576 default values for some optional arguments.
577
578 See also the :term:`argument` glossary entry, the FAQ question on
579 :ref:`the difference between arguments and parameters
580 <faq-argument-vs-parameter>`, the :class:`inspect.Parameter` class, the
581 :ref:`function` section, and :pep:`362`.
582
Christian Heimesd8654cf2007-12-02 15:22:16 +0000583 positional argument
Chris Jerdonekc2a7fd62012-11-28 02:29:33 -0800584 See :term:`argument`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000585
Guido van Rossumf10aa982007-08-17 18:30:38 +0000586 Python 3000
Benjamin Peterson1e2f0502008-05-26 12:52:02 +0000587 Nickname for the Python 3.x release line (coined long ago when the release
588 of version 3 was something in the distant future.) This is also
589 abbreviated "Py3k".
Guido van Rossumf10aa982007-08-17 18:30:38 +0000590
Christian Heimesd8654cf2007-12-02 15:22:16 +0000591 Pythonic
Benjamin Peterson5478b472008-09-17 22:25:09 +0000592 An idea or piece of code which closely follows the most common idioms
593 of the Python language, rather than implementing code using concepts
594 common to other languages. For example, a common idiom in Python is
595 to loop over all elements of an iterable using a :keyword:`for`
596 statement. Many other languages don't have this type of construct, so
597 people unfamiliar with Python sometimes use a numerical counter instead::
Georg Brandl48310cd2009-01-03 21:18:54 +0000598
Christian Heimesd8654cf2007-12-02 15:22:16 +0000599 for i in range(len(food)):
Georg Brandla09ca382007-12-02 18:20:12 +0000600 print(food[i])
Christian Heimesd8654cf2007-12-02 15:22:16 +0000601
602 As opposed to the cleaner, Pythonic method::
603
604 for piece in food:
Georg Brandla09ca382007-12-02 18:20:12 +0000605 print(piece)
Christian Heimesd8654cf2007-12-02 15:22:16 +0000606
Guido van Rossumf10aa982007-08-17 18:30:38 +0000607 reference count
Benjamin Peterson5478b472008-09-17 22:25:09 +0000608 The number of references to an object. When the reference count of an
609 object drops to zero, it is deallocated. Reference counting is
610 generally not visible to Python code, but it is a key element of the
611 :term:`CPython` implementation. The :mod:`sys` module defines a
Georg Brandlede6c2a2010-01-05 10:22:04 +0000612 :func:`~sys.getrefcount` function that programmers can call to return the
Benjamin Peterson5478b472008-09-17 22:25:09 +0000613 reference count for a particular object.
614
Guido van Rossumf10aa982007-08-17 18:30:38 +0000615 __slots__
Georg Brandl85eb8c12007-08-31 16:33:38 +0000616 A declaration inside a class that saves memory by pre-declaring space for
617 instance attributes and eliminating instance dictionaries. Though
618 popular, the technique is somewhat tricky to get right and is best
619 reserved for rare cases where there are large numbers of instances in a
620 memory-critical application.
Georg Brandl48310cd2009-01-03 21:18:54 +0000621
Guido van Rossumf10aa982007-08-17 18:30:38 +0000622 sequence
623 An :term:`iterable` which supports efficient element access using integer
Benjamin Peterson5478b472008-09-17 22:25:09 +0000624 indices via the :meth:`__getitem__` special method and defines a
Andrew Svetlov8cf1cc42012-10-05 13:26:10 +0300625 :meth:`__len__` method that returns the length of the sequence.
Guido van Rossumf10aa982007-08-17 18:30:38 +0000626 Some built-in sequence types are :class:`list`, :class:`str`,
Georg Brandl2ae8ac22009-02-05 10:40:48 +0000627 :class:`tuple`, and :class:`bytes`. Note that :class:`dict` also
Guido van Rossumf10aa982007-08-17 18:30:38 +0000628 supports :meth:`__getitem__` and :meth:`__len__`, but is considered a
629 mapping rather than a sequence because the lookups use arbitrary
630 :term:`immutable` keys rather than integers.
631
Christian Heimesd8654cf2007-12-02 15:22:16 +0000632 slice
Georg Brandlc6fe37b2007-12-03 21:07:25 +0000633 An object usually containing a portion of a :term:`sequence`. A slice is
Christian Heimesd8654cf2007-12-02 15:22:16 +0000634 created using the subscript notation, ``[]`` with colons between numbers
635 when several are given, such as in ``variable_name[1:3:5]``. The bracket
Georg Brandla09ca382007-12-02 18:20:12 +0000636 (subscript) notation uses :class:`slice` objects internally.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000637
Georg Brandlaf265f42008-12-07 15:06:20 +0000638 special method
639 A method that is called implicitly by Python to execute a certain
640 operation on a type, such as addition. Such methods have names starting
641 and ending with double underscores. Special methods are documented in
642 :ref:`specialnames`.
643
Christian Heimesd8654cf2007-12-02 15:22:16 +0000644 statement
645 A statement is part of a suite (a "block" of code). A statement is either
646 an :term:`expression` or a one of several constructs with a keyword, such
Georg Brandla09ca382007-12-02 18:20:12 +0000647 as :keyword:`if`, :keyword:`while` or :keyword:`for`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000648
Benjamin Peterson5478b472008-09-17 22:25:09 +0000649 triple-quoted string
650 A string which is bound by three instances of either a quotation mark
651 (") or an apostrophe ('). While they don't provide any functionality
652 not available with single-quoted strings, they are useful for a number
653 of reasons. They allow you to include unescaped single and double
654 quotes within a string and they can span multiple lines without the
655 use of the continuation character, making them especially useful when
656 writing docstrings.
657
Guido van Rossumf10aa982007-08-17 18:30:38 +0000658 type
659 The type of a Python object determines what kind of object it is; every
660 object has a type. An object's type is accessible as its
661 :attr:`__class__` attribute or can be retrieved with ``type(obj)``.
Benjamin Peterson5478b472008-09-17 22:25:09 +0000662
R David Murray1b00f252012-08-15 10:43:58 -0400663 universal newlines
664 A manner of interpreting text streams in which all of the following are
665 recognized as ending a line: the Unix end-of-line convention ``'\n'``,
666 the Windows convention ``'\r\n'``, and the old Macintosh convention
667 ``'\r'``. See :pep:`278` and :pep:`3116`, as well as
668 :func:`str.splitlines` for an additional use.
669
Benjamin Peterson656aa282008-11-21 23:22:00 +0000670 view
Ezio Melotti619de8f2009-06-25 18:39:31 +0000671 The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and
Benjamin Peterson656aa282008-11-21 23:22:00 +0000672 :meth:`dict.items` are called dictionary views. They are lazy sequences
673 that will see changes in the underlying dictionary. To force the
674 dictionary view to become a full list use ``list(dictview)``. See
675 :ref:`dict-views`.
676
Benjamin Peterson5478b472008-09-17 22:25:09 +0000677 virtual machine
678 A computer defined entirely in software. Python's virtual machine
679 executes the :term:`bytecode` emitted by the bytecode compiler.
Georg Brandl48310cd2009-01-03 21:18:54 +0000680
Guido van Rossumf10aa982007-08-17 18:30:38 +0000681 Zen of Python
682 Listing of Python design principles and philosophies that are helpful in
683 understanding and using the language. The listing can be found by typing
684 "``import this``" at the interactive prompt.