blob: cb647a333bcd72f2d570fb2e10c601bf16773e62 [file] [log] [blame]
Guido van Rossumf10aa982007-08-17 18:30:38 +00001.. _glossary:
2
3********
4Glossary
5********
6
7.. if you add new entries, keep the alphabetical sorting!
8
9.. glossary::
10
11 ``>>>``
Benjamin Peterson5478b472008-09-17 22:25:09 +000012 The default Python prompt of the interactive shell. Often seen for code
13 examples which can be executed interactively in the interpreter.
Georg Brandl48310cd2009-01-03 21:18:54 +000014
Guido van Rossumf10aa982007-08-17 18:30:38 +000015 ``...``
Benjamin Peterson5478b472008-09-17 22:25:09 +000016 The default Python prompt of the interactive shell when entering code for
17 an indented code block or within a pair of matching left and right
18 delimiters (parentheses, square brackets or curly braces).
Christian Heimesd8654cf2007-12-02 15:22:16 +000019
Benjamin Petersond6313712008-07-31 16:23:04 +000020 2to3
21 A tool that tries to convert Python 2.x code to Python 3.x code by
Georg Brandl6faee4e2010-09-21 14:48:28 +000022 handling most of the incompatibilities which can be detected by parsing the
Benjamin Petersond6313712008-07-31 16:23:04 +000023 source and traversing the parse tree.
24
25 2to3 is available in the standard library as :mod:`lib2to3`; a standalone
26 entry point is provided as :file:`Tools/scripts/2to3`. See
27 :ref:`2to3-reference`.
28
Georg Brandl86b2fb92008-07-16 03:43:04 +000029 abstract base class
Éric Araujofa088db2011-06-04 18:42:38 +020030 Abstract base classes complement :term:`duck-typing` by
Georg Brandl22b34312009-07-26 14:54:51 +000031 providing a way to define interfaces when other techniques like
Éric Araujofa088db2011-06-04 18:42:38 +020032 :func:`hasattr` would be clumsy or subtly wrong (for example with
Éric Araujo04ac59a2011-08-19 09:07:46 +020033 :ref:`magic methods <special-lookup>`). ABCs introduce virtual
34 subclasses, which are classes that don't inherit from a class but are
35 still recognized by :func:`isinstance` and :func:`issubclass`; see the
36 :mod:`abc` module documentation. Python comes with many built-in ABCs for
Éric Araujo459b4522011-06-04 21:16:42 +020037 data structures (in the :mod:`collections.abc` module), numbers (in the
Éric Araujofa088db2011-06-04 18:42:38 +020038 :mod:`numbers` module), streams (in the :mod:`io` module), import finders
39 and loaders (in the :mod:`importlib.abc` module). You can create your own
40 ABCs with the :mod:`abc` module.
Benjamin Peterson41181742008-07-02 20:22:54 +000041
Christian Heimesd8654cf2007-12-02 15:22:16 +000042 argument
Benjamin Peterson5478b472008-09-17 22:25:09 +000043 A value passed to a function or method, assigned to a named local
44 variable in the function body. A function or method may have both
45 positional arguments and keyword arguments in its definition.
46 Positional and keyword arguments may be variable-length: ``*`` accepts
47 or passes (if in the function definition or call) several positional
48 arguments in a list, while ``**`` does the same for keyword arguments
49 in a dictionary.
Christian Heimesd8654cf2007-12-02 15:22:16 +000050
51 Any expression may be used within the argument list, and the evaluated
52 value is passed to the local variable.
Benjamin Peterson5478b472008-09-17 22:25:09 +000053
54 attribute
55 A value associated with an object which is referenced by name using
56 dotted expressions. For example, if an object *o* has an attribute
57 *a* it would be referenced as *o.a*.
Georg Brandl48310cd2009-01-03 21:18:54 +000058
Guido van Rossumf10aa982007-08-17 18:30:38 +000059 BDFL
60 Benevolent Dictator For Life, a.k.a. `Guido van Rossum
61 <http://www.python.org/~guido/>`_, Python's creator.
Georg Brandl48310cd2009-01-03 21:18:54 +000062
Georg Brandl9afde1c2007-11-01 20:32:30 +000063 bytecode
64 Python source code is compiled into bytecode, the internal representation
Brett Cannon8315fd12010-07-02 22:03:00 +000065 of a Python program in the CPython interpreter. The bytecode is also
66 cached in ``.pyc`` and ``.pyo`` files so that executing the same file is
67 faster the second time (recompilation from source to bytecode can be
68 avoided). This "intermediate language" is said to run on a
69 :term:`virtual machine` that executes the machine code corresponding to
70 each bytecode. Do note that bytecodes are not expected to work between
71 different Python virtual machines, nor to be stable between Python
72 releases.
Benjamin Peterson5478b472008-09-17 22:25:09 +000073
Georg Brandl2cb72d32010-07-03 10:26:54 +000074 A list of bytecode instructions can be found in the documentation for
75 :ref:`the dis module <bytecodes>`.
76
Benjamin Peterson5478b472008-09-17 22:25:09 +000077 class
78 A template for creating user-defined objects. Class definitions
79 normally contain method definitions which operate on instances of the
80 class.
Georg Brandl48310cd2009-01-03 21:18:54 +000081
Benjamin Peterson5478b472008-09-17 22:25:09 +000082 coercion
83 The implicit conversion of an instance of one type to another during an
84 operation which involves two arguments of the same type. For example,
85 ``int(3.15)`` converts the floating point number to the integer ``3``, but
86 in ``3+4.5``, each argument is of a different type (one int, one float),
87 and both must be converted to the same type before they can be added or it
Benjamin Peterson2d718222008-11-21 00:25:02 +000088 will raise a ``TypeError``. Without coercion, all arguments of even
Benjamin Peterson5478b472008-09-17 22:25:09 +000089 compatible types would have to be normalized to the same value by the
90 programmer, e.g., ``float(3)+4.5`` rather than just ``3+4.5``.
Georg Brandl48310cd2009-01-03 21:18:54 +000091
Guido van Rossumf10aa982007-08-17 18:30:38 +000092 complex number
93 An extension of the familiar real number system in which all numbers are
94 expressed as a sum of a real part and an imaginary part. Imaginary
95 numbers are real multiples of the imaginary unit (the square root of
96 ``-1``), often written ``i`` in mathematics or ``j`` in
Georg Brandl22b34312009-07-26 14:54:51 +000097 engineering. Python has built-in support for complex numbers, which are
Guido van Rossumf10aa982007-08-17 18:30:38 +000098 written with this latter notation; the imaginary part is written with a
99 ``j`` suffix, e.g., ``3+1j``. To get access to complex equivalents of the
100 :mod:`math` module, use :mod:`cmath`. Use of complex numbers is a fairly
101 advanced mathematical feature. If you're not aware of a need for them,
102 it's almost certain you can safely ignore them.
Georg Brandl48310cd2009-01-03 21:18:54 +0000103
Christian Heimes895627f2007-12-08 17:28:33 +0000104 context manager
Benjamin Peterson5478b472008-09-17 22:25:09 +0000105 An object which controls the environment seen in a :keyword:`with`
Christian Heimes895627f2007-12-08 17:28:33 +0000106 statement by defining :meth:`__enter__` and :meth:`__exit__` methods.
107 See :pep:`343`.
108
Benjamin Peterson5478b472008-09-17 22:25:09 +0000109 CPython
Antoine Pitrou00342812011-01-06 16:31:28 +0000110 The canonical implementation of the Python programming language, as
111 distributed on `python.org <http://python.org>`_. The term "CPython"
112 is used when necessary to distinguish this implementation from others
113 such as Jython or IronPython.
Benjamin Peterson5478b472008-09-17 22:25:09 +0000114
Christian Heimesd8654cf2007-12-02 15:22:16 +0000115 decorator
116 A function returning another function, usually applied as a function
117 transformation using the ``@wrapper`` syntax. Common examples for
118 decorators are :func:`classmethod` and :func:`staticmethod`.
119
120 The decorator syntax is merely syntactic sugar, the following two
121 function definitions are semantically equivalent::
122
123 def f(...):
124 ...
125 f = staticmethod(f)
126
127 @staticmethod
128 def f(...):
129 ...
130
Georg Brandlaf265f42008-12-07 15:06:20 +0000131 The same concept exists for classes, but is less commonly used there. See
132 the documentation for :ref:`function definitions <function>` and
133 :ref:`class definitions <class>` for more about decorators.
Georg Brandla09ca382007-12-02 18:20:12 +0000134
Guido van Rossumf10aa982007-08-17 18:30:38 +0000135 descriptor
Benjamin Peterson5478b472008-09-17 22:25:09 +0000136 Any object which defines the methods :meth:`__get__`, :meth:`__set__`, or
Georg Brandl85eb8c12007-08-31 16:33:38 +0000137 :meth:`__delete__`. When a class attribute is a descriptor, its special
Georg Brandl9afde1c2007-11-01 20:32:30 +0000138 binding behavior is triggered upon attribute lookup. Normally, using
139 *a.b* to get, set or delete an attribute looks up the object named *b* in
140 the class dictionary for *a*, but if *b* is a descriptor, the respective
141 descriptor method gets called. Understanding descriptors is a key to a
142 deep understanding of Python because they are the basis for many features
143 including functions, methods, properties, class methods, static methods,
144 and reference to super classes.
145
146 For more information about descriptors' methods, see :ref:`descriptors`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000147
Guido van Rossumf10aa982007-08-17 18:30:38 +0000148 dictionary
Senthil Kumaran6080db72012-03-12 10:05:34 -0700149 An associative array, where arbitrary keys are mapped to values. The
150 keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
151 Called a hash in Perl.
Georg Brandl3dbca812008-07-23 16:10:53 +0000152
153 docstring
Benjamin Peterson5478b472008-09-17 22:25:09 +0000154 A string literal which appears as the first expression in a class,
155 function or module. While ignored when the suite is executed, it is
156 recognized by the compiler and put into the :attr:`__doc__` attribute
157 of the enclosing class, function or module. Since it is available via
158 introspection, it is the canonical place for documentation of the
Georg Brandl3dbca812008-07-23 16:10:53 +0000159 object.
Georg Brandl48310cd2009-01-03 21:18:54 +0000160
161 duck-typing
Georg Brandl73b1c7b2010-07-10 10:39:57 +0000162 A programming style which does not look at an object's type to determine
163 if it has the right interface; instead, the method or attribute is simply
164 called or used ("If it looks like a duck and quacks like a duck, it
Guido van Rossumf10aa982007-08-17 18:30:38 +0000165 must be a duck.") By emphasizing interfaces rather than specific types,
166 well-designed code improves its flexibility by allowing polymorphic
167 substitution. Duck-typing avoids tests using :func:`type` or
Georg Brandl8a1c2542010-07-11 08:36:20 +0000168 :func:`isinstance`. (Note, however, that duck-typing can be complemented
Éric Araujo0519b092011-08-19 00:39:19 +0200169 with :term:`abstract base classes <abstract base class>`.) Instead, it
170 typically employs :func:`hasattr` tests or :term:`EAFP` programming.
Georg Brandl48310cd2009-01-03 21:18:54 +0000171
Guido van Rossumf10aa982007-08-17 18:30:38 +0000172 EAFP
173 Easier to ask for forgiveness than permission. This common Python coding
174 style assumes the existence of valid keys or attributes and catches
175 exceptions if the assumption proves false. This clean and fast style is
176 characterized by the presence of many :keyword:`try` and :keyword:`except`
Georg Brandl48310cd2009-01-03 21:18:54 +0000177 statements. The technique contrasts with the :term:`LBYL` style
Benjamin Peterson5478b472008-09-17 22:25:09 +0000178 common to many other languages such as C.
Guido van Rossumf10aa982007-08-17 18:30:38 +0000179
Christian Heimesd8654cf2007-12-02 15:22:16 +0000180 expression
181 A piece of syntax which can be evaluated to some value. In other words,
Benjamin Peterson5478b472008-09-17 22:25:09 +0000182 an expression is an accumulation of expression elements like literals,
183 names, attribute access, operators or function calls which all return a
184 value. In contrast to many other languages, not all language constructs
185 are expressions. There are also :term:`statement`\s which cannot be used
186 as expressions, such as :keyword:`if`. Assignments are also statements,
187 not expressions.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000188
Guido van Rossumf10aa982007-08-17 18:30:38 +0000189 extension module
Georg Brandl9d9848e2010-12-28 11:48:53 +0000190 A module written in C or C++, using Python's C API to interact with the
191 core and with user code.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000192
Antoine Pitrou0b65b0f2010-09-15 09:58:26 +0000193 file object
194 An object exposing a file-oriented API (with methods such as
Georg Brandl9d9848e2010-12-28 11:48:53 +0000195 :meth:`read()` or :meth:`write()`) to an underlying resource. Depending
196 on the way it was created, a file object can mediate access to a real
Eli Benderskydbaedb82012-03-30 11:02:05 +0300197 on-disk file or to another type of storage or communication device
Georg Brandl9d9848e2010-12-28 11:48:53 +0000198 (for example standard input/output, in-memory buffers, sockets, pipes,
199 etc.). File objects are also called :dfn:`file-like objects` or
200 :dfn:`streams`.
Antoine Pitrou0b65b0f2010-09-15 09:58:26 +0000201
Georg Brandl9d9848e2010-12-28 11:48:53 +0000202 There are actually three categories of file objects: raw binary files,
203 buffered binary files and text files. Their interfaces are defined in the
204 :mod:`io` module. The canonical way to create a file object is by using
205 the :func:`open` function.
Antoine Pitrou0b65b0f2010-09-15 09:58:26 +0000206
207 file-like object
208 A synonym for :term:`file object`.
209
Brett Cannon51d4aab2009-01-25 04:21:39 +0000210 finder
211 An object that tries to find the :term:`loader` for a module. It must
212 implement a method named :meth:`find_module`. See :pep:`302` for
Brett Cannone43b0602009-03-21 03:11:16 +0000213 details and :class:`importlib.abc.Finder` for an
214 :term:`abstract base class`.
Brett Cannon51d4aab2009-01-25 04:21:39 +0000215
Benjamin Peterson2d718222008-11-21 00:25:02 +0000216 floor division
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000217 Mathematical division that rounds down to nearest integer. The floor
218 division operator is ``//``. For example, the expression ``11 // 4``
219 evaluates to ``2`` in contrast to the ``2.75`` returned by float true
220 division. Note that ``(-11) // 4`` is ``-3`` because that is ``-2.75``
221 rounded *downward*. See :pep:`238`.
Benjamin Peterson2d718222008-11-21 00:25:02 +0000222
Christian Heimesd8654cf2007-12-02 15:22:16 +0000223 function
224 A series of statements which returns some value to a caller. It can also
225 be passed zero or more arguments which may be used in the execution of
226 the body. See also :term:`argument` and :term:`method`.
227
Guido van Rossumf10aa982007-08-17 18:30:38 +0000228 __future__
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000229 A pseudo-module which programmers can use to enable new language features
Benjamin Peterson2d718222008-11-21 00:25:02 +0000230 which are not compatible with the current interpreter.
231
232 By importing the :mod:`__future__` module and evaluating its variables,
233 you can see when a new feature was first added to the language and when it
234 becomes the default::
Georg Brandl48310cd2009-01-03 21:18:54 +0000235
Guido van Rossumf10aa982007-08-17 18:30:38 +0000236 >>> import __future__
237 >>> __future__.division
238 _Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)
239
240 garbage collection
241 The process of freeing memory when it is not used anymore. Python
242 performs garbage collection via reference counting and a cyclic garbage
243 collector that is able to detect and break reference cycles.
Georg Brandl48310cd2009-01-03 21:18:54 +0000244
Benjamin Peterson08bf91c2010-04-11 16:12:57 +0000245 .. index:: single: generator
246
Guido van Rossumf10aa982007-08-17 18:30:38 +0000247 generator
Benjamin Peterson5478b472008-09-17 22:25:09 +0000248 A function which returns an iterator. It looks like a normal function
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000249 except that it contains :keyword:`yield` statements for producing a series
250 a values usable in a for-loop or that can be retrieved one at a time with
251 the :func:`next` function. Each :keyword:`yield` temporarily suspends
252 processing, remembering the location execution state (including local
253 variables and pending try-statements). When the generator resumes, it
254 picks-up where it left-off (in contrast to functions which start fresh on
Éric Araujoe0854f92011-05-27 04:36:52 +0200255 every invocation).
Georg Brandl48310cd2009-01-03 21:18:54 +0000256
Guido van Rossumf10aa982007-08-17 18:30:38 +0000257 .. index:: single: generator expression
Georg Brandl48310cd2009-01-03 21:18:54 +0000258
Guido van Rossumf10aa982007-08-17 18:30:38 +0000259 generator expression
Benjamin Peterson08bf91c2010-04-11 16:12:57 +0000260 An expression that returns an iterator. It looks like a normal expression
Guido van Rossumf10aa982007-08-17 18:30:38 +0000261 followed by a :keyword:`for` expression defining a loop variable, range,
262 and an optional :keyword:`if` expression. The combined expression
263 generates values for an enclosing function::
Georg Brandl48310cd2009-01-03 21:18:54 +0000264
Guido van Rossumf10aa982007-08-17 18:30:38 +0000265 >>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81
266 285
Georg Brandl48310cd2009-01-03 21:18:54 +0000267
Guido van Rossumf10aa982007-08-17 18:30:38 +0000268 GIL
269 See :term:`global interpreter lock`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000270
Guido van Rossumf10aa982007-08-17 18:30:38 +0000271 global interpreter lock
Antoine Pitrou00342812011-01-06 16:31:28 +0000272 The mechanism used by the :term:`CPython` interpreter to assure that
273 only one thread executes Python :term:`bytecode` at a time.
274 This simplifies the CPython implementation by making the object model
275 (including critical built-in types such as :class:`dict`) implicitly
276 safe against concurrent access. Locking the entire interpreter
277 makes it easier for the interpreter to be multi-threaded, at the
278 expense of much of the parallelism afforded by multi-processor
279 machines.
280
281 However, some extension modules, either standard or third-party,
282 are designed so as to release the GIL when doing computationally-intensive
283 tasks such as compression or hashing. Also, the GIL is always released
284 when doing I/O.
285
286 Past efforts to create a "free-threaded" interpreter (one which locks
287 shared data at a much finer granularity) have not been successful
288 because performance suffered in the common single-processor case. It
289 is believed that overcoming this performance issue would make the
290 implementation much more complicated and therefore costlier to maintain.
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000291
292 hashable
Benjamin Peterson5478b472008-09-17 22:25:09 +0000293 An object is *hashable* if it has a hash value which never changes during
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000294 its lifetime (it needs a :meth:`__hash__` method), and can be compared to
Georg Brandl05f5ab72008-09-24 09:11:47 +0000295 other objects (it needs an :meth:`__eq__` method). Hashable objects which
296 compare equal must have the same hash value.
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000297
298 Hashability makes an object usable as a dictionary key and a set member,
299 because these data structures use the hash value internally.
300
Benjamin Peterson5478b472008-09-17 22:25:09 +0000301 All of Python's immutable built-in objects are hashable, while no mutable
302 containers (such as lists or dictionaries) are. Objects which are
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000303 instances of user-defined classes are hashable by default; they all
304 compare unequal, and their hash value is their :func:`id`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000305
Guido van Rossumf10aa982007-08-17 18:30:38 +0000306 IDLE
307 An Integrated Development Environment for Python. IDLE is a basic editor
Benjamin Peterson5478b472008-09-17 22:25:09 +0000308 and interpreter environment which ships with the standard distribution of
Raymond Hettingerf37ca3c2010-09-01 22:11:53 +0000309 Python.
Georg Brandl48310cd2009-01-03 21:18:54 +0000310
Guido van Rossumf10aa982007-08-17 18:30:38 +0000311 immutable
Benjamin Peterson5478b472008-09-17 22:25:09 +0000312 An object with a fixed value. Immutable objects include numbers, strings and
313 tuples. Such an object cannot be altered. A new object has to
Guido van Rossumf10aa982007-08-17 18:30:38 +0000314 be created if a different value has to be stored. They play an important
315 role in places where a constant hash value is needed, for example as a key
316 in a dictionary.
Benjamin Peterson2d718222008-11-21 00:25:02 +0000317
Brett Cannon51d4aab2009-01-25 04:21:39 +0000318 importer
319 An object that both finds and loads a module; both a
320 :term:`finder` and :term:`loader` object.
321
Guido van Rossumf10aa982007-08-17 18:30:38 +0000322 interactive
Benjamin Peterson5478b472008-09-17 22:25:09 +0000323 Python has an interactive interpreter which means you can enter
324 statements and expressions at the interpreter prompt, immediately
325 execute them and see their results. Just launch ``python`` with no
326 arguments (possibly by selecting it from your computer's main
327 menu). It is a very powerful way to test out new ideas or inspect
328 modules and packages (remember ``help(x)``).
Georg Brandl48310cd2009-01-03 21:18:54 +0000329
Guido van Rossumf10aa982007-08-17 18:30:38 +0000330 interpreted
Benjamin Peterson5478b472008-09-17 22:25:09 +0000331 Python is an interpreted language, as opposed to a compiled one,
332 though the distinction can be blurry because of the presence of the
333 bytecode compiler. This means that source files can be run directly
334 without explicitly creating an executable which is then run.
335 Interpreted languages typically have a shorter development/debug cycle
336 than compiled ones, though their programs generally also run more
337 slowly. See also :term:`interactive`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000338
Guido van Rossumf10aa982007-08-17 18:30:38 +0000339 iterable
Raymond Hettingerb6b76c22010-11-14 05:27:15 +0000340 An object capable of returning its members one at a
Guido van Rossumf10aa982007-08-17 18:30:38 +0000341 time. Examples of iterables include all sequence types (such as
342 :class:`list`, :class:`str`, and :class:`tuple`) and some non-sequence
343 types like :class:`dict` and :class:`file` and objects of any classes you
344 define with an :meth:`__iter__` or :meth:`__getitem__` method. Iterables
345 can be used in a :keyword:`for` loop and in many other places where a
346 sequence is needed (:func:`zip`, :func:`map`, ...). When an iterable
Georg Brandl22b34312009-07-26 14:54:51 +0000347 object is passed as an argument to the built-in function :func:`iter`, it
Guido van Rossumf10aa982007-08-17 18:30:38 +0000348 returns an iterator for the object. This iterator is good for one pass
349 over the set of values. When using iterables, it is usually not necessary
350 to call :func:`iter` or deal with iterator objects yourself. The ``for``
351 statement does that automatically for you, creating a temporary unnamed
352 variable to hold the iterator for the duration of the loop. See also
353 :term:`iterator`, :term:`sequence`, and :term:`generator`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000354
Guido van Rossumf10aa982007-08-17 18:30:38 +0000355 iterator
356 An object representing a stream of data. Repeated calls to the iterator's
Georg Brandlb30f3302011-01-06 09:23:56 +0000357 :meth:`__next__` method (or passing it to the built-in function
358 :func:`next`) return successive items in the stream. When no more data
359 are available a :exc:`StopIteration` exception is raised instead. At this
Benjamin Petersone7c78b22008-07-03 20:28:26 +0000360 point, the iterator object is exhausted and any further calls to its
Georg Brandlb30f3302011-01-06 09:23:56 +0000361 :meth:`__next__` method just raise :exc:`StopIteration` again. Iterators
362 are required to have an :meth:`__iter__` method that returns the iterator
Guido van Rossumf10aa982007-08-17 18:30:38 +0000363 object itself so every iterator is also iterable and may be used in most
364 places where other iterables are accepted. One notable exception is code
Benjamin Peterson5478b472008-09-17 22:25:09 +0000365 which attempts multiple iteration passes. A container object (such as a
Guido van Rossumf10aa982007-08-17 18:30:38 +0000366 :class:`list`) produces a fresh new iterator each time you pass it to the
367 :func:`iter` function or use it in a :keyword:`for` loop. Attempting this
368 with an iterator will just return the same exhausted iterator object used
369 in the previous iteration pass, making it appear like an empty container.
Georg Brandl48310cd2009-01-03 21:18:54 +0000370
Georg Brandl9afde1c2007-11-01 20:32:30 +0000371 More information can be found in :ref:`typeiter`.
372
Georg Brandlc275e152010-11-05 07:10:41 +0000373 key function
374 A key function or collation function is a callable that returns a value
375 used for sorting or ordering. For example, :func:`locale.strxfrm` is
376 used to produce a sort key that is aware of locale specific sort
377 conventions.
378
379 A number of tools in Python accept key functions to control how elements
380 are ordered or grouped. They include :func:`min`, :func:`max`,
381 :func:`sorted`, :meth:`list.sort`, :func:`heapq.nsmallest`,
382 :func:`heapq.nlargest`, and :func:`itertools.groupby`.
383
384 There are several ways to create a key function. For example. the
385 :meth:`str.lower` method can serve as a key function for case insensitive
386 sorts. Alternatively, an ad-hoc key function can be built from a
387 :keyword:`lambda` expression such as ``lambda r: (r[0], r[2])``. Also,
Sandro Tosi165a2c22012-04-01 01:50:00 +0200388 the :mod:`operator` module provides three key function constructors:
Georg Brandlc275e152010-11-05 07:10:41 +0000389 :func:`~operator.attrgetter`, :func:`~operator.itemgetter`, and
390 :func:`~operator.methodcaller`. See the :ref:`Sorting HOW TO
391 <sortinghowto>` for examples of how to create and use key functions.
392
Christian Heimesd8654cf2007-12-02 15:22:16 +0000393 keyword argument
394 Arguments which are preceded with a ``variable_name=`` in the call.
395 The variable name designates the local name in the function to which the
396 value is assigned. ``**`` is used to accept or pass a dictionary of
397 keyword arguments. See :term:`argument`.
398
399 lambda
400 An anonymous inline function consisting of a single :term:`expression`
401 which is evaluated when the function is called. The syntax to create
402 a lambda function is ``lambda [arguments]: expression``
403
Guido van Rossumf10aa982007-08-17 18:30:38 +0000404 LBYL
405 Look before you leap. This coding style explicitly tests for
406 pre-conditions before making calls or lookups. This style contrasts with
407 the :term:`EAFP` approach and is characterized by the presence of many
408 :keyword:`if` statements.
Benjamin Peterson5478b472008-09-17 22:25:09 +0000409
Raymond Hettinger09f44142010-12-17 20:19:50 +0000410 In a multi-threaded environment, the LBYL approach can risk introducing a
411 race condition between "the looking" and "the leaping". For example, the
412 code, ``if key in mapping: return mapping[key]`` can fail if another
413 thread removes *key* from *mapping* after the test, but before the lookup.
414 This issue can be solved with locks or by using the EAFP approach.
415
Benjamin Peterson5478b472008-09-17 22:25:09 +0000416 list
417 A built-in Python :term:`sequence`. Despite its name it is more akin
418 to an array in other languages than to a linked list since access to
419 elements are O(1).
Georg Brandl48310cd2009-01-03 21:18:54 +0000420
Guido van Rossumf10aa982007-08-17 18:30:38 +0000421 list comprehension
Benjamin Peterson5478b472008-09-17 22:25:09 +0000422 A compact way to process all or part of the elements in a sequence and
Georg Brandlede6c2a2010-01-05 10:22:04 +0000423 return a list with the results. ``result = ['{:#04x}'.format(x) for x in
Benjamin Peterson5478b472008-09-17 22:25:09 +0000424 range(256) if x % 2 == 0]`` generates a list of strings containing
425 even hex numbers (0x..) in the range from 0 to 255. The :keyword:`if`
426 clause is optional. If omitted, all elements in ``range(256)`` are
427 processed.
Georg Brandl48310cd2009-01-03 21:18:54 +0000428
Brett Cannon51d4aab2009-01-25 04:21:39 +0000429 loader
430 An object that loads a module. It must define a method named
431 :meth:`load_module`. A loader is typically returned by a
Brett Cannone43b0602009-03-21 03:11:16 +0000432 :term:`finder`. See :pep:`302` for details and
433 :class:`importlib.abc.Loader` for an :term:`abstract base class`.
Brett Cannon51d4aab2009-01-25 04:21:39 +0000434
Guido van Rossumf10aa982007-08-17 18:30:38 +0000435 mapping
Raymond Hettingere3ee66f2011-01-08 23:44:37 +0000436 A container object that supports arbitrary key lookups and implements the
Éric Araujob8edbdf2011-09-01 05:57:12 +0200437 methods specified in the :class:`~collections.abc.Mapping` or
438 :class:`~collections.abc.MutableMapping`
Éric Araujofa088db2011-06-04 18:42:38 +0200439 :ref:`abstract base classes <collections-abstract-base-classes>`. Examples
440 include :class:`dict`, :class:`collections.defaultdict`,
Raymond Hettingere3ee66f2011-01-08 23:44:37 +0000441 :class:`collections.OrderedDict` and :class:`collections.Counter`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000442
Guido van Rossumf10aa982007-08-17 18:30:38 +0000443 metaclass
444 The class of a class. Class definitions create a class name, a class
445 dictionary, and a list of base classes. The metaclass is responsible for
446 taking those three arguments and creating the class. Most object oriented
447 programming languages provide a default implementation. What makes Python
448 special is that it is possible to create custom metaclasses. Most users
449 never need this tool, but when the need arises, metaclasses can provide
450 powerful, elegant solutions. They have been used for logging attribute
451 access, adding thread-safety, tracking object creation, implementing
452 singletons, and many other tasks.
Georg Brandl9afde1c2007-11-01 20:32:30 +0000453
454 More information can be found in :ref:`metaclasses`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000455
456 method
Benjamin Peterson5478b472008-09-17 22:25:09 +0000457 A function which is defined inside a class body. If called as an attribute
Christian Heimesd8654cf2007-12-02 15:22:16 +0000458 of an instance of that class, the method will get the instance object as
459 its first :term:`argument` (which is usually called ``self``).
460 See :term:`function` and :term:`nested scope`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000461
Michael Foord95fc51d2010-11-20 15:07:30 +0000462 method resolution order
463 Method Resolution Order is the order in which base classes are searched
464 for a member during lookup. See `The Python 2.3 Method Resolution Order
465 <http://www.python.org/download/releases/2.3/mro/>`_.
466
467 MRO
468 See :term:`method resolution order`.
469
Guido van Rossumf10aa982007-08-17 18:30:38 +0000470 mutable
471 Mutable objects can change their value but keep their :func:`id`. See
472 also :term:`immutable`.
Christian Heimes25bb7832008-01-11 16:17:00 +0000473
474 named tuple
Raymond Hettingerd04fa312009-02-04 19:45:13 +0000475 Any tuple-like class whose indexable elements are also accessible using
Christian Heimesd32ed6f2008-01-14 18:49:24 +0000476 named attributes (for example, :func:`time.localtime` returns a
477 tuple-like object where the *year* is accessible either with an
478 index such as ``t[0]`` or with a named attribute like ``t.tm_year``).
479
480 A named tuple can be a built-in type such as :class:`time.struct_time`,
481 or it can be created with a regular class definition. A full featured
482 named tuple can also be created with the factory function
483 :func:`collections.namedtuple`. The latter approach automatically
484 provides extra features such as a self-documenting representation like
485 ``Employee(name='jones', title='programmer')``.
Georg Brandl48310cd2009-01-03 21:18:54 +0000486
Guido van Rossumf10aa982007-08-17 18:30:38 +0000487 namespace
488 The place where a variable is stored. Namespaces are implemented as
Georg Brandl22b34312009-07-26 14:54:51 +0000489 dictionaries. There are the local, global and built-in namespaces as well
Guido van Rossumf10aa982007-08-17 18:30:38 +0000490 as nested namespaces in objects (in methods). Namespaces support
491 modularity by preventing naming conflicts. For instance, the functions
Georg Brandl1a3284e2007-12-02 09:40:06 +0000492 :func:`builtins.open` and :func:`os.open` are distinguished by their
Guido van Rossumf10aa982007-08-17 18:30:38 +0000493 namespaces. Namespaces also aid readability and maintainability by making
494 it clear which module implements a function. For instance, writing
Éric Araujo7af8ebb2011-09-01 03:20:13 +0200495 :func:`random.seed` or :func:`itertools.islice` makes it clear that those
Guido van Rossumf10aa982007-08-17 18:30:38 +0000496 functions are implemented by the :mod:`random` and :mod:`itertools`
Benjamin Peterson5478b472008-09-17 22:25:09 +0000497 modules, respectively.
Georg Brandl48310cd2009-01-03 21:18:54 +0000498
Guido van Rossumf10aa982007-08-17 18:30:38 +0000499 nested scope
500 The ability to refer to a variable in an enclosing definition. For
501 instance, a function defined inside another function can refer to
Benjamin Peterson927ccd22010-06-29 18:36:39 +0000502 variables in the outer function. Note that nested scopes by default work
503 only for reference and not for assignment. Local variables both read and
504 write in the innermost scope. Likewise, global variables read and write
505 to the global namespace. The :keyword:`nonlocal` allows writing to outer
506 scopes.
Georg Brandl48310cd2009-01-03 21:18:54 +0000507
Guido van Rossumf10aa982007-08-17 18:30:38 +0000508 new-style class
Georg Brandl85eb8c12007-08-31 16:33:38 +0000509 Old name for the flavor of classes now used for all class objects. In
510 earlier Python versions, only new-style classes could use Python's newer,
511 versatile features like :attr:`__slots__`, descriptors, properties,
512 :meth:`__getattribute__`, class methods, and static methods.
Georg Brandl9afde1c2007-11-01 20:32:30 +0000513
Benjamin Peterson5478b472008-09-17 22:25:09 +0000514 object
515 Any data with state (attributes or value) and defined behavior
516 (methods). Also the ultimate base class of any :term:`new-style
517 class`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000518
Christian Heimesd8654cf2007-12-02 15:22:16 +0000519 positional argument
520 The arguments assigned to local names inside a function or method,
521 determined by the order in which they were given in the call. ``*`` is
522 used to either accept multiple positional arguments (when in the
523 definition), or pass several arguments as a list to a function. See
524 :term:`argument`.
525
Eli Bendersky6bdb6502012-03-30 10:52:25 +0300526 provisional package
527 A provisional package is one which has been deliberately excluded from the
528 standard library's backwards compatibility guarantees. While major
529 changes to such packages are not expected, as long as they are marked
530 provisional, backwards incompatible changes (up to and including removal
531 of the package) may occur if deemed necessary by core developers. Such
532 changes will not be made gratuitously -- they will occur only if serious
533 flaws are uncovered that were missed prior to the inclusion of the
534 package.
535
536 This process allows the standard library to continue to evolve over time,
537 without locking in problematic design errors for extended periods of time.
538 See :pep:`411` for more details.
539
Guido van Rossumf10aa982007-08-17 18:30:38 +0000540 Python 3000
Benjamin Peterson1e2f0502008-05-26 12:52:02 +0000541 Nickname for the Python 3.x release line (coined long ago when the release
542 of version 3 was something in the distant future.) This is also
543 abbreviated "Py3k".
Guido van Rossumf10aa982007-08-17 18:30:38 +0000544
Christian Heimesd8654cf2007-12-02 15:22:16 +0000545 Pythonic
Benjamin Peterson5478b472008-09-17 22:25:09 +0000546 An idea or piece of code which closely follows the most common idioms
547 of the Python language, rather than implementing code using concepts
548 common to other languages. For example, a common idiom in Python is
549 to loop over all elements of an iterable using a :keyword:`for`
550 statement. Many other languages don't have this type of construct, so
551 people unfamiliar with Python sometimes use a numerical counter instead::
Georg Brandl48310cd2009-01-03 21:18:54 +0000552
Christian Heimesd8654cf2007-12-02 15:22:16 +0000553 for i in range(len(food)):
Georg Brandla09ca382007-12-02 18:20:12 +0000554 print(food[i])
Christian Heimesd8654cf2007-12-02 15:22:16 +0000555
556 As opposed to the cleaner, Pythonic method::
557
558 for piece in food:
Georg Brandla09ca382007-12-02 18:20:12 +0000559 print(piece)
Christian Heimesd8654cf2007-12-02 15:22:16 +0000560
Antoine Pitrou86a36b52011-11-25 18:56:07 +0100561 qualified name
562 A dotted name showing the "path" from a module's global scope to a
563 class, function or method defined in that module, as defined in
564 :pep:`3155`. For top-level functions and classes, the qualified name
565 is the same as the object's name::
566
567 >>> class C:
568 ... class D:
569 ... def meth(self):
570 ... pass
571 ...
572 >>> C.__qualname__
573 'C'
574 >>> C.D.__qualname__
575 'C.D'
576 >>> C.D.meth.__qualname__
577 'C.D.meth'
578
Guido van Rossumf10aa982007-08-17 18:30:38 +0000579 reference count
Benjamin Peterson5478b472008-09-17 22:25:09 +0000580 The number of references to an object. When the reference count of an
581 object drops to zero, it is deallocated. Reference counting is
582 generally not visible to Python code, but it is a key element of the
583 :term:`CPython` implementation. The :mod:`sys` module defines a
Georg Brandlede6c2a2010-01-05 10:22:04 +0000584 :func:`~sys.getrefcount` function that programmers can call to return the
Benjamin Peterson5478b472008-09-17 22:25:09 +0000585 reference count for a particular object.
586
Guido van Rossumf10aa982007-08-17 18:30:38 +0000587 __slots__
Georg Brandl85eb8c12007-08-31 16:33:38 +0000588 A declaration inside a class that saves memory by pre-declaring space for
589 instance attributes and eliminating instance dictionaries. Though
590 popular, the technique is somewhat tricky to get right and is best
591 reserved for rare cases where there are large numbers of instances in a
592 memory-critical application.
Georg Brandl48310cd2009-01-03 21:18:54 +0000593
Guido van Rossumf10aa982007-08-17 18:30:38 +0000594 sequence
595 An :term:`iterable` which supports efficient element access using integer
Benjamin Peterson5478b472008-09-17 22:25:09 +0000596 indices via the :meth:`__getitem__` special method and defines a
597 :meth:`len` method that returns the length of the sequence.
Guido van Rossumf10aa982007-08-17 18:30:38 +0000598 Some built-in sequence types are :class:`list`, :class:`str`,
Georg Brandl2ae8ac22009-02-05 10:40:48 +0000599 :class:`tuple`, and :class:`bytes`. Note that :class:`dict` also
Guido van Rossumf10aa982007-08-17 18:30:38 +0000600 supports :meth:`__getitem__` and :meth:`__len__`, but is considered a
601 mapping rather than a sequence because the lookups use arbitrary
602 :term:`immutable` keys rather than integers.
603
Christian Heimesd8654cf2007-12-02 15:22:16 +0000604 slice
Georg Brandlc6fe37b2007-12-03 21:07:25 +0000605 An object usually containing a portion of a :term:`sequence`. A slice is
Christian Heimesd8654cf2007-12-02 15:22:16 +0000606 created using the subscript notation, ``[]`` with colons between numbers
607 when several are given, such as in ``variable_name[1:3:5]``. The bracket
Georg Brandla09ca382007-12-02 18:20:12 +0000608 (subscript) notation uses :class:`slice` objects internally.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000609
Georg Brandlaf265f42008-12-07 15:06:20 +0000610 special method
611 A method that is called implicitly by Python to execute a certain
612 operation on a type, such as addition. Such methods have names starting
613 and ending with double underscores. Special methods are documented in
614 :ref:`specialnames`.
615
Christian Heimesd8654cf2007-12-02 15:22:16 +0000616 statement
617 A statement is part of a suite (a "block" of code). A statement is either
618 an :term:`expression` or a one of several constructs with a keyword, such
Georg Brandla09ca382007-12-02 18:20:12 +0000619 as :keyword:`if`, :keyword:`while` or :keyword:`for`.
Christian Heimesd8654cf2007-12-02 15:22:16 +0000620
Benjamin Peterson82f614b2011-04-20 18:27:32 -0500621 struct sequence
Florent Xiclunaf8240d62011-11-11 19:58:53 +0100622 A tuple with named elements. Struct sequences expose an interface similar
Benjamin Peterson82f614b2011-04-20 18:27:32 -0500623 to :term:`named tuple` in that elements can either be accessed either by
624 index or as an attribute. However, they do not have any of the named tuple
625 methods like :meth:`~collections.somenamedtuple._make` or
626 :meth:`~collections.somenamedtuple._asdict`. Examples of struct sequences
627 include :data:`sys.float_info` and the return value of :func:`os.stat`.
628
Benjamin Peterson5478b472008-09-17 22:25:09 +0000629 triple-quoted string
630 A string which is bound by three instances of either a quotation mark
631 (") or an apostrophe ('). While they don't provide any functionality
632 not available with single-quoted strings, they are useful for a number
633 of reasons. They allow you to include unescaped single and double
634 quotes within a string and they can span multiple lines without the
635 use of the continuation character, making them especially useful when
636 writing docstrings.
637
Guido van Rossumf10aa982007-08-17 18:30:38 +0000638 type
639 The type of a Python object determines what kind of object it is; every
640 object has a type. An object's type is accessible as its
641 :attr:`__class__` attribute or can be retrieved with ``type(obj)``.
Benjamin Peterson5478b472008-09-17 22:25:09 +0000642
Benjamin Peterson656aa282008-11-21 23:22:00 +0000643 view
Ezio Melotti619de8f2009-06-25 18:39:31 +0000644 The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and
Benjamin Peterson656aa282008-11-21 23:22:00 +0000645 :meth:`dict.items` are called dictionary views. They are lazy sequences
646 that will see changes in the underlying dictionary. To force the
647 dictionary view to become a full list use ``list(dictview)``. See
648 :ref:`dict-views`.
649
Benjamin Peterson5478b472008-09-17 22:25:09 +0000650 virtual machine
651 A computer defined entirely in software. Python's virtual machine
652 executes the :term:`bytecode` emitted by the bytecode compiler.
Georg Brandl48310cd2009-01-03 21:18:54 +0000653
Guido van Rossumf10aa982007-08-17 18:30:38 +0000654 Zen of Python
655 Listing of Python design principles and philosophies that are helpful in
656 understanding and using the language. The listing can be found by typing
657 "``import this``" at the interactive prompt.