rest25/library/functions.rst => rest262/library/functions.rst
f1
2.. _built-in-funcs:
3
4Built-in Functions
5==================
6
7The Python interpreter has a number of functions built into it that are always
8available.  They are listed here in alphabetical order.
n9- 
10- 
11-.. function:: __import__(name[, globals[, locals[, fromlist[, level]]]])
12- 
13-   .. index::
14-      statement: import
15-      module: ihooks
16-      module: rexec
17-      module: imp
18- 
19-   This function is invoked by the :keyword:`import` statement.  It mainly exists
20-   so that you can replace it with another function that has a compatible
21-   interface, in order to change the semantics of the :keyword:`import` statement.
22-   For examples of why and how you would do this, see the standard library modules
23-   :mod:`ihooks` and :mod:`rexec`.  See also the built-in module :mod:`imp`, which
24-   defines some useful operations out of which you can build your own
25-   :func:`__import__` function.
26- 
27-   For example, the statement ``import spam`` results in the following call:
28-   ``__import__('spam',`` ``globals(),`` ``locals(), [], -1)``; the statement
29-   ``from spam.ham import eggs`` results in ``__import__('spam.ham', globals(),
30-   locals(), ['eggs'], -1)``.  Note that even though ``locals()`` and ``['eggs']``
31-   are passed in as arguments, the :func:`__import__` function does not set the
32-   local variable named ``eggs``; this is done by subsequent code that is generated
33-   for the import statement.  (In fact, the standard implementation does not use
34-   its *locals* argument at all, and uses its *globals* only to determine the
35-   package context of the :keyword:`import` statement.)
36- 
37-   When the *name* variable is of the form ``package.module``, normally, the top-
38-   level package (the name up till the first dot) is returned, *not* the module
39-   named by *name*.  However, when a non-empty *fromlist* argument is given, the
40-   module named by *name* is returned.  This is done for compatibility with the
41-   bytecode generated for the different kinds of import statement; when using
42-   ``import spam.ham.eggs``, the top-level package :mod:`spam` must be placed in
43-   the importing namespace, but when using ``from spam.ham import eggs``, the
44-   ``spam.ham`` subpackage must be used to find the ``eggs`` variable.  As a
45-   workaround for this behavior, use :func:`getattr` to extract the desired
46-   components.  For example, you could define the following helper::
47- 
48-      def my_import(name):
49-          mod = __import__(name)
50-          components = name.split('.')
51-          for comp in components[1:]:
52-              mod = getattr(mod, comp)
53-          return mod
54- 
55-   *level* specifies whether to use absolute or relative imports. The default is
56-   ``-1`` which indicates both absolute and relative imports will be attempted.
57-   ``0`` means only perform absolute imports. Positive values for *level* indicate
58-   the number of parent directories to search relative to the directory of the
59-   module calling :func:`__import__`.
60- 
61-   .. versionchanged:: 2.5
62-      The level parameter was added.
63- 
64-   .. versionchanged:: 2.5
65-      Keyword support for parameters was added.
66
67
68.. function:: abs(x)
69
70   Return the absolute value of a number.  The argument may be a plain or long
71   integer or a floating point number.  If the argument is a complex number, its
72   magnitude is returned.
73
103   This abstract type is the superclass for :class:`str` and :class:`unicode`. It
104   cannot be called or instantiated, but it can be used to test whether an object
105   is an instance of :class:`str` or :class:`unicode`. ``isinstance(obj,
106   basestring)`` is equivalent to ``isinstance(obj, (str, unicode))``.
107
108   .. versionadded:: 2.3
109
110
n54+.. function:: bin(x)
55+ 
56+   Convert an integer number to a binary string. The result is a valid Python
57+   expression.  If *x* is not a Python :class:`int` object, it has to define an
58+   :meth:`__index__` method that returns an integer.
59+ 
60+   .. versionadded:: 2.6
61+ 
62+ 
111.. function:: bool([x])
112
113   Convert a value to a Boolean, using the standard truth testing procedure.  If
114   *x* is false or omitted, this returns :const:`False`; otherwise it returns
115   :const:`True`. :class:`bool` is also a class, which is a subclass of
116   :class:`int`. Class :class:`bool` cannot be subclassed further.  Its only
117   instances are :const:`False` and :const:`True`.
118
121   .. versionadded:: 2.2.1
122
123   .. versionchanged:: 2.3
124      If no argument is given, this function returns :const:`False`.
125
126
127.. function:: callable(object)
128
n129-   Return true if the *object* argument appears callable, false if not.  If this
n81+   Return :const:`True` if the *object* argument appears callable,
82+   :const:`False` if not.  If this
130   returns true, it is still possible that a call fails, but if it is false,
131   calling *object* will never succeed.  Note that classes are callable (calling a
132   class returns a new instance); class instances are callable if they have a
133   :meth:`__call__` method.
134
135
136.. function:: chr(i)
137
138   Return a string of one character whose ASCII code is the integer *i*.  For
139   example, ``chr(97)`` returns the string ``'a'``. This is the inverse of
140   :func:`ord`.  The argument must be in the range [0..255], inclusive;
n141-   :exc:`ValueError` will be raised if *i* is outside that range.
n94+   :exc:`ValueError` will be raised if *i* is outside that range. See
95+   also :func:`unichr`.
142
143
144.. function:: classmethod(function)
145
146   Return a class method for *function*.
147
148   A class method receives the class as implicit first argument, just like an
149   instance method receives the instance. To declare a class method, use this
150   idiom::
151
152      class C:
153          @classmethod
154          def f(cls, arg1, arg2, ...): ...
155
n156-   The ``@classmethod`` form is a function decorator -- see the description of
n110+   The ``@classmethod`` form is a function :term:`decorator` -- see the description
157-   function definitions in chapter 7 of the Python Reference Manual (XXX reference:
111+   of function definitions in :ref:`function` for details.
158-   ../ref/ref.html) for details.
159
160   It can be called either on the class (such as ``C.f()``) or on an instance (such
161   as ``C().f()``).  The instance is ignored except for its class. If a class
162   method is called for a derived class, the derived class object is passed as the
163   implied first argument.
164
165   Class methods are different than C++ or Java static methods. If you want those,
166   see :func:`staticmethod` in this section.
167
168   For more information on class methods, consult the documentation on the standard
n169-   type hierarchy in chapter 3 of the Python Reference Manual (XXX reference:
n122+   type hierarchy in :ref:`types`.
170-   ../ref/types.html) (at the bottom).
171
172   .. versionadded:: 2.2
173
174   .. versionchanged:: 2.4
175      Function decorator syntax added.
176
177
178.. function:: cmp(x, y)
179
180   Compare the two objects *x* and *y* and return an integer according to the
181   outcome.  The return value is negative if ``x < y``, zero if ``x == y`` and
182   strictly positive if ``x > y``.
183
184
n185-.. function:: compile(string, filename, kind[, flags[, dont_inherit]])
n137+.. function:: compile(source, filename, mode[, flags[, dont_inherit]])
186
n187-   Compile the *string* into a code object.  Code objects can be executed by an
n139+   Compile the *source* into a code or AST object.  Code objects can be executed
188-   :keyword:`exec` statement or evaluated by a call to :func:`eval`.  The
140+   by an :keyword:`exec` statement or evaluated by a call to :func:`eval`.
141+   *source* can either be a string or an AST object.  Refer to the :mod:`ast`
142+   module documentation for information on how to work with AST objects.
143+ 
189-   *filename* argument should give the file from which the code was read; pass some
144+   The *filename* argument should give the file from which the code was read;
190-   recognizable value if it wasn't read from a file (``'<string>'`` is commonly
145+   pass some recognizable value if it wasn't read from a file (``'<string>'`` is
146+   commonly used).
147+ 
191-   used). The *kind* argument specifies what kind of code must be compiled; it can
148+   The *mode* argument specifies what kind of code must be compiled; it can be
192-   be ``'exec'`` if *string* consists of a sequence of statements, ``'eval'`` if it
149+   ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
193   consists of a single expression, or ``'single'`` if it consists of a single
n194-   interactive statement (in the latter case, expression statements that evaluate
n151+   interactive statement (in the latter case, expression statements that
195-   to something else than ``None`` will be printed).
152+   evaluate to something else than ``None`` will be printed).
196
n197-   When compiling multi-line statements, two caveats apply: line endings must be
198-   represented by a single newline character (``'\n'``), and the input must be
199-   terminated by at least one newline character.  If line endings are represented
200-   by ``'\r\n'``, use the string :meth:`replace` method to change them into
201-   ``'\n'``.
202- 
203-   The optional arguments *flags* and *dont_inherit* (which are new in Python 2.2)
154+   The optional arguments *flags* and *dont_inherit* control which future
204-   control which future statements (see :pep:`236`) affect the compilation of
155+   statements (see :pep:`236`) affect the compilation of *source*.  If neither
205-   *string*.  If neither is present (or both are zero) the code is compiled with
156+   is present (or both are zero) the code is compiled with those future
206-   those future statements that are in effect in the code that is calling compile.
157+   statements that are in effect in the code that is calling compile.  If the
207-   If the *flags* argument is given and *dont_inherit* is not (or is zero) then the
158+   *flags* argument is given and *dont_inherit* is not (or is zero) then the
208   future statements specified by the *flags* argument are used in addition to
209   those that would be used anyway. If *dont_inherit* is a non-zero integer then
n210-   the *flags* argument is it -- the future statements in effect around the call to
n161+   the *flags* argument is it -- the future statements in effect around the call
211-   compile are ignored.
162+   to compile are ignored.
212
n213-   Future statements are specified by bits which can be bitwise or-ed together to
n164+   Future statements are specified by bits which can be bitwise ORed together to
214   specify multiple statements.  The bitfield required to specify a given feature
215   can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
216   instance in the :mod:`__future__` module.
n168+ 
169+   This function raises :exc:`SyntaxError` if the compiled source is invalid,
170+   and :exc:`TypeError` if the source contains null bytes.
171+ 
172+   .. note::
173+ 
174+      When compiling a string with multi-line statements, line endings must be
175+      represented by a single newline character (``'\n'``), and the input must
176+      be terminated by at least one newline character.  If line endings are
177+      represented by ``'\r\n'``, use :meth:`str.replace` to change them into
178+      ``'\n'``.
179+ 
180+   .. versionchanged:: 2.3
181+      The *flags* and *dont_inherit* arguments were added.
182+ 
183+   .. versionchanged:: 2.6
184+      Support for compiling AST objects.
217
218
219.. function:: complex([real[, imag]])
220
221   Create a complex number with the value *real* + *imag*\*j or convert a string or
222   number to a complex number.  If the first parameter is a string, it will be
223   interpreted as a complex number and the function must be called without a second
224   parameter.  The second parameter can never be a string. Each argument may be any
225   numeric type (including complex). If *imag* is omitted, it defaults to zero and
226   the function serves as a numeric conversion function like :func:`int`,
227   :func:`long` and :func:`float`.  If both arguments are omitted, returns ``0j``.
228
n197+   The complex type is described in :ref:`typesnumeric`.
198+ 
229
230.. function:: delattr(object, name)
231
232   This is a relative of :func:`setattr`.  The arguments are an object and a
233   string.  The string must be the name of one of the object's attributes.  The
234   function deletes the named attribute, provided the object allows it.  For
235   example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
236
237
n238-.. function:: dict([mapping-or-sequence])
n208+.. function:: dict([arg])
209+   :noindex:
239
n240-   Return a new dictionary initialized from an optional positional argument or from
n211+   Create a new data dictionary, optionally with items taken from *arg*.
241-   a set of keyword arguments. If no arguments are given, return a new empty
212+   The dictionary type is described in :ref:`typesmapping`.
242-   dictionary. If the positional argument is a mapping object, return a dictionary
243-   mapping the same keys to the same values as does the mapping object. Otherwise
244-   the positional argument must be a sequence, a container that supports iteration,
245-   or an iterator object.  The elements of the argument must each also be of one of
246-   those kinds, and each must in turn contain exactly two objects.  The first is
247-   used as a key in the new dictionary, and the second as the key's value.  If a
248-   given key is seen more than once, the last value associated with it is retained
249-   in the new dictionary.
250
n251-   If keyword arguments are given, the keywords themselves with their associated
n214+   For other containers see the built in :class:`list`, :class:`set`, and
252-   values are added as items to the dictionary. If a key is specified both in the
215+   :class:`tuple` classes, and the :mod:`collections` module.
253-   positional argument and as a keyword argument, the value associated with the
254-   keyword is retained in the dictionary. For example, these all return a
255-   dictionary equal to ``{"one": 2, "two": 3}``:
256- 
257-* ``dict({'one': 2, 'two': 3})``
258- 
259-* ``dict({'one': 2, 'two': 3}.items())``
260- 
261-* ``dict({'one': 2, 'two': 3}.iteritems())``
262- 
263-* ``dict(zip(('one', 'two'), (2, 3)))``
264- 
265-* ``dict([['two', 3], ['one', 2]])``
266- 
267-* ``dict(one=2, two=3)``
268- 
269-* ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])``
270- 
271-   .. versionadded:: 2.2
272- 
273-   .. versionchanged:: 2.3
274-      Support for building a dictionary from keyword arguments added.
275
276
277.. function:: dir([object])
278
n279-   Without arguments, return the list of names in the current local symbol table.
n220+   Without arguments, return the list of names in the current local scope.  With an
280-   With an argument, attempts to return a list of valid attributes for that object.
221+   argument, attempt to return a list of valid attributes for that object.
222+ 
223+   If the object has a method named :meth:`__dir__`, this method will be called and
224+   must return the list of attributes. This allows objects that implement a custom
225+   :func:`__getattr__` or :func:`__getattribute__` function to customize the way
226+   :func:`dir` reports their attributes.
227+ 
228+   If the object does not provide :meth:`__dir__`, the function tries its best to
281-   This information is gleaned from the object's :attr:`__dict__` attribute, if
229+   gather information from the object's :attr:`__dict__` attribute, if defined, and
282-   defined, and from the class or type object.  The list is not necessarily
230+   from its type object.  The resulting list is not necessarily complete, and may
231+   be inaccurate when the object has a custom :func:`__getattr__`.
232+ 
233+   The default :func:`dir` mechanism behaves differently with different types of
234+   objects, as it attempts to produce the most relevant, rather than complete,
235+   information:
236+ 
283-   complete. If the object is a module object, the list contains the names of the
237+   * If the object is a module object, the list contains the names of the module's
238+     attributes.
239+ 
284-   module's attributes. If the object is a type or class object, the list contains
240+   * If the object is a type or class object, the list contains the names of its
285-   the names of its attributes, and recursively of the attributes of its bases.
241+     attributes, and recursively of the attributes of its bases.
242+ 
286-   Otherwise, the list contains the object's attributes' names, the names of its
243+   * Otherwise, the list contains the object's attributes' names, the names of its
287-   class's attributes, and recursively of the attributes of its class's base
244+     class's attributes, and recursively of the attributes of its class's base
245+     classes.
246+ 
288-   classes. The resulting list is sorted alphabetically. For example::
247+   The resulting list is sorted alphabetically.  For example:
289
290      >>> import struct
n291-      >>> dir()
n250+      >>> dir()   # doctest: +SKIP
292      ['__builtins__', '__doc__', '__name__', 'struct']
n252+      >>> dir(struct)   # doctest: +NORMALIZE_WHITESPACE
253+      ['Struct', '__builtins__', '__doc__', '__file__', '__name__',
254+       '__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
255+       'unpack', 'unpack_from']
256+      >>> class Foo(object):
257+      ...     def __dir__(self):
258+      ...         return ["kan", "ga", "roo"]
259+      ...
260+      >>> f = Foo()
293-      >>> dir(struct)
261+      >>> dir(f)
294-      ['__doc__', '__name__', 'calcsize', 'error', 'pack', 'unpack']
262+      ['ga', 'kan', 'roo']
295
296   .. note::
297
298      Because :func:`dir` is supplied primarily as a convenience for use at an
299      interactive prompt, it tries to supply an interesting set of names more than it
300      tries to supply a rigorously or consistently defined set of names, and its
n301-      detailed behavior may change across releases.
n269+      detailed behavior may change across releases.  For example, metaclass attributes
270+      are not in the result list when the argument is a class.
302
303
304.. function:: divmod(a, b)
305
306   Take two (non complex) numbers as arguments and return a pair of numbers
307   consisting of their quotient and remainder when using long division.  With mixed
308   operand types, the rules for binary arithmetic operators apply.  For plain and
309   long integers, the result is the same as ``(a // b, a % b)``. For floating point
311   but may be 1 less than that.  In any case ``q * b + a % b`` is very close to
312   *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0 <= abs(a % b)
313   < abs(b)``.
314
315   .. versionchanged:: 2.3
316      Using :func:`divmod` with complex numbers is deprecated.
317
318
n319-.. function:: enumerate(iterable)
n288+.. function:: enumerate(sequence[, start=0])
320
n321-   Return an enumerate object. *iterable* must be a sequence, an iterator, or some
n290+   Return an enumerate object. *sequence* must be a sequence, an
322-   other object which supports iteration.  The :meth:`next` method of the iterator
291+   :term:`iterator`, or some other object which supports iteration.  The
323-   returned by :func:`enumerate` returns a tuple containing a count (from zero) and
292+   :meth:`next` method of the iterator returned by :func:`enumerate` returns a
293+   tuple containing a count (from *start* which defaults to 0) and the
324-   the corresponding value obtained from iterating over *iterable*.
294+   corresponding value obtained from iterating over *iterable*.
325   :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``,
n326-   ``(1, seq[1])``, ``(2, seq[2])``, ....
n296+   ``(1, seq[1])``, ``(2, seq[2])``, .... For example:
297+ 
298+      >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter']):
299+      ...     print i, season
300+      0 Spring
301+      1 Summer
302+      2 Fall
303+      3 Winter
327
328   .. versionadded:: 2.3
n306+   .. versionadded:: 2.6
307+      The *start* parameter.
329
330
331.. function:: eval(expression[, globals[, locals]])
332
333   The arguments are a string and optional globals and locals.  If provided,
334   *globals* must be a dictionary.  If provided, *locals* can be any mapping
335   object.
336
337   .. versionchanged:: 2.4
338      formerly *locals* was required to be a dictionary.
339
340   The *expression* argument is parsed and evaluated as a Python expression
341   (technically speaking, a condition list) using the *globals* and *locals*
n342-   dictionaries as global and local name space.  If the *globals* dictionary is
n321+   dictionaries as global and local namespace.  If the *globals* dictionary is
343   present and lacks '__builtins__', the current globals are copied into *globals*
344   before *expression* is parsed.  This means that *expression* normally has full
345   access to the standard :mod:`__builtin__` module and restricted environments are
346   propagated.  If the *locals* dictionary is omitted it defaults to the *globals*
347   dictionary.  If both dictionaries are omitted, the expression is executed in the
n348-   environment where :keyword:`eval` is called.  The return value is the result of
n327+   environment where :func:`eval` is called.  The return value is the result of
349-   the evaluated expression. Syntax errors are reported as exceptions.  Example::
328+   the evaluated expression. Syntax errors are reported as exceptions.  Example:
350
351      >>> x = 1
352      >>> print eval('x+1')
353      2
354
n355-   This function can also be used to execute arbitrary code objects (such as those
n334+   This function can also be used to execute arbitrary code objects (such as
356-   created by :func:`compile`).  In this case pass a code object instead of a
335+   those created by :func:`compile`).  In this case pass a code object instead
357-   string.  The code object must have been compiled passing ``'eval'`` as the
336+   of a string.  If the code object has been compiled with ``'exec'`` as the
358-   *kind* argument.
337+   *kind* argument, :func:`eval`\'s return value will be ``None``.
359
360   Hints: dynamic execution of statements is supported by the :keyword:`exec`
361   statement.  Execution of statements from a file is supported by the
362   :func:`execfile` function.  The :func:`globals` and :func:`locals` functions
363   returns the current global and local dictionary, respectively, which may be
364   useful to pass around for use by :func:`eval` or :func:`execfile`.
365
366
389      modifications to the default *locals* dictionary should not be attempted.  Pass
390      an explicit *locals* dictionary if you need to see effects of the code on
391      *locals* after function :func:`execfile` returns.  :func:`execfile` cannot be
392      used reliably to modify a function's locals.
393
394
395.. function:: file(filename[, mode[, bufsize]])
396
n397-   Constructor function for the :class:`file` type, described further  in section
n376+   Constructor function for the :class:`file` type, described further in section
398-   :ref:`bltin-file-objects`, "File Objects (XXX reference: bltin-file-
399-   objects.html)".  The constructor's arguments are the same as those of the
377+   :ref:`bltin-file-objects`.  The constructor's arguments are the same as those
400-   :func:`open` built-in function described below.
378+   of the :func:`open` built-in function described below.
401
402   When opening a file, it's preferable to use :func:`open` instead of  invoking
403   this constructor directly.  :class:`file` is more suited to type testing (for
404   example, writing ``isinstance(f, file)``).
405
406   .. versionadded:: 2.2
407
408
n409-.. function:: filter(function, list)
n387+.. function:: filter(function, iterable)
410
n411-   Construct a list from those elements of *list* for which *function* returns
n389+   Construct a list from those elements of *iterable* for which *function* returns
412-   true.  *list* may be either a sequence, a container which supports iteration, or
390+   true.  *iterable* may be either a sequence, a container which supports
413-   an iterator,  If *list* is a string or a tuple, the result also has that type;
391+   iteration, or an iterator.  If *iterable* is a string or a tuple, the result
414-   otherwise it is always a list.  If *function* is ``None``, the identity function
392+   also has that type; otherwise it is always a list.  If *function* is ``None``,
415-   is assumed, that is, all elements of *list* that are false are removed.
393+   the identity function is assumed, that is, all elements of *iterable* that are
394+   false are removed.
416
n417-   Note that ``filter(function, list)`` is equivalent to ``[item for item in list
n396+   Note that ``filter(function, iterable)`` is equivalent to ``[item for item in
418-   if function(item)]`` if function is not ``None`` and ``[item for item in list if
397+   iterable if function(item)]`` if function is not ``None`` and ``[item for item
419-   item]`` if function is ``None``.
398+   in iterable if item]`` if function is ``None``.
399+ 
400+   See :func:`itertools.filterfalse` for the complementary function that returns
401+   elements of *iterable* for which *function* returns false.
420
421
422.. function:: float([x])
423
424   Convert a string or a number to floating point.  If the argument is a string, it
425   must contain a possibly signed decimal or floating point number, possibly
n408+   embedded in whitespace. The argument may also be [+|-]nan or [+|-]inf.
426-   embedded in whitespace. Otherwise, the argument may be a plain or long integer
409+   Otherwise, the argument may be a plain or long integer
427   or a floating point number, and a floating point number with the same value
428   (within Python's floating point precision) is returned.  If no argument is
429   given, returns ``0.0``.
430
431   .. note::
432
433      .. index::
434         single: NaN
435         single: Infinity
436
437      When passing in a string, values for NaN and Infinity may be returned, depending
n438-      on the underlying C library.  The specific set of strings accepted which cause
n421+      on the underlying C library.  Float accepts the strings nan, inf and -inf for
439-      these values to be returned depends entirely on the C library and is known to
422+      NaN and positive or negative infinity. The case and a leading + are ignored as
440-      vary.
423+      well as a leading - is ignored for NaN. Float always represents NaN and infinity
424+      as nan, inf or -inf.
425+ 
426+   The float type is described in :ref:`typesnumeric`.
427+ 
428+ 
429+.. function:: format(value[, format_spec])
430+ 
431+   .. index::
432+      pair: str; format
433+      single: __format__
434+ 
435+   Convert a *value* to a "formatted" representation, as controlled by
436+   *format_spec*.  The interpretation of *format_spec* will depend on the type
437+   of the *value* argument, however there is a standard formatting syntax that
438+   is used by most built-in types: :ref:`formatspec`.
439+ 
440+   .. note::
441+ 
442+      ``format(value, format_spec)`` merely calls
443+      ``value.__format__(format_spec)``.
444+ 
445+   .. versionadded:: 2.6
441
442
443.. function:: frozenset([iterable])
n449+   :noindex:
444
n445-   Return a frozenset object whose elements are taken from *iterable*. Frozensets
n451+   Return a frozenset object, optionally with elements taken from *iterable*.
446-   are sets that have no update methods but can be hashed and used as members of
452+   The frozenset type is described in :ref:`types-set`.
447-   other sets or as dictionary keys.  The elements of a frozenset must be immutable
453+ 
448-   themselves.  To represent sets of sets, the inner sets should also be
454+   For other containers see the built in :class:`dict`, :class:`list`, and
449-   :class:`frozenset` objects.  If *iterable* is not specified, returns a new empty
455+   :class:`tuple` classes, and the :mod:`collections` module.
450-   set, ``frozenset([])``.
451
452   .. versionadded:: 2.4
453
454
455.. function:: getattr(object, name[, default])
456
457   Return the value of the named attributed of *object*.  *name* must be a string.
458   If the string is the name of one of the object's attributes, the result is the
488
489   Invoke the built-in help system.  (This function is intended for interactive
490   use.)  If no argument is given, the interactive help system starts on the
491   interpreter console.  If the argument is a string, then the string is looked up
492   as the name of a module, function, class, method, keyword, or documentation
493   topic, and a help page is printed on the console.  If the argument is any other
494   kind of object, a help page on the object is generated.
495
n501+   This function is added to the built-in namespace by the :mod:`site` module.
502+ 
496   .. versionadded:: 2.2
497
498
499.. function:: hex(x)
500
501   Convert an integer number (of any size) to a hexadecimal string. The result is a
502   valid Python expression.
503
528   If the :mod:`readline` module was loaded, then :func:`input` will use it to
529   provide elaborate line editing and history features.
530
531   Consider using the :func:`raw_input` function for general input from users.
532
533
534.. function:: int([x[, radix]])
535
n536-   Convert a string or number to a plain integer.  If the argument is a string, it
n543+   Convert a string or number to a plain integer.  If the argument is a string,
537-   must contain a possibly signed decimal number representable as a Python integer,
544+   it must contain a possibly signed decimal number representable as a Python
538-   possibly embedded in whitespace. The *radix* parameter gives the base for the
545+   integer, possibly embedded in whitespace.  The *radix* parameter gives the
539-   conversion and may be any integer in the range [2, 36], or zero.  If *radix* is
546+   base for the conversion (which is 10 by default) and may be any integer in
540-   zero, the proper radix is guessed based on the contents of string; the
547+   the range [2, 36], or zero.  If *radix* is zero, the proper radix is
541-   interpretation is the same as for integer literals.  If *radix* is specified and
548+   determined based on the contents of string; the interpretation is the same as
549+   for integer literals.  (See :ref:`numbers`.)  If *radix* is specified and *x*
542-   *x* is not a string, :exc:`TypeError` is raised. Otherwise, the argument may be
550+   is not a string, :exc:`TypeError` is raised. Otherwise, the argument may be a
543-   a plain or long integer or a floating point number.  Conversion of floating
551+   plain or long integer or a floating point number.  Conversion of floating
544-   point numbers to integers truncates (towards zero). If the argument is outside
552+   point numbers to integers truncates (towards zero).  If the argument is
545-   the integer range a long object will be returned instead.  If no arguments are
553+   outside the integer range a long object will be returned instead.  If no
546-   given, returns ``0``.
554+   arguments are given, returns ``0``.
555+ 
556+   The integer type is described in :ref:`typesnumeric`.
547
548
549.. function:: isinstance(object, classinfo)
550
551   Return true if the *object* argument is an instance of the *classinfo* argument,
552   or of a (direct or indirect) subclass thereof.  Also return true if *classinfo*
n553-   is a type object and *object* is an object of that type.  If *object* is not a
n563+   is a type object (new-style class) and *object* is an object of that type or of
554-   class instance or an object of the given type, the function always returns
564+   a (direct or indirect) subclass thereof.  If *object* is not a class instance or
555-   false.  If *classinfo* is neither a class object nor a type object, it may be a
565+   an object of the given type, the function always returns false.  If *classinfo*
556-   tuple of class or type objects, or may recursively contain other such tuples
566+   is neither a class object nor a type object, it may be a tuple of class or type
557-   (other sequence types are not accepted).  If *classinfo* is not a class, type,
567+   objects, or may recursively contain other such tuples (other sequence types are
558-   or tuple of classes, types, and such tuples, a :exc:`TypeError` exception is
568+   not accepted).  If *classinfo* is not a class, type, or tuple of classes, types,
559-   raised.
569+   and such tuples, a :exc:`TypeError` exception is raised.
560
561   .. versionchanged:: 2.2
562      Support for a tuple of type information was added.
563
564
565.. function:: issubclass(class, classinfo)
566
567   Return true if *class* is a subclass (direct or indirect) of *classinfo*.  A
570   case, a :exc:`TypeError` exception is raised.
571
572   .. versionchanged:: 2.3
573      Support for a tuple of type information was added.
574
575
576.. function:: iter(o[, sentinel])
577
n578-   Return an iterator object.  The first argument is interpreted very differently
n588+   Return an :term:`iterator` object.  The first argument is interpreted very differently
579   depending on the presence of the second argument. Without a second argument, *o*
580   must be a collection object which supports the iteration protocol (the
581   :meth:`__iter__` method), or it must support the sequence protocol (the
582   :meth:`__getitem__` method with integer arguments starting at ``0``).  If it
583   does not support either of those protocols, :exc:`TypeError` is raised. If the
584   second argument, *sentinel*, is given, then *o* must be a callable object.  The
585   iterator created in this case will call *o* with no arguments for each call to
586   its :meth:`next` method; if the value returned is equal to *sentinel*,
590
591
592.. function:: len(s)
593
594   Return the length (the number of items) of an object.  The argument may be a
595   sequence (string, tuple or list) or a mapping (dictionary).
596
597
n598-.. function:: list([sequence])
n608+.. function:: list([iterable])
599
n600-   Return a list whose items are the same and in the same order as *sequence*'s
n610+   Return a list whose items are the same and in the same order as *iterable*'s
601-   items.  *sequence* may be either a sequence, a container that supports
611+   items.  *iterable* may be either a sequence, a container that supports
602-   iteration, or an iterator object.  If *sequence* is already a list, a copy is
612+   iteration, or an iterator object.  If *iterable* is already a list, a copy is
603-   made and returned, similar to ``sequence[:]``.  For instance, ``list('abc')``
613+   made and returned, similar to ``iterable[:]``.  For instance, ``list('abc')``
604   returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``.  If
605   no argument is given, returns a new empty list, ``[]``.
606
n617+   :class:`list` is a mutable sequence type, as documented in
618+   :ref:`typesseq`. For other containers see the built in :class:`dict`,
619+   :class:`set`, and :class:`tuple` classes, and the :mod:`collections` module.
620+ 
607
608.. function:: locals()
609
610   Update and return a dictionary representing the current local symbol table.
611
612   .. warning::
613
614      The contents of this dictionary should not be modified; changes may not affect
615      the values of local variables used by the interpreter.
n630+ 
631+   Free variables are returned by :func:`locals` when it is called in a function block.
632+   Modifications of free variables may not affect the values used by the
633+   interpreter.  Free variables are not returned in class blocks.
616
617
618.. function:: long([x[, radix]])
619
620   Convert a string or number to a long integer.  If the argument is a string, it
621   must contain a possibly signed number of arbitrary size, possibly embedded in
622   whitespace. The *radix* argument is interpreted in the same way as for
623   :func:`int`, and may only be given when *x* is a string. Otherwise, the argument
624   may be a plain or long integer or a floating point number, and a long integer
625   with the same value is returned.    Conversion of floating point numbers to
626   integers truncates (towards zero).  If no arguments are given, returns ``0L``.
627
n646+   The long type is described in :ref:`typesnumeric`.
628
n629-.. function:: map(function, list, ...)
n648+.. function:: map(function, iterable, ...)
630
n631-   Apply *function* to every item of *list* and return a list of the results.  If
n650+   Apply *function* to every item of *iterable* and return a list of the results.
632-   additional *list* arguments are passed, *function* must take that many arguments
651+   If additional *iterable* arguments are passed, *function* must take that many
633-   and is applied to the items of all lists in parallel; if a list is shorter than
652+   arguments and is applied to the items from all iterables in parallel.  If one
634-   another it is assumed to be extended with ``None`` items.  If *function* is
653+   iterable is shorter than another it is assumed to be extended with ``None``
635-   ``None``, the identity function is assumed; if there are multiple list
654+   items.  If *function* is ``None``, the identity function is assumed; if there
636-   arguments, :func:`map` returns a list consisting of tuples containing the
655+   are multiple arguments, :func:`map` returns a list consisting of tuples
637-   corresponding items from all lists (a kind of transpose operation).  The *list*
656+   containing the corresponding items from all iterables (a kind of transpose
638-   arguments may be any kind of sequence; the result is always a list.
657+   operation).  The *iterable* arguments may be a sequence  or any iterable object;
658+   the result is always a list.
639
640
n641-.. function:: max(s[, args...][key])
n661+.. function:: max(iterable[, args...][key])
642
n643-   With a single argument *s*, return the largest item of a non-empty sequence
n663+   With a single argument *iterable*, return the largest item of a non-empty
644-   (such as a string, tuple or list).  With more than one argument, return the
664+   iterable (such as a string, tuple or list).  With more than one argument, return
645-   largest of the arguments.
665+   the largest of the arguments.
646
647   The optional *key* argument specifies a one-argument ordering function like that
648   used for :meth:`list.sort`.  The *key* argument, if supplied, must be in keyword
649   form (for example, ``max(a,b,c,key=func)``).
650
651   .. versionchanged:: 2.5
652      Added support for the optional *key* argument.
653
654
n655-.. function:: min(s[, args...][key])
n675+.. function:: min(iterable[, args...][key])
656
n657-   With a single argument *s*, return the smallest item of a non-empty sequence
n677+   With a single argument *iterable*, return the smallest item of a non-empty
658-   (such as a string, tuple or list).  With more than one argument, return the
678+   iterable (such as a string, tuple or list).  With more than one argument, return
659-   smallest of the arguments.
679+   the smallest of the arguments.
660
661   The optional *key* argument specifies a one-argument ordering function like that
662   used for :meth:`list.sort`.  The *key* argument, if supplied, must be in keyword
663   form (for example, ``min(a,b,c,key=func)``).
664
665   .. versionchanged:: 2.5
666      Added support for the optional *key* argument.
667
668
n689+.. function:: next(iterator[, default])
690+ 
691+   Retrieve the next item from the *iterator* by calling its :meth:`next`
692+   method.  If *default* is given, it is returned if the iterator is exhausted,
693+   otherwise :exc:`StopIteration` is raised.
694+ 
695+   .. versionadded:: 2.6
696+ 
697+ 
669.. function:: object()
670
671   Return a new featureless object.  :class:`object` is a base for all new style
672   classes.  It has the methods that are common to all instances of new style
673   classes.
674
675   .. versionadded:: 2.2
676
685   valid Python expression.
686
687   .. versionchanged:: 2.4
688      Formerly only returned an unsigned literal.
689
690
691.. function:: open(filename[, mode[, bufsize]])
692
n693-   Open a file, returning an object of the :class:`file` type described in section
n722+   Open a file, returning an object of the :class:`file` type described in
694-   :ref:`bltin-file-objects`, "File Objects (XXX reference: bltin-file-
723+   section :ref:`bltin-file-objects`.  If the file cannot be opened,
695-   objects.html)".  If the file cannot be opened, :exc:`IOError` is raised.  When
724+   :exc:`IOError` is raised.  When opening a file, it's preferable to use
696-   opening a file, it's preferable to use :func:`open` instead of invoking the
725+   :func:`open` instead of invoking the :class:`file` constructor directly.
697-   :class:`file` constructor directly.
698
699   The first two arguments are the same as for ``stdio``'s :cfunc:`fopen`:
700   *filename* is the file name to be opened, and *mode* is a string indicating how
701   the file is to be opened.
702
703   The most commonly-used values of *mode* are ``'r'`` for reading, ``'w'`` for
704   writing (truncating the file if it already exists), and ``'a'`` for appending
705   (which on *some* Unix systems means that *all* writes append to the end of the
706   file regardless of the current seek position).  If *mode* is omitted, it
n735+   defaults to ``'r'``.  The default is to use text mode, which may convert
736+   ``'\n'`` characters to a platform-specific representation on writing and back
707-   defaults to ``'r'``.  When opening a binary file, you should append ``'b'`` to
737+   on reading.  Thus, when opening a binary file, you should append ``'b'`` to
708   the *mode* value to open the file in binary mode, which will improve
709   portability.  (Appending ``'b'`` is useful even on systems that don't treat
710   binary and text files differently, where it serves as documentation.)  See below
711   for more possible values of *mode*.
712
713   .. index::
714      single: line-buffered I/O
715      single: unbuffered I/O
736   without universal newline support a *mode* with ``'U'`` is the same as normal
737   text mode.  Note that file objects so opened also have an attribute called
738   :attr:`newlines` which has a value of ``None`` (if no newlines have yet been
739   seen), ``'\n'``, ``'\r'``, ``'\r\n'``, or a tuple containing all the newline
740   types seen.
741
742   Python enforces that the mode, after stripping ``'U'``, begins with ``'r'``,
743   ``'w'`` or ``'a'``.
n774+ 
775+   Python provides many file handling modules including
776+   :mod:`fileinput`, :mod:`os`, :mod:`os.path`, :mod:`tempfile`, and
777+   :mod:`shutil`.
744
745   .. versionchanged:: 2.5
746      Restriction on first letter of mode string introduced.
747
748
749.. function:: ord(c)
750
751   Given a string of length one, return an integer representing the Unicode code
774   argument was negative, an exception was raised.) If the second argument is
775   negative, the third argument must be omitted. If *z* is present, *x* and *y*
776   must be of integer types, and *y* must be non-negative.  (This restriction was
777   added in Python 2.2.  In Python 2.1 and before, floating 3-argument ``pow()``
778   returned platform-dependent results depending on floating-point rounding
779   accidents.)
780
781
n816+.. function:: print([object, ...][, sep=' '][, end='\n'][, file=sys.stdout])
817+ 
818+   Print *object*\(s) to the stream *file*, separated by *sep* and followed by
819+   *end*.  *sep*, *end* and *file*, if present, must be given as keyword
820+   arguments.
821+ 
822+   All non-keyword arguments are converted to strings like :func:`str` does and
823+   written to the stream, separated by *sep* and followed by *end*.  Both *sep*
824+   and *end* must be strings; they can also be ``None``, which means to use the
825+   default values.  If no *object* is given, :func:`print` will just write
826+   *end*.
827+ 
828+   The *file* argument must be an object with a ``write(string)`` method; if it
829+   is not present or ``None``, :data:`sys.stdout` will be used.
830+ 
831+   .. note::
832+ 
833+      This function is not normally available as a builtin since the name
834+      ``print`` is recognized as the :keyword:`print` statement.  To disable the
835+      statement and use the :func:`print` function, use this future statement at
836+      the top of your module::
837+ 
838+         from __future__ import print_function
839+ 
840+   .. versionadded:: 2.6
841+ 
842+ 
782.. function:: property([fget[, fset[, fdel[, doc]]]])
783
n784-   Return a property attribute for new-style classes (classes that derive from
n845+   Return a property attribute for :term:`new-style class`\es (classes that
785-   :class:`object`).
846+   derive from :class:`object`).
786
787   *fget* is a function for getting an attribute value, likewise *fset* is a
788   function for setting, and *fdel* a function for del'ing, an attribute.  Typical
789   use is to define a managed attribute x::
790
791      class C(object):
n792-          def __init__(self): self.__x = None
n853+          def __init__(self):
854+              self._x = None
855+ 
793-          def getx(self): return self._x
856+          def getx(self):
857+              return self._x
794-          def setx(self, value): self._x = value
858+          def setx(self, value):
859+              self._x = value
795-          def delx(self): del self._x
860+          def delx(self):
861+              del self._x
796          x = property(getx, setx, delx, "I'm the 'x' property.")
797
798   If given, *doc* will be the docstring of the property attribute. Otherwise, the
799   property will copy *fget*'s docstring (if it exists).  This makes it possible to
n800-   create read-only properties easily using :func:`property` as a decorator::
n866+   create read-only properties easily using :func:`property` as a :term:`decorator`::
801
802      class Parrot(object):
803          def __init__(self):
804              self._voltage = 100000
805
806          @property
807          def voltage(self):
808              """Get the current voltage."""
809              return self._voltage
810
n811-   turns the :meth:`voltage` method into a "getter" for a read-only attribute with
n877+   turns the :meth:`voltage` method into a "getter" for a read-only attribute
812-   the same name.
878+   with the same name.
879+ 
880+   A property object has :attr:`getter`, :attr:`setter`, and :attr:`deleter`
881+   methods usable as decorators that create a copy of the property with the
882+   corresponding accessor function set to the decorated function.  This is
883+   best explained with an example::
884+ 
885+      class C(object):
886+          def __init__(self):
887+              self._x = None
888+ 
889+          @property
890+          def x(self):
891+              """I'm the 'x' property."""
892+              return self._x
893+ 
894+          @x.setter
895+          def x(self, value):
896+              self._x = value
897+ 
898+          @x.deleter
899+          def x(self):
900+              del self._x
901+ 
902+   This code is exactly equivalent to the first example.  Be sure to give the
903+   additional functions the same name as the original property (``x`` in this
904+   case.)
905+ 
906+   The returned property also has the attributes ``fget``, ``fset``, and
907+   ``fdel`` corresponding to the constructor arguments.
813
814   .. versionadded:: 2.2
815
816   .. versionchanged:: 2.5
817      Use *fget*'s docstring if no *doc* given.
n913+ 
914+   .. versionchanged:: 2.6
915+      The ``getter``, ``setter``, and ``deleter`` attributes were added.
818
819
820.. function:: range([start,] stop[, step])
821
822   This is a versatile function to create lists containing arithmetic progressions.
823   It is most often used in :keyword:`for` loops.  The arguments must be plain
824   integers.  If the *step* argument is omitted, it defaults to ``1``.  If the
825   *start* argument is omitted, it defaults to ``0``.  The full form returns a list
826   of plain integers ``[start, start + step, start + 2 * step, ...]``.  If *step*
827   is positive, the last element is the largest ``start + i * step`` less than
828   *stop*; if *step* is negative, the last element is the smallest ``start + i *
829   step`` greater than *stop*.  *step* must not be zero (or else :exc:`ValueError`
n830-   is raised).  Example::
n928+   is raised).  Example:
831
832      >>> range(10)
833      [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
834      >>> range(1, 11)
835      [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
836      >>> range(0, 30, 5)
837      [0, 5, 10, 15, 20, 25]
838      >>> range(0, 10, 3)
856      --> Monty Python's Flying Circus
857      >>> s
858      "Monty Python's Flying Circus"
859
860   If the :mod:`readline` module was loaded, then :func:`raw_input` will use it to
861   provide elaborate line editing and history features.
862
863
n864-.. function:: reduce(function, sequence[, initializer])
n962+.. function:: reduce(function, iterable[, initializer])
865
n866-   Apply *function* of two arguments cumulatively to the items of *sequence*, from
n964+   Apply *function* of two arguments cumulatively to the items of *iterable*, from
867-   left to right, so as to reduce the sequence to a single value.  For example,
965+   left to right, so as to reduce the iterable to a single value.  For example,
868   ``reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])`` calculates ``((((1+2)+3)+4)+5)``.
869   The left argument, *x*, is the accumulated value and the right argument, *y*, is
n870-   the update value from the *sequence*.  If the optional *initializer* is present,
n968+   the update value from the *iterable*.  If the optional *initializer* is present,
871-   it is placed before the items of the sequence in the calculation, and serves as
969+   it is placed before the items of the iterable in the calculation, and serves as
872-   a default when the sequence is empty.  If *initializer* is not given and
970+   a default when the iterable is empty.  If *initializer* is not given and
873-   *sequence* contains only one item, the first item is returned.
971+   *iterable* contains only one item, the first item is returned.
874
875
876.. function:: reload(module)
877
878   Reload a previously imported *module*.  The argument must be a module object, so
879   it must have been successfully imported before.  This is useful if you have
880   edited the module source file using an external editor and want to try out the
881   new version without leaving the Python interpreter.  The return value is the
882   module object (the same as the *module* argument).
883
884   When ``reload(module)`` is executed:
885
n886-* Python modules' code is recompiled and the module-level code reexecuted,
n984+   * Python modules' code is recompiled and the module-level code reexecuted,
887     defining a new set of objects which are bound to names in the module's
888     dictionary.  The ``init`` function of extension modules is not called a second
889     time.
890
n891-* As with all other objects in Python the old objects are only reclaimed after
n989+   * As with all other objects in Python the old objects are only reclaimed after
892     their reference counts drop to zero.
893
n894-* The names in the module namespace are updated to point to any new or changed
n992+   * The names in the module namespace are updated to point to any new or changed
895     objects.
896
n897-* Other references to the old objects (such as names external to the module) are
n995+   * Other references to the old objects (such as names external to the module) are
898     not rebound to refer to the new objects and must be updated in each namespace
899     where they occur if that is desired.
900
901   There are a number of other caveats:
902
903   If a module is syntactically correct but its initialization fails, the first
904   :keyword:`import` statement for it does not bind its name locally, but does
905   store a (partially initialized) module object in ``sys.modules``.  To reload the
932
933   If a module instantiates instances of a class, reloading the module that defines
934   the class does not affect the method definitions of the instances --- they
935   continue to use the old class definition.  The same is true for derived classes.
936
937
938.. function:: repr(object)
939
n940-   Return a string containing a printable representation of an object. This is the
n1038+   Return a string containing a printable representation of an object.  This is
941-   same value yielded by conversions (reverse quotes). It is sometimes useful to be
1039+   the same value yielded by conversions (reverse quotes).  It is sometimes
942-   able to access this operation as an ordinary function.  For many types, this
1040+   useful to be able to access this operation as an ordinary function.  For many
943-   function makes an attempt to return a string that would yield an object with the
1041+   types, this function makes an attempt to return a string that would yield an
944-   same value when passed to :func:`eval`.
1042+   object with the same value when passed to :func:`eval`, otherwise the
1043+   representation is a string enclosed in angle brackets that contains the name
1044+   of the type of the object together with additional information often
1045+   including the name and address of the object.  A class can control what this
1046+   function returns for its instances by defining a :meth:`__repr__` method.
945
946
947.. function:: reversed(seq)
948
n949-   Return a reverse iterator.  *seq* must be an object which supports the sequence
n1051+   Return a reverse :term:`iterator`.  *seq* must be an object which has
1052+   a :meth:`__reversed__` method or supports the sequence protocol (the
950-   protocol (th__len__() method and the :meth:`__getitem__` method with integer
1053+   :meth:`__len__` method and the :meth:`__getitem__` method with integer
951   arguments starting at ``0``).
952
953   .. versionadded:: 2.4
n1057+ 
1058+   .. versionchanged:: 2.6
1059+      Added the possibility to write a custom :meth:`__reversed__` method.
954
955
956.. function:: round(x[, n])
957
958   Return the floating point value *x* rounded to *n* digits after the decimal
959   point.  If *n* is omitted, it defaults to zero. The result is a floating point
960   number.  Values are rounded to the closest multiple of 10 to the power minus
961   *n*; if two multiples are equally close, rounding is done away from 0 (so. for
962   example, ``round(0.5)`` is ``1.0`` and ``round(-0.5)`` is ``-1.0``).
963
964
965.. function:: set([iterable])
n1072+   :noindex:
966
n967-   Return a set whose elements are taken from *iterable*.  The elements must be
n1074+   Return a new set, optionally with elements are taken from *iterable*.
968-   immutable.  To represent sets of sets, the inner sets should be
1075+   The set type is described in :ref:`types-set`.
969-   :class:`frozenset` objects.  If *iterable* is not specified, returns a new empty
1076+ 
970-   set, ``set([])``.
1077+   For other containers see the built in :class:`dict`, :class:`list`, and
1078+   :class:`tuple` classes, and the :mod:`collections` module.
971
972   .. versionadded:: 2.4
973
974
975.. function:: setattr(object, name, value)
976
977   This is the counterpart of :func:`getattr`.  The arguments are an object, a
978   string and an arbitrary value.  The string may name an existing attribute or a
980   object allows it.  For example, ``setattr(x, 'foobar', 123)`` is equivalent to
981   ``x.foobar = 123``.
982
983
984.. function:: slice([start,] stop[, step])
985
986   .. index:: single: Numerical Python
987
n988-   Return a slice object representing the set of indices specified by
n1096+   Return a :term:`slice` object representing the set of indices specified by
989   ``range(start, stop, step)``.  The *start* and *step* arguments default to
990   ``None``.  Slice objects have read-only data attributes :attr:`start`,
991   :attr:`stop` and :attr:`step` which merely return the argument values (or their
992   default).  They have no other explicit functionality; however they are used by
993   Numerical Python and other third party extensions.  Slice objects are also
994   generated when extended indexing syntax is used.  For example:
n995-   ``a[start:stop:step]`` or ``a[start:stop, i]``.
n1103+   ``a[start:stop:step]`` or ``a[start:stop, i]``.  See :func:`itertools.islice`
1104+   for an alternate version that returns an iterator.
996
997
998.. function:: sorted(iterable[, cmp[, key[, reverse]]])
999
1000   Return a new sorted list from the items in *iterable*.
1001
1002   The optional arguments *cmp*, *key*, and *reverse* have the same meaning as
1003   those for the :meth:`list.sort` method (described in section
1004   :ref:`typesseq-mutable`).
1005
1006   *cmp* specifies a custom comparison function of two arguments (iterable
1007   elements) which should return a negative, zero or positive number depending on
1008   whether the first argument is considered smaller than, equal to, or larger than
n1009-   the second argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``
n1118+   the second argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``.  The default
1119+   value is ``None``.
1010
1011   *key* specifies a function of one argument that is used to extract a comparison
n1012-   key from each list element: ``key=str.lower``
n1122+   key from each list element: ``key=str.lower``.  The default value is ``None``.
1013
1014   *reverse* is a boolean value.  If set to ``True``, then the list elements are
1015   sorted as if each comparison were reversed.
1016
n1017-   In general, the *key* and *reverse* conversion processes are much faster than
n1127+   In general, the *key* and *reverse* conversion processes are much faster
1018-   specifying an equivalent *cmp* function.  This is because *cmp* is called
1128+   than specifying an equivalent *cmp* function.  This is because *cmp* is
1019-   multiple times for each list element while *key* and *reverse* touch each
1129+   called multiple times for each list element while *key* and *reverse* touch
1020-   element only once.
1130+   each element only once.  To convert an old-style *cmp* function to a *key*
1131+   function, see the `CmpToKey recipe in the ASPN cookbook
1132+   <http://code.activestate.com/recipes/576653/>`_\.
1021
1022   .. versionadded:: 2.4
1023
1024
1025.. function:: staticmethod(function)
1026
1027   Return a static method for *function*.
1028
1029   A static method does not receive an implicit first argument. To declare a static
1030   method, use this idiom::
1031
1032      class C:
1033          @staticmethod
1034          def f(arg1, arg2, ...): ...
1035
n1036-   The ``@staticmethod`` form is a function decorator -- see the description of
n1148+   The ``@staticmethod`` form is a function :term:`decorator` -- see the
1037-   function definitions in chapter 7 of the Python Reference Manual (XXX reference:
1149+   description of function definitions in :ref:`function` for details.
1038-   ../ref/function.html) for details.
1039
1040   It can be called either on the class (such as ``C.f()``) or on an instance (such
1041   as ``C().f()``).  The instance is ignored except for its class.
1042
1043   Static methods in Python are similar to those found in Java or C++. For a more
1044   advanced concept, see :func:`classmethod` in this section.
1045
1046   For more information on static methods, consult the documentation on the
n1047-   standard type hierarchy in chapter 3 of the Python Reference Manual (XXX
n1158+   standard type hierarchy in :ref:`types`.
1048-   reference: ../ref/types.html) (at the bottom).
1049
1050   .. versionadded:: 2.2
1051
1052   .. versionchanged:: 2.4
1053      Function decorator syntax added.
1054
1055
1056.. function:: str([object])
1057
1058   Return a string containing a nicely printable representation of an object.  For
1059   strings, this returns the string itself.  The difference with ``repr(object)``
1060   is that ``str(object)`` does not always attempt to return a string that is
1061   acceptable to :func:`eval`; its goal is to return a printable string.  If no
1062   argument is given, returns the empty string, ``''``.
1063
n1174+   For more information on strings see :ref:`typesseq` which describes sequence
1175+   functionality (strings are sequences), and also the string-specific methods
1176+   described in the :ref:`string-methods` section. To output formatted strings
1177+   use template strings or the ``%`` operator described in the
1178+   :ref:`string-formatting` section. In addition see the :ref:`stringservices`
1179+   section. See also :func:`unicode`.
1064
n1181+ 
1065-.. function:: sum(sequence[, start])
1182+.. function:: sum(iterable[, start])
1066
n1067-   Sums *start* and the items of a *sequence*, from left to right, and returns the
n1184+   Sums *start* and the items of an *iterable* from left to right and returns the
1068-   total.  *start* defaults to ``0``. The *sequence*'s items are normally numbers,
1185+   total.  *start* defaults to ``0``. The *iterable*'s items are normally numbers,
1069-   and are not allowed to be strings.  The fast, correct way to concatenate
1186+   and are not allowed to be strings.  The fast, correct way to concatenate a
1070   sequence of strings is by calling ``''.join(sequence)``. Note that
1071   ``sum(range(n), m)`` is equivalent to ``reduce(operator.add, range(n), m)``
n1189+   To add floating point values with extended precision, see :func:`math.fsum`\.
1072
1073   .. versionadded:: 2.3
1074
1075
1076.. function:: super(type[, object-or-type])
1077
n1078-   Return the superclass of *type*.  If the second argument is omitted the super
n1196+   Return a proxy object that delegates method calls to a parent or sibling
1079-   object returned is unbound.  If the second argument is an object,
1197+   class of *type*.  This is useful for accessing inherited methods that have
1080-   ``isinstance(obj, type)`` must be true.  If the second argument is a type,
1198+   been overridden in a class. The search order is same as that used by
1081-   ``issubclass(type2, type)`` must be true. :func:`super` only works for new-style
1199+   :func:`getattr` except that the *type* itself is skipped.
1082-   classes.
1083
n1084-   A typical use for calling a cooperative superclass method is::
n1201+   The :attr:`__mro__` attribute of the *type* lists the method resolution
1202+   search order used by both :func:`getattr` and :func:`super`.  The attribute
1203+   is dynamic and can change whenever the inheritance hierarchy is updated.
1204+ 
1205+   If the second argument is omitted, the super object returned is unbound.  If
1206+   the second argument is an object, ``isinstance(obj, type)`` must be true.  If
1207+   the second argument is a type, ``issubclass(type2, type)`` must be true (this
1208+   is useful for classmethods).
1209+ 
1210+   .. note::
1211+      :func:`super` only works for :term:`new-style class`\es.
1212+ 
1213+   There are two typical use cases for *super*.  In a class hierarchy with
1214+   single inheritance, *super* can be used to refer to parent classes without
1215+   naming them explicitly, thus making the code more maintainable.  This use
1216+   closely parallels the use of *super* in other programming languages.
1217+ 
1218+   The second use case is to support cooperative multiple inheritance in a
1219+   dynamic execution environment.  This use case is unique to Python and is
1220+   not found in statically compiled languages or languages that only support
1221+   single inheritance.  This makes it possible to implement "diamond diagrams"
1222+   where multiple base classes implement the same method.  Good design dictates
1223+   that this method have the same calling signature in every case (because the
1224+   order of calls is determined at runtime, because that order adapts
1225+   to changes in the class hierarchy, and because that order can include
1226+   sibling classes that are unknown prior to runtime).
1227+ 
1228+   For both use cases, a typical superclass call looks like this::
1085
1086      class C(B):
n1087-          def meth(self, arg):
n1231+          def method(self, arg):
1088-              super(C, self).meth(arg)
1232+              super(C, self).method(arg)
1089
1090   Note that :func:`super` is implemented as part of the binding process for
n1091-   explicit dotted attribute lookups such as ``super(C, self).__getitem__(name)``.
n1235+   explicit dotted attribute lookups such as ``super().__getitem__(name)``.
1236+   It does so by implementing its own :meth:`__getattribute__` method for searching
1237+   classes in a predictable order that supports cooperative multiple inheritance.
1092   Accordingly, :func:`super` is undefined for implicit lookups using statements or
n1093-   operators such as ``super(C, self)[name]``.
n1239+   operators such as ``super()[name]``.
1240+ 
1241+   Also note that :func:`super` is not limited to use inside methods.  The two
1242+   argument form specifies the arguments exactly and makes the appropriate
1243+   references.
1094
1095   .. versionadded:: 2.2
1096
1097
n1098-.. function:: tuple([sequence])
n1248+.. function:: tuple([iterable])
1099
n1100-   Return a tuple whose items are the same and in the same order as *sequence*'s
n1250+   Return a tuple whose items are the same and in the same order as *iterable*'s
1101-   items.  *sequence* may be a sequence, a container that supports iteration, or an
1251+   items.  *iterable* may be a sequence, a container that supports iteration, or an
1102-   iterator object. If *sequence* is already a tuple, it is returned unchanged.
1252+   iterator object. If *iterable* is already a tuple, it is returned unchanged.
1103   For instance, ``tuple('abc')`` returns ``('a', 'b', 'c')`` and ``tuple([1, 2,
1104   3])`` returns ``(1, 2, 3)``.  If no argument is given, returns a new empty
1105   tuple, ``()``.
1106
n1257+   :class:`tuple` is an immutable sequence type, as documented in
1258+   :ref:`typesseq`. For other containers see the built in :class:`dict`,
1259+   :class:`list`, and :class:`set` classes, and the :mod:`collections` module.
1260+ 
1107
1108.. function:: type(object)
1109
1110   .. index:: object: type
1111
1112   Return the type of an *object*.  The return value is a type object.  The
1113   :func:`isinstance` built-in function is recommended for testing the type of an
1114   object.
1115
1116   With three arguments, :func:`type` functions as a constructor as detailed below.
1117
1118
1119.. function:: type(name, bases, dict)
n1274+   :noindex:
1120
1121   Return a new type object.  This is essentially a dynamic form of the
1122   :keyword:`class` statement. The *name* string is the class name and becomes the
1123   :attr:`__name__` attribute; the *bases* tuple itemizes the base classes and
1124   becomes the :attr:`__bases__` attribute; and the *dict* dictionary is the
1125   namespace containing definitions for class body and becomes the :attr:`__dict__`
1126   attribute.  For example, the following two statements create identical
n1127-   :class:`type` objects::
n1282+   :class:`type` objects:
1128
1129      >>> class X(object):
1130      ...     a = 1
n1131-      ...     
n1286+      ...
1132      >>> X = type('X', (object,), dict(a=1))
1133
1134   .. versionadded:: 2.2
1135
1136
1137.. function:: unichr(i)
1138
1139   Return the Unicode string of one character whose Unicode code is the integer
1140   *i*.  For example, ``unichr(97)`` returns the string ``u'a'``.  This is the
1141   inverse of :func:`ord` for Unicode strings.  The valid range for the argument
1142   depends how Python was configured -- it may be either UCS2 [0..0xFFFF] or UCS4
n1143-   [0..0x10FFFF]. :exc:`ValueError` is raised otherwise.
n1298+   [0..0x10FFFF]. :exc:`ValueError` is raised otherwise. For ASCII and 8-bit
1299+   strings see :func:`chr`.
1144
1145   .. versionadded:: 2.0
1146
1147
1148.. function:: unicode([object[, encoding [, errors]]])
1149
1150   Return the Unicode string version of *object* using one of the following modes:
1151
1165   precisely, if *object* is a Unicode string or subclass it will return that
1166   Unicode string without any additional decoding applied.
1167
1168   For objects which provide a :meth:`__unicode__` method, it will call this method
1169   without arguments to create a Unicode string. For all other objects, the 8-bit
1170   string version or representation is requested and then converted to a Unicode
1171   string using the codec for the default encoding in ``'strict'`` mode.
1172
n1329+   For more information on Unicode strings see :ref:`typesseq` which describes
1330+   sequence functionality (Unicode strings are sequences), and also the
1331+   string-specific methods described in the :ref:`string-methods` section. To
1332+   output formatted strings use template strings or the ``%`` operator described
1333+   in the :ref:`string-formatting` section. In addition see the
1334+   :ref:`stringservices` section. See also :func:`str`.
1335+ 
1173   .. versionadded:: 2.0
1174
1175   .. versionchanged:: 2.2
1176      Support for :meth:`__unicode__` added.
1177
1178
1179.. function:: vars([object])
1180
1181   Without arguments, return a dictionary corresponding to the current local symbol
1182   table.  With a module, class or class instance object as argument (or anything
1183   else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
n1347+   to the object's symbol table.
1348+ 
1349+   .. warning::
1350+ 
1184-   to the object's symbol table.  The returned dictionary should not be modified:
1351+      The returned dictionary should not be modified:
1185-   the effects on the corresponding symbol table are undefined. [#]_
1352+      the effects on the corresponding symbol table are undefined. [#]_
1186
1187
1188.. function:: xrange([start,] stop[, step])
1189
1190   This function is very similar to :func:`range`, but returns an "xrange object"
1191   instead of a list.  This is an opaque sequence type which yields the same values
1192   as the corresponding list, without actually storing them all simultaneously.
1193   The advantage of :func:`xrange` over :func:`range` is minimal (since
1196   elements are never used (such as when the loop is usually terminated with
1197   :keyword:`break`).
1198
1199   .. note::
1200
1201      :func:`xrange` is intended to be simple and fast. Implementations may impose
1202      restrictions to achieve this. The C implementation of Python restricts all
1203      arguments to native C longs ("short" Python integers), and also requires that
n1204-      the number of elements fit in a native C long.
n1371+      the number of elements fit in a native C long.  If a larger range is needed,
1372+      an alternate version can be crafted using the :mod:`itertools` module:
1373+      ``islice(count(start, step), (stop-start+step-1)//step)``.
1205
1206
1207.. function:: zip([iterable, ...])
1208
1209   This function returns a list of tuples, where the *i*-th tuple contains the
1210   *i*-th element from each of the argument sequences or iterables. The returned
1211   list is truncated in length to the length of the shortest argument sequence.
1212   When there are multiple arguments which are all of the same length, :func:`zip`
1213   is similar to :func:`map` with an initial argument of ``None``. With a single
1214   sequence argument, it returns a list of 1-tuples. With no arguments, it returns
1215   an empty list.
1216
n1386+   The left-to-right evaluation order of the iterables is guaranteed. This
1387+   makes possible an idiom for clustering a data series into n-length groups
1388+   using ``zip(*[iter(s)]*n)``.
1389+ 
1390+   :func:`zip` in conjunction with the ``*`` operator can be used to unzip a
1391+   list::
1392+ 
1393+      >>> x = [1, 2, 3]
1394+      >>> y = [4, 5, 6]
1395+      >>> zipped = zip(x, y)
1396+      >>> zipped
1397+      [(1, 4), (2, 5), (3, 6)]
1398+      >>> x2, y2 = zip(*zipped)
1399+      >>> x == x2, y == y2
1400+      True
1401+ 
1217   .. versionadded:: 2.0
1218
1219   .. versionchanged:: 2.4
1220      Formerly, :func:`zip` required at least one argument and ``zip()`` raised a
1221      :exc:`TypeError` instead of returning an empty list.
1222
n1408+ 
1409+.. function:: __import__(name[, globals[, locals[, fromlist[, level]]]])
1410+ 
1411+   .. index::
1412+      statement: import
1413+      module: imp
1414+ 
1415+   .. note::
1416+ 
1417+      This is an advanced function that is not needed in everyday Python
1418+      programming.
1419+ 
1420+   This function is invoked by the :keyword:`import` statement.  It can be
1421+   replaced (by importing the :mod:`builtins` module and assigning to
1422+   ``builtins.__import__``) in order to change semantics of the
1423+   :keyword:`import` statement, but nowadays it is usually simpler to use import
1424+   hooks (see :pep:`302`).  Direct use of :func:`__import__` is rare, except in
1425+   cases where you want to import a module whose name is only known at runtime.
1426+ 
1427+   The function imports the module *name*, potentially using the given *globals*
1428+   and *locals* to determine how to interpret the name in a package context.
1429+   The *fromlist* gives the names of objects or submodules that should be
1430+   imported from the module given by *name*.  The standard implementation does
1431+   not use its *locals* argument at all, and uses its *globals* only to
1432+   determine the package context of the :keyword:`import` statement.
1433+ 
1434+   *level* specifies whether to use absolute or relative imports.  The default
1435+   is ``-1`` which indicates both absolute and relative imports will be
1436+   attempted.  ``0`` means only perform absolute imports.  Positive values for
1437+   *level* indicate the number of parent directories to search relative to the
1438+   directory of the module calling :func:`__import__`.
1439+ 
1440+   When the *name* variable is of the form ``package.module``, normally, the
1441+   top-level package (the name up till the first dot) is returned, *not* the
1442+   module named by *name*.  However, when a non-empty *fromlist* argument is
1443+   given, the module named by *name* is returned.
1444+ 
1445+   For example, the statement ``import spam`` results in bytecode resembling the
1446+   following code::
1447+ 
1448+      spam = __import__('spam', globals(), locals(), [], -1)
1449+ 
1450+   The statement ``import spam.ham`` results in this call::
1451+ 
1452+      spam = __import__('spam.ham', globals(), locals(), [], -1)
1453+ 
1454+   Note how :func:`__import__` returns the toplevel module here because this is
1455+   the object that is bound to a name by the :keyword:`import` statement.
1456+ 
1457+   On the other hand, the statement ``from spam.ham import eggs, sausage as
1458+   saus`` results in ::
1459+ 
1460+      _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], -1)
1461+      eggs = _temp.eggs
1462+      saus = _temp.sausage
1463+ 
1464+   Here, the ``spam.ham`` module is returned from :func:`__import__`.  From this
1465+   object, the names to import are retrieved and assigned to their respective
1466+   names.
1467+ 
1468+   If you simply want to import a module (potentially within a package) by name,
1469+   you can get it from :data:`sys.modules`::
1470+ 
1471+      >>> import sys
1472+      >>> name = 'foo.bar.baz'
1473+      >>> __import__(name)
1474+      <module 'foo' from ...>
1475+      >>> baz = sys.modules[name]
1476+      >>> baz
1477+      <module 'foo.bar.baz' from ...>
1478+ 
1479+   .. versionchanged:: 2.5
1480+      The level parameter was added.
1481+ 
1482+   .. versionchanged:: 2.5
1483+      Keyword support for parameters was added.
1484+ 
1223-.. % ---------------------------------------------------------------------------
1485+..  ---------------------------------------------------------------------------
1224
1225
1226.. _non-essential-built-in-funcs:
1227
1228Non-essential Built-in Functions
1229================================
1230
1231There are several built-in functions that are no longer essential to learn, know
1232or use in modern Python programming.  They have been kept here to maintain
1233backwards compatibility with programs written for older versions of Python.
1234
n1235-Python programmers, trainers, students and bookwriters should feel free to
n1497+Python programmers, trainers, students and book writers should feel free to
1236bypass these functions without concerns about missing something important.
1237
1238
1239.. function:: apply(function, args[, keywords])
1240
1241   The *function* argument must be a callable object (a user-defined or built-in
1242   function or method, or a class object) and the *args* argument must be a
1243   sequence.  The *function* is called with *args* as the argument list; the number
1244   of arguments is the length of the tuple. If the optional *keywords* argument is
1245   present, it must be a dictionary whose keys are strings.  It specifies keyword
1246   arguments to be added to the end of the argument list. Calling :func:`apply` is
1247   different from just calling ``function(args)``, since in that case there is
1248   always exactly one argument.  The use of :func:`apply` is equivalent to
n1249-   ``function(*args, **keywords)``. Use of :func:`apply` is not necessary since the
n1511+   ``function(*args, **keywords)``.
1250-   "extended call syntax," as used in the last example, is completely equivalent.
1251
1252   .. deprecated:: 2.3
t1253-      Use the extended call syntax instead, as described above.
t1514+      Use the extended call syntax with ``*args`` and ``**keywords`` instead.
1254
1255
1256.. function:: buffer(object[, offset[, size]])
1257
1258   The *object* argument must be an object that supports the buffer call interface
1259   (such as strings, arrays, and buffers).  A new buffer object will be created
1260   which references the *object* argument. The buffer object will be a slice from
1261   the beginning of *object* (or from the specified *offset*). The slice will
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op