| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 1 | .. _glossary: | 
 | 2 |  | 
 | 3 | ******** | 
 | 4 | Glossary | 
 | 5 | ******** | 
 | 6 |  | 
 | 7 | .. if you add new entries, keep the alphabetical sorting! | 
 | 8 |  | 
 | 9 | .. glossary:: | 
 | 10 |  | 
 | 11 |    ``>>>`` | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 12 |       The default Python prompt of the interactive shell.  Often seen for code | 
 | 13 |       examples which can be executed interactively in the interpreter. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 14 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 15 |    ``...`` | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 16 |       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 Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 19 |  | 
| Georg Brandl | 5a42ca6 | 2008-05-20 07:20:12 +0000 | [diff] [blame] | 20 |    2to3 | 
 | 21 |       A tool that tries to convert Python 2.x code to Python 3.x code by | 
| Georg Brandl | 0930228 | 2010-10-06 09:32:48 +0000 | [diff] [blame] | 22 |       handling most of the incompatibilities which can be detected by parsing the | 
| Georg Brandl | 5a42ca6 | 2008-05-20 07:20:12 +0000 | [diff] [blame] | 23 |       source and traversing the parse tree. | 
 | 24 |  | 
 | 25 |       2to3 is available in the standard library as :mod:`lib2to3`; a standalone | 
| Benjamin Peterson | 4020221 | 2008-07-24 02:45:37 +0000 | [diff] [blame] | 26 |       entry point is provided as :file:`Tools/scripts/2to3`.  See | 
 | 27 |       :ref:`2to3-reference`. | 
| Georg Brandl | 5a42ca6 | 2008-05-20 07:20:12 +0000 | [diff] [blame] | 28 |  | 
| Benjamin Peterson | 9385b9d | 2008-07-03 12:57:35 +0000 | [diff] [blame] | 29 |    abstract base class | 
| Éric Araujo | 8fde950 | 2011-07-29 11:34:17 +0200 | [diff] [blame] | 30 |       Abstract base classes complement :term:`duck-typing` by | 
| Georg Brandl | d7d4fd7 | 2009-07-26 14:37:28 +0000 | [diff] [blame] | 31 |       providing a way to define interfaces when other techniques like | 
| Éric Araujo | 8fde950 | 2011-07-29 11:34:17 +0200 | [diff] [blame] | 32 |       :func:`hasattr` would be clumsy or subtly wrong (for example with | 
| Éric Araujo | e0054c5 | 2011-08-19 09:15:47 +0200 | [diff] [blame] | 33 |       :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 Brandl | d7d4fd7 | 2009-07-26 14:37:28 +0000 | [diff] [blame] | 37 |       data structures (in the :mod:`collections` module), numbers (in the | 
 | 38 |       :mod:`numbers` module), and streams (in the :mod:`io` module). You can | 
| Éric Araujo | 8fde950 | 2011-07-29 11:34:17 +0200 | [diff] [blame] | 39 |       create your own ABCs with the :mod:`abc` module. | 
| Benjamin Peterson | aac51b8 | 2008-07-01 23:33:06 +0000 | [diff] [blame] | 40 |  | 
| Georg Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 41 |    argument | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 42 |       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 Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 49 |  | 
 | 50 |       Any expression may be used within the argument list, and the evaluated | 
 | 51 |       value is passed to the local variable. | 
| Skip Montanaro | 9feab31 | 2008-09-15 02:19:53 +0000 | [diff] [blame] | 52 |  | 
 | 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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 57 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 58 |    BDFL | 
 | 59 |       Benevolent Dictator For Life, a.k.a. `Guido van Rossum | 
 | 60 |       <http://www.python.org/~guido/>`_, Python's creator. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 61 |  | 
| Georg Brandl | 63fa168 | 2007-10-21 10:24:20 +0000 | [diff] [blame] | 62 |    bytecode | 
 | 63 |       Python source code is compiled into bytecode, the internal representation | 
| Éric Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 64 |       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 Montanaro | 9feab31 | 2008-09-15 02:19:53 +0000 | [diff] [blame] | 72 |  | 
| Georg Brandl | 2b4eda4 | 2010-07-03 10:25:54 +0000 | [diff] [blame] | 73 |       A list of bytecode instructions can be found in the documentation for | 
 | 74 |       :ref:`the dis module <bytecodes>`. | 
 | 75 |  | 
| Skip Montanaro | 9feab31 | 2008-09-15 02:19:53 +0000 | [diff] [blame] | 76 |    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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 80 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 81 |    classic class | 
 | 82 |       Any class which does not inherit from :class:`object`.  See | 
| Ezio Melotti | 510ff54 | 2012-05-03 19:21:40 +0300 | [diff] [blame] | 83 |       :term:`new-style class`.  Classic classes have been removed in Python 3. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 84 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 85 |    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 Brandl | d7d4fd7 | 2009-07-26 14:37:28 +0000 | [diff] [blame] | 92 |       performed with the ``coerce`` built-in function; thus, ``3+4.5`` is | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 93 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 97 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 98 |    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 Brandl | d7d4fd7 | 2009-07-26 14:37:28 +0000 | [diff] [blame] | 103 |       engineering.  Python has built-in support for complex numbers, which are | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 104 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 109 |  | 
| Skip Montanaro | ffe455c | 2007-12-08 15:23:31 +0000 | [diff] [blame] | 110 |    context manager | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 111 |       An object which controls the environment seen in a :keyword:`with` | 
| Skip Montanaro | ffe455c | 2007-12-08 15:23:31 +0000 | [diff] [blame] | 112 |       statement by defining :meth:`__enter__` and :meth:`__exit__` methods. | 
 | 113 |       See :pep:`343`. | 
 | 114 |  | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 115 |    CPython | 
| Antoine Pitrou | 9f41bb3 | 2011-01-06 16:35:14 +0000 | [diff] [blame] | 116 |       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 Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 120 |  | 
| Georg Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 121 |    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 Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 137 |       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 Brandl | 5066c0c | 2008-12-05 18:00:06 +0000 | [diff] [blame] | 140 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 141 |    descriptor | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 142 |       Any *new-style* object which defines the methods :meth:`__get__`, | 
| Georg Brandl | 5e52db0 | 2007-10-21 10:45:46 +0000 | [diff] [blame] | 143 |       :meth:`__set__`, or :meth:`__delete__`.  When a class attribute is a | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 144 |       descriptor, its special binding behavior is triggered upon attribute | 
| Georg Brandl | 5e52db0 | 2007-10-21 10:45:46 +0000 | [diff] [blame] | 145 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 153 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 154 |    dictionary | 
| Senthil Kumaran | c768d4c | 2012-03-12 10:05:04 -0700 | [diff] [blame] | 155 |       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 Brandl | e64f738 | 2008-07-20 11:50:29 +0000 | [diff] [blame] | 158 |  | 
 | 159 |    docstring | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 160 |       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 Brandl | e64f738 | 2008-07-20 11:50:29 +0000 | [diff] [blame] | 165 |       object. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 166 |  | 
 | 167 |    duck-typing | 
| Georg Brandl | e85e1ae | 2010-10-06 09:17:24 +0000 | [diff] [blame] | 168 |       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 Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 171 |       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 Brandl | 04eba2c | 2010-07-11 08:56:18 +0000 | [diff] [blame] | 174 |       :func:`isinstance`.  (Note, however, that duck-typing can be complemented | 
| Éric Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 175 |       with :term:`abstract base classes <abstract base class>`.)  Instead, it | 
 | 176 |       typically employs :func:`hasattr` tests or :term:`EAFP` programming. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 177 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 178 |    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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 183 |       statements.  The technique contrasts with the :term:`LBYL` style | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 184 |       common to many other languages such as C. | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 185 |  | 
| Georg Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 186 |    expression | 
 | 187 |       A piece of syntax which can be evaluated to some value.  In other words, | 
| Éric Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 188 |       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 Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 194 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 195 |    extension module | 
| Georg Brandl | 28dadd9 | 2011-02-25 10:50:32 +0000 | [diff] [blame] | 196 |       A module written in C or C++, using Python's C API to interact with the | 
 | 197 |       core and with user code. | 
| Georg Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 198 |  | 
| Éric Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 199 |    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 Tosi | fd4c4b1 | 2012-06-02 23:40:59 +0200 | [diff] [blame] | 203 |       on-disk file or to another type of storage or communication device | 
| Éric Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 204 |       (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 Brandl | 624f337 | 2009-03-31 16:11:45 +0000 | [diff] [blame] | 216 |    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 Hettinger | f1b678d | 2010-09-01 22:25:41 +0000 | [diff] [blame] | 221 |    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 Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 228 |    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 Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 233 |    __future__ | 
| Raymond Hettinger | f1b678d | 2010-09-01 22:25:41 +0000 | [diff] [blame] | 234 |       A pseudo-module which programmers can use to enable new language features | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 235 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 238 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 239 |          from __future__ import division | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 240 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 241 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 245 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 246 |          >>> 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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 254 |  | 
| Georg Brandl | ea2d389 | 2010-04-02 09:11:49 +0000 | [diff] [blame] | 255 |       .. index:: single: generator | 
 | 256 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 257 |    generator | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 258 |       A function which returns an iterator.  It looks like a normal function | 
| Raymond Hettinger | f1b678d | 2010-09-01 22:25:41 +0000 | [diff] [blame] | 259 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 266 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 267 |       .. index:: single: generator expression | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 268 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 269 |    generator expression | 
| Georg Brandl | ea2d389 | 2010-04-02 09:11:49 +0000 | [diff] [blame] | 270 |       An expression that returns an iterator.  It looks like a normal expression | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 271 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 274 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 275 |          >>> sum(i*i for i in range(10))         # sum of squares 0, 1, 4, ... 81 | 
 | 276 |          285 | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 277 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 278 |    GIL | 
| Georg Brandl | 6c82b6c | 2007-08-17 16:54:59 +0000 | [diff] [blame] | 279 |       See :term:`global interpreter lock`. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 280 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 281 |    global interpreter lock | 
| Antoine Pitrou | 9f41bb3 | 2011-01-06 16:35:14 +0000 | [diff] [blame] | 282 |       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 Brandl | 7c3e79f | 2007-11-02 20:06:17 +0000 | [diff] [blame] | 301 |  | 
 | 302 |    hashable | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 303 |       An object is *hashable* if it has a hash value which never changes during | 
| Georg Brandl | 7c3e79f | 2007-11-02 20:06:17 +0000 | [diff] [blame] | 304 |       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 Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 306 |       Hashable objects which compare equal must have the same hash value. | 
| Georg Brandl | 7c3e79f | 2007-11-02 20:06:17 +0000 | [diff] [blame] | 307 |  | 
 | 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 Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 311 |       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 Brandl | 7c3e79f | 2007-11-02 20:06:17 +0000 | [diff] [blame] | 313 |       instances of user-defined classes are hashable by default; they all | 
 | 314 |       compare unequal, and their hash value is their :func:`id`. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 315 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 316 |    IDLE | 
 | 317 |       An Integrated Development Environment for Python.  IDLE is a basic editor | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 318 |       and interpreter environment which ships with the standard distribution of | 
| Raymond Hettinger | f1b678d | 2010-09-01 22:25:41 +0000 | [diff] [blame] | 319 |       Python. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 320 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 321 |    immutable | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 322 |       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 Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 324 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 327 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 328 |    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 Brandl | 6c82b6c | 2007-08-17 16:54:59 +0000 | [diff] [blame] | 335 |       coerced (see :term:`coercion`) to a common type.  For example, an integer | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 336 |       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 Brandl | 6c82b6c | 2007-08-17 16:54:59 +0000 | [diff] [blame] | 338 |       instead of the ``/`` operator.  See also :term:`__future__`. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 339 |  | 
| Georg Brandl | 624f337 | 2009-03-31 16:11:45 +0000 | [diff] [blame] | 340 |    importer | 
 | 341 |       An object that both finds and loads a module; both a | 
 | 342 |       :term:`finder` and :term:`loader` object. | 
 | 343 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 344 |    interactive | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 345 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 351 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 352 |    interpreted | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 353 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 360 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 361 |    iterable | 
| Éric Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 362 |       An object capable of returning its members one at a | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 363 |       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 Brandl | d7d4fd7 | 2009-07-26 14:37:28 +0000 | [diff] [blame] | 369 |       object is passed as an argument to the built-in function :func:`iter`, it | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 370 |       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 Brandl | 6c82b6c | 2007-08-17 16:54:59 +0000 | [diff] [blame] | 375 |       :term:`iterator`, :term:`sequence`, and :term:`generator`. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 376 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 377 |    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 Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 380 |       data are available a :exc:`StopIteration` exception is raised instead.  At | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 381 |       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 Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 386 |       which attempts multiple iteration passes.  A container object (such as a | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 387 |       :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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 391 |  | 
| Georg Brandl | e7a0990 | 2007-10-21 12:10:28 +0000 | [diff] [blame] | 392 |       More information can be found in :ref:`typeiter`. | 
 | 393 |  | 
| Georg Brandl | 3b85b9b | 2010-11-26 08:20:18 +0000 | [diff] [blame] | 394 |    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 Tosi | d987c02 | 2012-04-01 01:49:46 +0200 | [diff] [blame] | 409 |       the :mod:`operator` module provides three key function constructors: | 
| Georg Brandl | 3b85b9b | 2010-11-26 08:20:18 +0000 | [diff] [blame] | 410 |       :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 Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 414 |    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 Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 425 |    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 Brandl | 6c82b6c | 2007-08-17 16:54:59 +0000 | [diff] [blame] | 428 |       the :term:`EAFP` approach and is characterized by the presence of many | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 429 |       :keyword:`if` statements. | 
| Skip Montanaro | 9feab31 | 2008-09-15 02:19:53 +0000 | [diff] [blame] | 430 |  | 
| Éric Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 431 |       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 Montanaro | 9feab31 | 2008-09-15 02:19:53 +0000 | [diff] [blame] | 437 |    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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 441 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 442 |    list comprehension | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 443 |       A compact way to process all or part of the elements in a sequence and | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 444 |       return a list with the results.  ``result = ["0x%02x" % x for x in | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 445 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 449 |  | 
| Georg Brandl | 624f337 | 2009-03-31 16:11:45 +0000 | [diff] [blame] | 450 |    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 Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 455 |    mapping | 
| Raymond Hettinger | c4c52dd | 2011-01-08 23:50:39 +0000 | [diff] [blame] | 456 |       A container object that supports arbitrary key lookups and implements the | 
| Éric Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 457 |       methods specified in the :class:`~collections.Mapping` or | 
 | 458 |       :class:`~collections.MutableMapping` | 
| Éric Araujo | 8fde950 | 2011-07-29 11:34:17 +0200 | [diff] [blame] | 459 |       :ref:`abstract base classes <collections-abstract-base-classes>`.  Examples | 
 | 460 |       include :class:`dict`, :class:`collections.defaultdict`, | 
| Raymond Hettinger | c4c52dd | 2011-01-08 23:50:39 +0000 | [diff] [blame] | 461 |       :class:`collections.OrderedDict` and :class:`collections.Counter`. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 462 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 463 |    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 Brandl | a739503 | 2007-10-21 12:15:05 +0000 | [diff] [blame] | 473 |  | 
 | 474 |       More information can be found in :ref:`metaclasses`. | 
| Georg Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 475 |  | 
 | 476 |    method | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 477 |       A function which is defined inside a class body.  If called as an attribute | 
| Georg Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 478 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 481 |  | 
| Éric Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 482 |    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 Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 490 |    mutable | 
 | 491 |       Mutable objects can change their value but keep their :func:`id`.  See | 
| Georg Brandl | 6c82b6c | 2007-08-17 16:54:59 +0000 | [diff] [blame] | 492 |       also :term:`immutable`. | 
| Georg Brandl | e3c3db5 | 2008-01-11 09:55:53 +0000 | [diff] [blame] | 493 |  | 
 | 494 |    named tuple | 
| Raymond Hettinger | aff711d | 2009-02-04 19:25:17 +0000 | [diff] [blame] | 495 |       Any tuple-like class whose indexable elements are also accessible using | 
| Raymond Hettinger | c20ed51 | 2008-01-13 06:15:15 +0000 | [diff] [blame] | 496 |       named attributes (for example, :func:`time.localtime` returns a | 
| Raymond Hettinger | 8bdd044 | 2008-01-13 06:18:07 +0000 | [diff] [blame] | 497 |       tuple-like object where the *year* is accessible either with an | 
| Raymond Hettinger | c20ed51 | 2008-01-13 06:15:15 +0000 | [diff] [blame] | 498 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 506 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 507 |    namespace | 
 | 508 |       The place where a variable is stored.  Namespaces are implemented as | 
| Georg Brandl | d7d4fd7 | 2009-07-26 14:37:28 +0000 | [diff] [blame] | 509 |       dictionaries.  There are the local, global and built-in namespaces as well | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 510 |       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 Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 517 |       modules, respectively. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 518 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 519 |    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 Tosi | 03c6110 | 2012-01-17 18:32:02 +0100 | [diff] [blame] | 522 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 526 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 527 |    new-style class | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 528 |       Any class which inherits from :class:`object`.  This includes all built-in | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 529 |       types like :class:`list` and :class:`dict`.  Only new-style classes can | 
 | 530 |       use Python's newer, versatile features like :attr:`__slots__`, | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 531 |       descriptors, properties, and :meth:`__getattribute__`. | 
| Georg Brandl | a739503 | 2007-10-21 12:15:05 +0000 | [diff] [blame] | 532 |  | 
 | 533 |       More information can be found in :ref:`newstyle`. | 
| Skip Montanaro | 9feab31 | 2008-09-15 02:19:53 +0000 | [diff] [blame] | 534 |  | 
 | 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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 539 |  | 
| Georg Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 540 |    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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 547 |    Python 3000 | 
| Éric Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 548 |       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 Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 551 |  | 
| Georg Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 552 |    Pythonic | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 553 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 559 |  | 
| Georg Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 560 |           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 Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 568 |    reference count | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 569 |       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 Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 573 |       :func:`~sys.getrefcount` function that programmers can call to return the | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 574 |       reference count for a particular object. | 
 | 575 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 576 |    __slots__ | 
| Georg Brandl | 6c82b6c | 2007-08-17 16:54:59 +0000 | [diff] [blame] | 577 |       A declaration inside a :term:`new-style class` that saves memory by | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 578 |       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 Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 582 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 583 |    sequence | 
| Georg Brandl | 6c82b6c | 2007-08-17 16:54:59 +0000 | [diff] [blame] | 584 |       An :term:`iterable` which supports efficient element access using integer | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 585 |       indices via the :meth:`__getitem__` special method and defines a | 
 | 586 |       :meth:`len` method that returns the length of the sequence. | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 587 |       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 Brandl | 6c82b6c | 2007-08-17 16:54:59 +0000 | [diff] [blame] | 591 |       :term:`immutable` keys rather than integers. | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 592 |  | 
| Georg Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 593 |    slice | 
| Georg Brandl | 968a3e5 | 2007-12-02 18:17:50 +0000 | [diff] [blame] | 594 |       An object usually containing a portion of a :term:`sequence`.  A slice is | 
| Georg Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 595 |       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 Brandl | 9a05373 | 2008-12-05 15:29:39 +0000 | [diff] [blame] | 600 |    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 Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 606 |    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 Araujo | a8f66dd | 2011-08-19 01:27:00 +0200 | [diff] [blame] | 609 |       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 Brandl | 584265b | 2007-12-02 14:58:50 +0000 | [diff] [blame] | 618 |  | 
| Skip Montanaro | 9feab31 | 2008-09-15 02:19:53 +0000 | [diff] [blame] | 619 |    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 Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 628 |    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 Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 632 |  | 
| Alexandre Vassalotti | 69eb516 | 2010-01-11 23:17:10 +0000 | [diff] [blame] | 633 |    view | 
 | 634 |       The objects returned from :meth:`dict.viewkeys`, :meth:`dict.viewvalues`, | 
 | 635 |       and :meth:`dict.viewitems` are called dictionary views.  They are lazy | 
 | 636 |       sequences that will see changes in the underlying dictionary.  To force | 
 | 637 |       the dictionary view to become a full list use ``list(dictview)``.  See | 
 | 638 |       :ref:`dict-views`. | 
 | 639 |  | 
| Skip Montanaro | f02c5f3 | 2008-09-15 02:03:05 +0000 | [diff] [blame] | 640 |    virtual machine | 
 | 641 |       A computer defined entirely in software.  Python's virtual machine | 
 | 642 |       executes the :term:`bytecode` emitted by the bytecode compiler. | 
| Georg Brandl | c62ef8b | 2009-01-03 20:55:06 +0000 | [diff] [blame] | 643 |  | 
| Georg Brandl | 437e6a3 | 2007-08-17 06:27:11 +0000 | [diff] [blame] | 644 |    Zen of Python | 
 | 645 |       Listing of Python design principles and philosophies that are helpful in | 
 | 646 |       understanding and using the language.  The listing can be found by typing | 
 | 647 |       "``import this``" at the interactive prompt. |