cpython-lru_cache-weakref: Doc/library/functions.rst annotate

annotate Doc/library/functions.rst @ 54294:dba767bc3155 legacy-trunk

remove mention of old ctypes version

author	Benjamin Peterson <benjamin@python.org>
date	Sat, 23 May 2009 20:59:09 +0000
parents	840a09de68c3
children	8ad7fc809f68

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 .. _built-in-funcs:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 Built-in Functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 ==================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 The Python interpreter has a number of functions built into it that are always
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 available. They are listed here in alphabetical order.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 .. function:: abs(x)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 Return the absolute value of a number. The argument may be a plain or long
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 integer or a floating point number. If the argument is a complex number, its
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 magnitude is returned.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 .. function:: all(iterable)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19
53175 1f5f992801f9 Clarify the behavior of any() and all() with an empty iterable. Raymond Hettinger <python@rcn.com> parents: 52749 diff changeset	20 Return True if all elements of the iterable are true (or if the iterable
1f5f992801f9 Clarify the behavior of any() and all() with an empty iterable. Raymond Hettinger <python@rcn.com> parents: 52749 diff changeset	21 is empty). Equivalent to::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 def all(iterable):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 for element in iterable:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 if not element:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 return False
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 return True
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 .. function:: any(iterable)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33
53175 1f5f992801f9 Clarify the behavior of any() and all() with an empty iterable. Raymond Hettinger <python@rcn.com> parents: 52749 diff changeset	34 Return True if any element of the iterable is true. If the iterable
1f5f992801f9 Clarify the behavior of any() and all() with an empty iterable. Raymond Hettinger <python@rcn.com> parents: 52749 diff changeset	35 is empty, return False. Equivalent to::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 def any(iterable):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 for element in iterable:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 if element:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 return True
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 return False
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 .. function:: basestring()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 This abstract type is the superclass for :class:`str` and :class:`unicode`. It
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 cannot be called or instantiated, but it can be used to test whether an object
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 is an instance of :class:`str` or :class:`unicode`. ``isinstance(obj,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 basestring)`` is equivalent to ``isinstance(obj, (str, unicode))``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55
49616 b0cccb55941c backport bin() documentation Benjamin Peterson <benjamin@python.org> parents: 49511 diff changeset	56 .. function:: bin(x)
b0cccb55941c backport bin() documentation Benjamin Peterson <benjamin@python.org> parents: 49511 diff changeset	57
b0cccb55941c backport bin() documentation Benjamin Peterson <benjamin@python.org> parents: 49511 diff changeset	58 Convert an integer number to a binary string. The result is a valid Python
b0cccb55941c backport bin() documentation Benjamin Peterson <benjamin@python.org> parents: 49511 diff changeset	59 expression. If x is not a Python :class:`int` object, it has to define an
b0cccb55941c backport bin() documentation Benjamin Peterson <benjamin@python.org> parents: 49511 diff changeset	60 :meth:`__index__` method that returns an integer.
b0cccb55941c backport bin() documentation Benjamin Peterson <benjamin@python.org> parents: 49511 diff changeset	61
b0cccb55941c backport bin() documentation Benjamin Peterson <benjamin@python.org> parents: 49511 diff changeset	62 .. versionadded:: 2.6
b0cccb55941c backport bin() documentation Benjamin Peterson <benjamin@python.org> parents: 49511 diff changeset	63
b0cccb55941c backport bin() documentation Benjamin Peterson <benjamin@python.org> parents: 49511 diff changeset	64
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 .. function:: bool([x])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 Convert a value to a Boolean, using the standard truth testing procedure. If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 x is false or omitted, this returns :const:`False`; otherwise it returns
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 :const:`True`. :class:`bool` is also a class, which is a subclass of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 :class:`int`. Class :class:`bool` cannot be subclassed further. Its only
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 instances are :const:`False` and :const:`True`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 .. index:: pair: Boolean; type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 .. versionadded:: 2.2.1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 If no argument is given, this function returns :const:`False`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 .. function:: callable(object)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 Return :const:`True` if the object argument appears callable,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 :const:`False` if not. If this
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 returns true, it is still possible that a call fails, but if it is false,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 calling object will never succeed. Note that classes are callable (calling a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 class returns a new instance); class instances are callable if they have a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 :meth:`__call__` method.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 .. function:: chr(i)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 Return a string of one character whose ASCII code is the integer i. For
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 example, ``chr(97)`` returns the string ``'a'``. This is the inverse of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 :func:`ord`. The argument must be in the range [0..255], inclusive;
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 :exc:`ValueError` will be raised if i is outside that range. See
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 also :func:`unichr`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 .. function:: classmethod(function)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 Return a class method for function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 A class method receives the class as implicit first argument, just like an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 instance method receives the instance. To declare a class method, use this
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 idiom::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 class C:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 @classmethod
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 def f(cls, arg1, arg2, ...): ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111
44103 1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 43748 diff changeset	112 The ``@classmethod`` form is a function :term:`decorator` -- see the description
1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 43748 diff changeset	113 of function definitions in :ref:`function` for details.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 It can be called either on the class (such as ``C.f()``) or on an instance (such
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 as ``C().f()``). The instance is ignored except for its class. If a class
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 method is called for a derived class, the derived class object is passed as the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 implied first argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 Class methods are different than C++ or Java static methods. If you want those,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 see :func:`staticmethod` in this section.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 For more information on class methods, consult the documentation on the standard
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 type hierarchy in :ref:`types`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 Function decorator syntax added.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 .. function:: cmp(x, y)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 Compare the two objects x and y and return an integer according to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 outcome. The return value is negative if ``x < y``, zero if ``x == y`` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 strictly positive if ``x > y``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 .. function:: compile(source, filename, mode[, flags[, dont_inherit]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140
46162 ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	141 Compile the source into a code or AST object. Code objects can be executed
ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	142 by an :keyword:`exec` statement or evaluated by a call to :func:`eval`.
49689 20a40894539a a few compile() and ast doc improvements Benjamin Peterson <benjamin@python.org> parents: 49616 diff changeset	143 source can either be a string or an AST object. Refer to the :mod:`ast`
20a40894539a a few compile() and ast doc improvements Benjamin Peterson <benjamin@python.org> parents: 49616 diff changeset	144 module documentation for information on how to work with AST objects.
46162 ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	145
ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	146 The filename argument should give the file from which the code was read;
ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	147 pass some recognizable value if it wasn't read from a file (``'<string>'`` is
ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	148 commonly used).
ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	149
ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	150 The mode argument specifies what kind of code must be compiled; it can be
ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	151 ``'exec'`` if source consists of a sequence of statements, ``'eval'`` if it
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 consists of a single expression, or ``'single'`` if it consists of a single
46162 ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	153 interactive statement (in the latter case, expression statements that
ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	154 evaluate to something else than ``None`` will be printed).
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155
49690 d34ccb0341ea move context clue to versionchanged tag Benjamin Peterson <benjamin@python.org> parents: 49689 diff changeset	156 The optional arguments flags and dont_inherit control which future
d34ccb0341ea move context clue to versionchanged tag Benjamin Peterson <benjamin@python.org> parents: 49689 diff changeset	157 statements (see :pep:`236`) affect the compilation of source. If neither
d34ccb0341ea move context clue to versionchanged tag Benjamin Peterson <benjamin@python.org> parents: 49689 diff changeset	158 is present (or both are zero) the code is compiled with those future
d34ccb0341ea move context clue to versionchanged tag Benjamin Peterson <benjamin@python.org> parents: 49689 diff changeset	159 statements that are in effect in the code that is calling compile. If the
d34ccb0341ea move context clue to versionchanged tag Benjamin Peterson <benjamin@python.org> parents: 49689 diff changeset	160 flags argument is given and dont_inherit is not (or is zero) then the
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 future statements specified by the flags argument are used in addition to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 those that would be used anyway. If dont_inherit is a non-zero integer then
49690 d34ccb0341ea move context clue to versionchanged tag Benjamin Peterson <benjamin@python.org> parents: 49689 diff changeset	163 the flags argument is it -- the future statements in effect around the call
d34ccb0341ea move context clue to versionchanged tag Benjamin Peterson <benjamin@python.org> parents: 49689 diff changeset	164 to compile are ignored.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165
44497 01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. Georg Brandl <georg@python.org> parents: 44488 diff changeset	166 Future statements are specified by bits which can be bitwise ORed together to
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 specify multiple statements. The bitfield required to specify a given feature
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 instance in the :mod:`__future__` module.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170
44533 b24888cb9553 #1499: Document compile() exceptions. Georg Brandl <georg@python.org> parents: 44532 diff changeset	171 This function raises :exc:`SyntaxError` if the compiled source is invalid,
b24888cb9553 #1499: Document compile() exceptions. Georg Brandl <georg@python.org> parents: 44532 diff changeset	172 and :exc:`TypeError` if the source contains null bytes.
b24888cb9553 #1499: Document compile() exceptions. Georg Brandl <georg@python.org> parents: 44532 diff changeset	173
49689 20a40894539a a few compile() and ast doc improvements Benjamin Peterson <benjamin@python.org> parents: 49616 diff changeset	174 .. note::
20a40894539a a few compile() and ast doc improvements Benjamin Peterson <benjamin@python.org> parents: 49616 diff changeset	175
20a40894539a a few compile() and ast doc improvements Benjamin Peterson <benjamin@python.org> parents: 49616 diff changeset	176 When compiling a string with multi-line statements, line endings must be
20a40894539a a few compile() and ast doc improvements Benjamin Peterson <benjamin@python.org> parents: 49616 diff changeset	177 represented by a single newline character (``'\n'``), and the input must
20a40894539a a few compile() and ast doc improvements Benjamin Peterson <benjamin@python.org> parents: 49616 diff changeset	178 be terminated by at least one newline character. If line endings are
20a40894539a a few compile() and ast doc improvements Benjamin Peterson <benjamin@python.org> parents: 49616 diff changeset	179 represented by ``'\r\n'``, use :meth:`str.replace` to change them into
20a40894539a a few compile() and ast doc improvements Benjamin Peterson <benjamin@python.org> parents: 49616 diff changeset	180 ``'\n'``.
20a40894539a a few compile() and ast doc improvements Benjamin Peterson <benjamin@python.org> parents: 49616 diff changeset	181
49690 d34ccb0341ea move context clue to versionchanged tag Benjamin Peterson <benjamin@python.org> parents: 49689 diff changeset	182 .. versionchanged:: 2.3
49693 bc4f742e2c1d clarify what was added Benjamin Peterson <benjamin@python.org> parents: 49690 diff changeset	183 The flags and dont_inherit arguments were added.
49690 d34ccb0341ea move context clue to versionchanged tag Benjamin Peterson <benjamin@python.org> parents: 49689 diff changeset	184
d34ccb0341ea move context clue to versionchanged tag Benjamin Peterson <benjamin@python.org> parents: 49689 diff changeset	185 .. versionchanged:: 2.6
46162 ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	186 Support for compiling AST objects.
ca38f7a4b4c9 Patch #1810 by Thomas Lee, reviewed by myself: Georg Brandl <georg@python.org> parents: 46067 diff changeset	187
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 .. function:: complex([real[, imag]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 Create a complex number with the value real + imag\*j or convert a string or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 number to a complex number. If the first parameter is a string, it will be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193 interpreted as a complex number and the function must be called without a second
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 parameter. The second parameter can never be a string. Each argument may be any
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 numeric type (including complex). If imag is omitted, it defaults to zero and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 the function serves as a numeric conversion function like :func:`int`,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 :func:`long` and :func:`float`. If both arguments are omitted, returns ``0j``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 The complex type is described in :ref:`typesnumeric`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 .. function:: delattr(object, name)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 This is a relative of :func:`setattr`. The arguments are an object and a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 string. The string must be the name of one of the object's attributes. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 function deletes the named attribute, provided the object allows it. For
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 .. function:: dict([arg])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 :noindex:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 Create a new data dictionary, optionally with items taken from arg.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 The dictionary type is described in :ref:`typesmapping`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 For other containers see the built in :class:`list`, :class:`set`, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 :class:`tuple` classes, and the :mod:`collections` module.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 .. function:: dir([object])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 Without arguments, return the list of names in the current local scope. With an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 argument, attempt to return a list of valid attributes for that object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 If the object has a method named :meth:`__dir__`, this method will be called and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 must return the list of attributes. This allows objects that implement a custom
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 :func:`__getattr__` or :func:`__getattribute__` function to customize the way
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 :func:`dir` reports their attributes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 If the object does not provide :meth:`__dir__`, the function tries its best to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 gather information from the object's :attr:`__dict__` attribute, if defined, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 from its type object. The resulting list is not necessarily complete, and may
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 be inaccurate when the object has a custom :func:`__getattr__`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 The default :func:`dir` mechanism behaves differently with different types of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 objects, as it attempts to produce the most relevant, rather than complete,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 information:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 * If the object is a module object, the list contains the names of the module's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 attributes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 * If the object is a type or class object, the list contains the names of its
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 attributes, and recursively of the attributes of its bases.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 * Otherwise, the list contains the object's attributes' names, the names of its
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 class's attributes, and recursively of the attributes of its class's base
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 classes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
46013 d6f0e3e556a4 Enable doctests in functions.rst. Already found two errors :) Georg Brandl <georg@python.org> parents: 45978 diff changeset	249 The resulting list is sorted alphabetically. For example:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 >>> import struct
46013 d6f0e3e556a4 Enable doctests in functions.rst. Already found two errors :) Georg Brandl <georg@python.org> parents: 45978 diff changeset	252 >>> dir() # doctest: +SKIP
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 ['__builtins__', '__doc__', '__name__', 'struct']
46013 d6f0e3e556a4 Enable doctests in functions.rst. Already found two errors :) Georg Brandl <georg@python.org> parents: 45978 diff changeset	254 >>> dir(struct) # doctest: +NORMALIZE_WHITESPACE
d6f0e3e556a4 Enable doctests in functions.rst. Already found two errors :) Georg Brandl <georg@python.org> parents: 45978 diff changeset	255 ['Struct', '__builtins__', '__doc__', '__file__', '__name__',
d6f0e3e556a4 Enable doctests in functions.rst. Already found two errors :) Georg Brandl <georg@python.org> parents: 45978 diff changeset	256 '__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
d6f0e3e556a4 Enable doctests in functions.rst. Already found two errors :) Georg Brandl <georg@python.org> parents: 45978 diff changeset	257 'unpack', 'unpack_from']
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258 >>> class Foo(object):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259 ... def __dir__(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 ... return ["kan", "ga", "roo"]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 >>> f = Foo()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 >>> dir(f)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 ['ga', 'kan', 'roo']
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 Because :func:`dir` is supplied primarily as a convenience for use at an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 interactive prompt, it tries to supply an interesting set of names more than it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270 tries to supply a rigorously or consistently defined set of names, and its
44527 64794ba9e25a #759525: document that dir() doesn't return metaclass attrs when given a class as arg. Georg Brandl <georg@python.org> parents: 44525 diff changeset	271 detailed behavior may change across releases. For example, metaclass attributes
64794ba9e25a #759525: document that dir() doesn't return metaclass attrs when given a class as arg. Georg Brandl <georg@python.org> parents: 44525 diff changeset	272 are not in the result list when the argument is a class.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275 .. function:: divmod(a, b)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 Take two (non complex) numbers as arguments and return a pair of numbers
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 consisting of their quotient and remainder when using long division. With mixed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 operand types, the rules for binary arithmetic operators apply. For plain and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 long integers, the result is the same as ``(a // b, a % b)``. For floating point
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 numbers the result is ``(q, a % b)``, where q is usually ``math.floor(a / b)``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 but may be 1 less than that. In any case ``q * b + a % b`` is very close to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283 a, if ``a % b`` is non-zero it has the same sign as b, and ``0 <= abs(a % b)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 < abs(b)``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 Using :func:`divmod` with complex numbers is deprecated.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289
46982 47692f6c815e #2831: add start argument to enumerate(). Patch by Scott Dial and me. Georg Brandl <georg@python.org> parents: 46952 diff changeset	290 .. function:: enumerate(sequence[, start=0])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291
46952 d2810b8aed6d Fix parameter name for enumerate(). Georg Brandl <georg@python.org> parents: 46866 diff changeset	292 Return an enumerate object. sequence must be a sequence, an
d2810b8aed6d Fix parameter name for enumerate(). Georg Brandl <georg@python.org> parents: 46866 diff changeset	293 :term:`iterator`, or some other object which supports iteration. The
d2810b8aed6d Fix parameter name for enumerate(). Georg Brandl <georg@python.org> parents: 46866 diff changeset	294 :meth:`next` method of the iterator returned by :func:`enumerate` returns a
46982 47692f6c815e #2831: add start argument to enumerate(). Patch by Scott Dial and me. Georg Brandl <georg@python.org> parents: 46952 diff changeset	295 tuple containing a count (from start which defaults to 0) and the
47692f6c815e #2831: add start argument to enumerate(). Patch by Scott Dial and me. Georg Brandl <georg@python.org> parents: 46952 diff changeset	296 corresponding value obtained from iterating over iterable.
47692f6c815e #2831: add start argument to enumerate(). Patch by Scott Dial and me. Georg Brandl <georg@python.org> parents: 46952 diff changeset	297 :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``,
47692f6c815e #2831: add start argument to enumerate(). Patch by Scott Dial and me. Georg Brandl <georg@python.org> parents: 46952 diff changeset	298 ``(1, seq[1])``, ``(2, seq[2])``, .... For example:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299
46013 d6f0e3e556a4 Enable doctests in functions.rst. Already found two errors :) Georg Brandl <georg@python.org> parents: 45978 diff changeset	300 >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter']):
d6f0e3e556a4 Enable doctests in functions.rst. Already found two errors :) Georg Brandl <georg@python.org> parents: 45978 diff changeset	301 ... print i, season
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 0 Spring
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303 1 Summer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 2 Fall
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305 3 Winter
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307 .. versionadded:: 2.3
46982 47692f6c815e #2831: add start argument to enumerate(). Patch by Scott Dial and me. Georg Brandl <georg@python.org> parents: 46952 diff changeset	308 .. versionadded:: 2.6
47692f6c815e #2831: add start argument to enumerate(). Patch by Scott Dial and me. Georg Brandl <georg@python.org> parents: 46952 diff changeset	309 The start parameter.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 .. function:: eval(expression[, globals[, locals]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314 The arguments are a string and optional globals and locals. If provided,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 globals must be a dictionary. If provided, locals can be any mapping
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 formerly locals was required to be a dictionary.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 The expression argument is parsed and evaluated as a Python expression
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 (technically speaking, a condition list) using the globals and locals
43631 03056365a1b6 Add :term:s for "new-style class". Georg Brandl <georg@python.org> parents: 43630 diff changeset	323 dictionaries as global and local namespace. If the globals dictionary is
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 present and lacks '__builtins__', the current globals are copied into globals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 before expression is parsed. This means that expression normally has full
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 access to the standard :mod:`__builtin__` module and restricted environments are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327 propagated. If the locals dictionary is omitted it defaults to the globals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 dictionary. If both dictionaries are omitted, the expression is executed in the
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	329 environment where :func:`eval` is called. The return value is the result of
46013 d6f0e3e556a4 Enable doctests in functions.rst. Already found two errors :) Georg Brandl <georg@python.org> parents: 45978 diff changeset	330 the evaluated expression. Syntax errors are reported as exceptions. Example:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332 >>> x = 1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 >>> print eval('x+1')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335
48895 56ed445fa61e #3569: eval() also accepts "exec"able code objects. Georg Brandl <georg@python.org> parents: 47937 diff changeset	336 This function can also be used to execute arbitrary code objects (such as
56ed445fa61e #3569: eval() also accepts "exec"able code objects. Georg Brandl <georg@python.org> parents: 47937 diff changeset	337 those created by :func:`compile`). In this case pass a code object instead
56ed445fa61e #3569: eval() also accepts "exec"able code objects. Georg Brandl <georg@python.org> parents: 47937 diff changeset	338 of a string. If the code object has been compiled with ``'exec'`` as the
56ed445fa61e #3569: eval() also accepts "exec"able code objects. Georg Brandl <georg@python.org> parents: 47937 diff changeset	339 kind argument, :func:`eval`\'s return value will be ``None``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 Hints: dynamic execution of statements is supported by the :keyword:`exec`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 statement. Execution of statements from a file is supported by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343 :func:`execfile` function. The :func:`globals` and :func:`locals` functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 returns the current global and local dictionary, respectively, which may be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 useful to pass around for use by :func:`eval` or :func:`execfile`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 .. function:: execfile(filename[, globals[, locals]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 This function is similar to the :keyword:`exec` statement, but parses a file
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351 instead of a string. It is different from the :keyword:`import` statement in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352 that it does not use the module administration --- it reads the file
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 unconditionally and does not create a new module. [#]_
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 The arguments are a file name and two optional dictionaries. The file is parsed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 and evaluated as a sequence of Python statements (similarly to a module) using
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 the globals and locals dictionaries as global and local namespace. If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 provided, locals can be any mapping object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361 formerly locals was required to be a dictionary.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363 If the locals dictionary is omitted it defaults to the globals dictionary.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364 If both dictionaries are omitted, the expression is executed in the environment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 where :func:`execfile` is called. The return value is ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366
53508 57812944c961 Demote warnings to notices where appropriate, following the goal that as few "red box" warnings Georg Brandl <georg@python.org> parents: 53304 diff changeset	367 .. note::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369 The default locals act as described for function :func:`locals` below:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370 modifications to the default locals dictionary should not be attempted. Pass
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371 an explicit locals dictionary if you need to see effects of the code on
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372 locals after function :func:`execfile` returns. :func:`execfile` cannot be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 used reliably to modify a function's locals.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376 .. function:: file(filename[, mode[, bufsize]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 Constructor function for the :class:`file` type, described further in section
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379 :ref:`bltin-file-objects`. The constructor's arguments are the same as those
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 of the :func:`open` built-in function described below.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 When opening a file, it's preferable to use :func:`open` instead of invoking
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 this constructor directly. :class:`file` is more suited to type testing (for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 example, writing ``isinstance(f, file)``).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389 .. function:: filter(function, iterable)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 Construct a list from those elements of iterable for which function returns
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 true. iterable may be either a sequence, a container which supports
43630 6df985744d96 Add :term:s for iterator. Georg Brandl <georg@python.org> parents: 43625 diff changeset	393 iteration, or an iterator. If iterable is a string or a tuple, the result
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 also has that type; otherwise it is always a list. If function is ``None``,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 the identity function is assumed, that is, all elements of iterable that are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396 false are removed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398 Note that ``filter(function, iterable)`` is equivalent to ``[item for item in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 iterable if function(item)]`` if function is not ``None`` and ``[item for item
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 in iterable if item]`` if function is ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401
51724 302263e3c8f1 Add some cross-references to the docs. Simplify the python code equivalent for izip(). Supply an optional argument for the nth() recipe. Raymond Hettinger <python@rcn.com> parents: 51679 diff changeset	402 See :func:`itertools.filterfalse` for the complementary function that returns
302263e3c8f1 Add some cross-references to the docs. Simplify the python code equivalent for izip(). Supply an optional argument for the nth() recipe. Raymond Hettinger <python@rcn.com> parents: 51679 diff changeset	403 elements of iterable for which function returns false.
302263e3c8f1 Add some cross-references to the docs. Simplify the python code equivalent for izip(). Supply an optional argument for the nth() recipe. Raymond Hettinger <python@rcn.com> parents: 51679 diff changeset	404
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 .. function:: float([x])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 Convert a string or a number to floating point. If the argument is a string, it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409 must contain a possibly signed decimal or floating point number, possibly
44344 1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms). Christian Heimes <christian@cheimes.de> parents: 44103 diff changeset	410 embedded in whitespace. The argument may also be [+\|-]nan or [+\|-]inf.
1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms). Christian Heimes <christian@cheimes.de> parents: 44103 diff changeset	411 Otherwise, the argument may be a plain or long integer
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 or a floating point number, and a floating point number with the same value
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 (within Python's floating point precision) is returned. If no argument is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 given, returns ``0.0``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 single: NaN
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420 single: Infinity
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422 When passing in a string, values for NaN and Infinity may be returned, depending
44344 1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms). Christian Heimes <christian@cheimes.de> parents: 44103 diff changeset	423 on the underlying C library. Float accepts the strings nan, inf and -inf for
1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms). Christian Heimes <christian@cheimes.de> parents: 44103 diff changeset	424 NaN and positive or negative infinity. The case and a leading + are ignored as
1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms). Christian Heimes <christian@cheimes.de> parents: 44103 diff changeset	425 well as a leading - is ignored for NaN. Float always represents NaN and infinity
1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms). Christian Heimes <christian@cheimes.de> parents: 44103 diff changeset	426 as nan, inf or -inf.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 The float type is described in :ref:`typesnumeric`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429
51807 8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	430
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	431 .. function:: format(value[, format_spec])
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	432
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	433 .. index::
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	434 pair: str; format
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	435 single: __format__
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	436
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	437 Convert a value to a "formatted" representation, as controlled by
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	438 format_spec. The interpretation of format_spec will depend on the type
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	439 of the value argument, however there is a standard formatting syntax that
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	440 is used by most built-in types: :ref:`formatspec`.
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	441
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	442 .. note::
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	443
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	444 ``format(value, format_spec)`` merely calls
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	445 ``value.__format__(format_spec)``.
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	446
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	447 .. versionadded:: 2.6
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	448
8a4dc0088e86 #5348: format() converts all kinds of values. Georg Brandl <georg@python.org> parents: 51732 diff changeset	449
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450 .. function:: frozenset([iterable])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 :noindex:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 Return a frozenset object, optionally with elements taken from iterable.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 The frozenset type is described in :ref:`types-set`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456 For other containers see the built in :class:`dict`, :class:`list`, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 :class:`tuple` classes, and the :mod:`collections` module.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462 .. function:: getattr(object, name[, default])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464 Return the value of the named attributed of object. name must be a string.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465 If the string is the name of one of the object's attributes, the result is the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466 value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 ``x.foobar``. If the named attribute does not exist, default is returned if
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468 provided, otherwise :exc:`AttributeError` is raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 .. function:: globals()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473 Return a dictionary representing the current global symbol table. This is always
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474 the dictionary of the current module (inside a function or method, this is the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475 module where it is defined, not the module from which it is called).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478 .. function:: hasattr(object, name)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 The arguments are an object and a string. The result is ``True`` if the string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 is the name of one of the object's attributes, ``False`` if not. (This is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 implemented by calling ``getattr(object, name)`` and seeing whether it raises an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483 exception or not.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486 .. function:: hash(object)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488 Return the hash value of the object (if it has one). Hash values are integers.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 They are used to quickly compare dictionary keys during a dictionary lookup.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490 Numeric values that compare equal have the same hash value (even if they are of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 different types, as is the case for 1 and 1.0).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494 .. function:: help([object])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496 Invoke the built-in help system. (This function is intended for interactive
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497 use.) If no argument is given, the interactive help system starts on the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 interpreter console. If the argument is a string, then the string is looked up
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499 as the name of a module, function, class, method, keyword, or documentation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 topic, and a help page is printed on the console. If the argument is any other
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501 kind of object, a help page on the object is generated.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502
44821 b28fdef2f0d7 #652749: document the constants added to the builtins by site.py. Georg Brandl <georg@python.org> parents: 44658 diff changeset	503 This function is added to the built-in namespace by the :mod:`site` module.
b28fdef2f0d7 #652749: document the constants added to the builtins by site.py. Georg Brandl <georg@python.org> parents: 44658 diff changeset	504
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 .. function:: hex(x)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 Convert an integer number (of any size) to a hexadecimal string. The result is a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511 valid Python expression.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514 Formerly only returned an unsigned literal.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517 .. function:: id(object)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519 Return the "identity" of an object. This is an integer (or long integer) which
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520 is guaranteed to be unique and constant for this object during its lifetime.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521 Two objects with non-overlapping lifetimes may have the same :func:`id` value.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522 (Implementation note: this is the address of the object.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	523
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525 .. function:: input([prompt])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527 Equivalent to ``eval(raw_input(prompt))``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529 .. warning::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	530
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	531 This function is not safe from user errors! It expects a valid Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532 expression as input; if the input is not syntactically valid, a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533 :exc:`SyntaxError` will be raised. Other exceptions may be raised if there is an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534 error during evaluation. (On the other hand, sometimes this is exactly what you
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535 need when writing a quick script for expert use.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537 If the :mod:`readline` module was loaded, then :func:`input` will use it to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 provide elaborate line editing and history features.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540 Consider using the :func:`raw_input` function for general input from users.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 .. function:: int([x[, radix]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544
43431 e98e11d7768c #1196: document default radix for int(). Georg Brandl <georg@python.org> parents: 43359 diff changeset	545 Convert a string or number to a plain integer. If the argument is a string,
e98e11d7768c #1196: document default radix for int(). Georg Brandl <georg@python.org> parents: 43359 diff changeset	546 it must contain a possibly signed decimal number representable as a Python
e98e11d7768c #1196: document default radix for int(). Georg Brandl <georg@python.org> parents: 43359 diff changeset	547 integer, possibly embedded in whitespace. The radix parameter gives the
e98e11d7768c #1196: document default radix for int(). Georg Brandl <georg@python.org> parents: 43359 diff changeset	548 base for the conversion (which is 10 by default) and may be any integer in
49190 cddf5d6476cf clarify that radix for int is not 'guessed' Benjamin Peterson <benjamin@python.org> parents: 48896 diff changeset	549 the range [2, 36], or zero. If radix is zero, the proper radix is
cddf5d6476cf clarify that radix for int is not 'guessed' Benjamin Peterson <benjamin@python.org> parents: 48896 diff changeset	550 determined based on the contents of string; the interpretation is the same as
cddf5d6476cf clarify that radix for int is not 'guessed' Benjamin Peterson <benjamin@python.org> parents: 48896 diff changeset	551 for integer literals. (See :ref:`numbers`.) If radix is specified and x
cddf5d6476cf clarify that radix for int is not 'guessed' Benjamin Peterson <benjamin@python.org> parents: 48896 diff changeset	552 is not a string, :exc:`TypeError` is raised. Otherwise, the argument may be a
cddf5d6476cf clarify that radix for int is not 'guessed' Benjamin Peterson <benjamin@python.org> parents: 48896 diff changeset	553 plain or long integer or a floating point number. Conversion of floating
cddf5d6476cf clarify that radix for int is not 'guessed' Benjamin Peterson <benjamin@python.org> parents: 48896 diff changeset	554 point numbers to integers truncates (towards zero). If the argument is
cddf5d6476cf clarify that radix for int is not 'guessed' Benjamin Peterson <benjamin@python.org> parents: 48896 diff changeset	555 outside the integer range a long object will be returned instead. If no
cddf5d6476cf clarify that radix for int is not 'guessed' Benjamin Peterson <benjamin@python.org> parents: 48896 diff changeset	556 arguments are given, returns ``0``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558 The integer type is described in :ref:`typesnumeric`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	559
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561 .. function:: isinstance(object, classinfo)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563 Return true if the object argument is an instance of the classinfo argument,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564 or of a (direct or indirect) subclass thereof. Also return true if classinfo
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 is a type object (new-style class) and object is an object of that type or of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566 a (direct or indirect) subclass thereof. If object is not a class instance or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567 an object of the given type, the function always returns false. If classinfo
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 is neither a class object nor a type object, it may be a tuple of class or type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569 objects, or may recursively contain other such tuples (other sequence types are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570 not accepted). If classinfo is not a class, type, or tuple of classes, types,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571 and such tuples, a :exc:`TypeError` exception is raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573 .. versionchanged:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574 Support for a tuple of type information was added.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577 .. function:: issubclass(class, classinfo)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579 Return true if class is a subclass (direct or indirect) of classinfo. A
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580 class is considered a subclass of itself. classinfo may be a tuple of class
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 objects, in which case every entry in classinfo will be checked. In any other
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582 case, a :exc:`TypeError` exception is raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 Support for a tuple of type information was added.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 .. function:: iter(o[, sentinel])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589
43630 6df985744d96 Add :term:s for iterator. Georg Brandl <georg@python.org> parents: 43625 diff changeset	590 Return an :term:`iterator` object. The first argument is interpreted very differently
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591 depending on the presence of the second argument. Without a second argument, o
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592 must be a collection object which supports the iteration protocol (the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593 :meth:`__iter__` method), or it must support the sequence protocol (the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	594 :meth:`__getitem__` method with integer arguments starting at ``0``). If it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595 does not support either of those protocols, :exc:`TypeError` is raised. If the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596 second argument, sentinel, is given, then o must be a callable object. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	597 iterator created in this case will call o with no arguments for each call to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598 its :meth:`next` method; if the value returned is equal to sentinel,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599 :exc:`StopIteration` will be raised, otherwise the value will be returned.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600
52220 92fefcddbfe8 a much better example Benjamin Peterson <benjamin@python.org> parents: 52194 diff changeset	601 One useful application of the second form of :func:`iter` is to read lines of
92fefcddbfe8 a much better example Benjamin Peterson <benjamin@python.org> parents: 52194 diff changeset	602 a file until a certain line is reached. The following example reads a file
92fefcddbfe8 a much better example Benjamin Peterson <benjamin@python.org> parents: 52194 diff changeset	603 until ``"STOP"`` is reached: ::
52194 171ed6ffc86c I thought this was begging for an example Benjamin Peterson <benjamin@python.org> parents: 51862 diff changeset	604
52220 92fefcddbfe8 a much better example Benjamin Peterson <benjamin@python.org> parents: 52194 diff changeset	605 with open("mydata.txt") as fp:
92fefcddbfe8 a much better example Benjamin Peterson <benjamin@python.org> parents: 52194 diff changeset	606 for line in iter(fp.readline, "STOP"):
92fefcddbfe8 a much better example Benjamin Peterson <benjamin@python.org> parents: 52194 diff changeset	607 process_line(line)
52194 171ed6ffc86c I thought this was begging for an example Benjamin Peterson <benjamin@python.org> parents: 51862 diff changeset	608
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	609 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	610
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	612 .. function:: len(s)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	613
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614 Return the length (the number of items) of an object. The argument may be a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615 sequence (string, tuple or list) or a mapping (dictionary).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	616
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	617
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	618 .. function:: list([iterable])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	619
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	620 Return a list whose items are the same and in the same order as iterable's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621 items. iterable may be either a sequence, a container that supports
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622 iteration, or an iterator object. If iterable is already a list, a copy is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623 made and returned, similar to ``iterable[:]``. For instance, ``list('abc')``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	624 returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	625 no argument is given, returns a new empty list, ``[]``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	626
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	627 :class:`list` is a mutable sequence type, as documented in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	628 :ref:`typesseq`. For other containers see the built in :class:`dict`,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	629 :class:`set`, and :class:`tuple` classes, and the :mod:`collections` module.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	631
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632 .. function:: locals()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634 Update and return a dictionary representing the current local symbol table.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	635
53508 57812944c961 Demote warnings to notices where appropriate, following the goal that as few "red box" warnings Georg Brandl <georg@python.org> parents: 53304 diff changeset	636 .. note::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638 The contents of this dictionary should not be modified; changes may not affect
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	639 the values of local variables used by the interpreter.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	641 Free variables are returned by :func:`locals` when it is called in a function block.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642 Modifications of free variables may not affect the values used by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643 interpreter. Free variables are not returned in class blocks.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	645
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	646 .. function:: long([x[, radix]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648 Convert a string or number to a long integer. If the argument is a string, it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649 must contain a possibly signed number of arbitrary size, possibly embedded in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650 whitespace. The radix argument is interpreted in the same way as for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651 :func:`int`, and may only be given when x is a string. Otherwise, the argument
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652 may be a plain or long integer or a floating point number, and a long integer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653 with the same value is returned. Conversion of floating point numbers to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654 integers truncates (towards zero). If no arguments are given, returns ``0L``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656 The long type is described in :ref:`typesnumeric`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658 .. function:: map(function, iterable, ...)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660 Apply function to every item of iterable and return a list of the results.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661 If additional iterable arguments are passed, function must take that many
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662 arguments and is applied to the items from all iterables in parallel. If one
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663 iterable is shorter than another it is assumed to be extended with ``None``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664 items. If function is ``None``, the identity function is assumed; if there
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 are multiple arguments, :func:`map` returns a list consisting of tuples
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666 containing the corresponding items from all iterables (a kind of transpose
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667 operation). The iterable arguments may be a sequence or any iterable object;
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668 the result is always a list.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 .. function:: max(iterable[, args...][key])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673 With a single argument iterable, return the largest item of a non-empty
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674 iterable (such as a string, tuple or list). With more than one argument, return
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675 the largest of the arguments.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677 The optional key argument specifies a one-argument ordering function like that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678 used for :meth:`list.sort`. The key argument, if supplied, must be in keyword
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679 form (for example, ``max(a,b,c,key=func)``).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681 .. versionchanged:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	682 Added support for the optional key argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684
52749 75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52483 diff changeset	685 .. function:: memoryview(obj)
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52483 diff changeset	686 :noindex:
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52483 diff changeset	687
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52483 diff changeset	688 Return a "memory view" object created from the given argument. See
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52483 diff changeset	689 :ref:`typememoryview` for more information.
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52483 diff changeset	690
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52483 diff changeset	691
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	692 .. function:: min(iterable[, args...][key])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694 With a single argument iterable, return the smallest item of a non-empty
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	695 iterable (such as a string, tuple or list). With more than one argument, return
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	696 the smallest of the arguments.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698 The optional key argument specifies a one-argument ordering function like that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699 used for :meth:`list.sort`. The key argument, if supplied, must be in keyword
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700 form (for example, ``min(a,b,c,key=func)``).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 .. versionchanged:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703 Added support for the optional key argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705
46607 7a6d7474ce6e #2719: backport next() from 3k. Georg Brandl <georg@python.org> parents: 46566 diff changeset	706 .. function:: next(iterator[, default])
7a6d7474ce6e #2719: backport next() from 3k. Georg Brandl <georg@python.org> parents: 46566 diff changeset	707
7a6d7474ce6e #2719: backport next() from 3k. Georg Brandl <georg@python.org> parents: 46566 diff changeset	708 Retrieve the next item from the iterator by calling its :meth:`next`
7a6d7474ce6e #2719: backport next() from 3k. Georg Brandl <georg@python.org> parents: 46566 diff changeset	709 method. If default is given, it is returned if the iterator is exhausted,
7a6d7474ce6e #2719: backport next() from 3k. Georg Brandl <georg@python.org> parents: 46566 diff changeset	710 otherwise :exc:`StopIteration` is raised.
7a6d7474ce6e #2719: backport next() from 3k. Georg Brandl <georg@python.org> parents: 46566 diff changeset	711
7a6d7474ce6e #2719: backport next() from 3k. Georg Brandl <georg@python.org> parents: 46566 diff changeset	712 .. versionadded:: 2.6
7a6d7474ce6e #2719: backport next() from 3k. Georg Brandl <georg@python.org> parents: 46566 diff changeset	713
7a6d7474ce6e #2719: backport next() from 3k. Georg Brandl <georg@python.org> parents: 46566 diff changeset	714
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	715 .. function:: object()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717 Return a new featureless object. :class:`object` is a base for all new style
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718 classes. It has the methods that are common to all instances of new style
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719 classes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724 This function does not accept any arguments. Formerly, it accepted arguments but
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 ignored them.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	728 .. function:: oct(x)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730 Convert an integer number (of any size) to an octal string. The result is a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 valid Python expression.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734 Formerly only returned an unsigned literal.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737 .. function:: open(filename[, mode[, bufsize]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	739 Open a file, returning an object of the :class:`file` type described in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740 section :ref:`bltin-file-objects`. If the file cannot be opened,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741 :exc:`IOError` is raised. When opening a file, it's preferable to use
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742 :func:`open` instead of invoking the :class:`file` constructor directly.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 The first two arguments are the same as for ``stdio``'s :cfunc:`fopen`:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 filename is the file name to be opened, and mode is a string indicating how
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 the file is to be opened.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748 The most commonly-used values of mode are ``'r'`` for reading, ``'w'`` for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 writing (truncating the file if it already exists), and ``'a'`` for appending
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750 (which on some Unix systems means that all writes append to the end of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 file regardless of the current seek position). If mode is omitted, it
44658 b672c015c2db Clarify the effect of text mode. Georg Brandl <georg@python.org> parents: 44547 diff changeset	752 defaults to ``'r'``. The default is to use text mode, which may convert
b672c015c2db Clarify the effect of text mode. Georg Brandl <georg@python.org> parents: 44547 diff changeset	753 ``'\n'`` characters to a platform-specific representation on writing and back
b672c015c2db Clarify the effect of text mode. Georg Brandl <georg@python.org> parents: 44547 diff changeset	754 on reading. Thus, when opening a binary file, you should append ``'b'`` to
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755 the mode value to open the file in binary mode, which will improve
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756 portability. (Appending ``'b'`` is useful even on systems that don't treat
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757 binary and text files differently, where it serves as documentation.) See below
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758 for more possible values of mode.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761 single: line-buffered I/O
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762 single: unbuffered I/O
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763 single: buffer size, I/O
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764 single: I/O control; buffering
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766 The optional bufsize argument specifies the file's desired buffer size: 0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767 means unbuffered, 1 means line buffered, any other positive value means use a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768 buffer of (approximately) that size. A negative bufsize means to use the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 system default, which is usually line buffered for tty devices and fully
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770 buffered for other files. If omitted, the system default is used. [#]_
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772 Modes ``'r+'``, ``'w+'`` and ``'a+'`` open the file for updating (note that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773 ``'w+'`` truncates the file). Append ``'b'`` to the mode to open the file in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774 binary mode, on systems that differentiate between binary and text files; on
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775 systems that don't have this distinction, adding the ``'b'`` has no effect.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777 In addition to the standard :cfunc:`fopen` values mode may be ``'U'`` or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778 ``'rU'``. Python is usually built with universal newline support; supplying
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779 ``'U'`` opens the file as a text file, but lines may be terminated by any of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	780 following: the Unix end-of-line convention ``'\n'``, the Macintosh convention
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781 ``'\r'``, or the Windows convention ``'\r\n'``. All of these external
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782 representations are seen as ``'\n'`` by the Python program. If Python is built
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783 without universal newline support a mode with ``'U'`` is the same as normal
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784 text mode. Note that file objects so opened also have an attribute called
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785 :attr:`newlines` which has a value of ``None`` (if no newlines have yet been
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786 seen), ``'\n'``, ``'\r'``, ``'\r\n'``, or a tuple containing all the newline
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787 types seen.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789 Python enforces that the mode, after stripping ``'U'``, begins with ``'r'``,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790 ``'w'`` or ``'a'``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791
43748 8a40b831ab68 Added more file-handling related cross-references. Mark Summerfield <list@qtrac.plus.com> parents: 43631 diff changeset	792 Python provides many file handling modules including
8a40b831ab68 Added more file-handling related cross-references. Mark Summerfield <list@qtrac.plus.com> parents: 43631 diff changeset	793 :mod:`fileinput`, :mod:`os`, :mod:`os.path`, :mod:`tempfile`, and
8a40b831ab68 Added more file-handling related cross-references. Mark Summerfield <list@qtrac.plus.com> parents: 43631 diff changeset	794 :mod:`shutil`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796 .. versionchanged:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797 Restriction on first letter of mode string introduced.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	798
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	799
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	800 .. function:: ord(c)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	801
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	802 Given a string of length one, return an integer representing the Unicode code
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803 point of the character when the argument is a unicode object, or the value of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	804 the byte when the argument is an 8-bit string. For example, ``ord('a')`` returns
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	805 the integer ``97``, ``ord(u'\u2020')`` returns ``8224``. This is the inverse of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	806 :func:`chr` for 8-bit strings and of :func:`unichr` for unicode objects. If a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807 unicode argument is given and Python was built with UCS2 Unicode, then the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808 character's code point must be in the range [0..65535] inclusive; otherwise the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 string length is two, and a :exc:`TypeError` will be raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	810
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812 .. function:: pow(x, y[, z])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814 Return x to the power y; if z is present, return x to the power y,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815 modulo z (computed more efficiently than ``pow(x, y) % z``). The two-argument
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	816 form ``pow(x, y)`` is equivalent to using the power operator: ``x**y``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	817
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	818 The arguments must have numeric types. With mixed operand types, the coercion
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	819 rules for binary arithmetic operators apply. For int and long int operands, the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	820 result has the same type as the operands (after coercion) unless the second
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	821 argument is negative; in that case, all arguments are converted to float and a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	822 float result is delivered. For example, ``10**2`` returns ``100``, but
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	823 ``10**-2`` returns ``0.01``. (This last feature was added in Python 2.2. In
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	824 Python 2.1 and before, if both arguments were of integer types and the second
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	825 argument was negative, an exception was raised.) If the second argument is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	826 negative, the third argument must be omitted. If z is present, x and y
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	827 must be of integer types, and y must be non-negative. (This restriction was
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828 added in Python 2.2. In Python 2.1 and before, floating 3-argument ``pow()``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	829 returned platform-dependent results depending on floating-point rounding
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	830 accidents.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832
53304 77336d82ab95 #5751: fix escaping of \\n. Georg Brandl <georg@python.org> parents: 53175 diff changeset	833 .. function:: print([object, ...][, sep=' '][, end='\\n'][, file=sys.stdout])
45978 544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	834
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	835 Print object\(s) to the stream file, separated by sep and followed by
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	836 end. sep, end and file, if present, must be given as keyword
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	837 arguments.
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	838
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	839 All non-keyword arguments are converted to strings like :func:`str` does and
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	840 written to the stream, separated by sep and followed by end. Both sep
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	841 and end must be strings; they can also be ``None``, which means to use the
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	842 default values. If no object is given, :func:`print` will just write
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	843 end.
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	844
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	845 The file argument must be an object with a ``write(string)`` method; if it
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	846 is not present or ``None``, :data:`sys.stdout` will be used.
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	847
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	848 .. note::
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	849
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	850 This function is not normally available as a builtin since the name
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	851 ``print`` is recognized as the :keyword:`print` statement. To disable the
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	852 statement and use the :func:`print` function, use this future statement at
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	853 the top of your module::
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	854
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	855 from __future__ import print_function
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	856
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	857 .. versionadded:: 2.6
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	858
544a46df0222 Add docs for print_function and future_builtins. Fixes #2442. Georg Brandl <georg@python.org> parents: 45079 diff changeset	859
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	860 .. function:: property([fget[, fset[, fdel[, doc]]]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	861
43631 03056365a1b6 Add :term:s for "new-style class". Georg Brandl <georg@python.org> parents: 43630 diff changeset	862 Return a property attribute for :term:`new-style class`\es (classes that
03056365a1b6 Add :term:s for "new-style class". Georg Brandl <georg@python.org> parents: 43630 diff changeset	863 derive from :class:`object`).
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	864
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	865 fget is a function for getting an attribute value, likewise fset is a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	866 function for setting, and fdel a function for del'ing, an attribute. Typical
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	867 use is to define a managed attribute x::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	868
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	869 class C(object):
46866 fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	870 def __init__(self):
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	871 self._x = None
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	872
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	873 def getx(self):
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	874 return self._x
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	875 def setx(self, value):
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	876 self._x = value
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	877 def delx(self):
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	878 del self._x
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	879 x = property(getx, setx, delx, "I'm the 'x' property.")
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	880
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	881 If given, doc will be the docstring of the property attribute. Otherwise, the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	882 property will copy fget's docstring (if it exists). This makes it possible to
44103 1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 43748 diff changeset	883 create read-only properties easily using :func:`property` as a :term:`decorator`::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	884
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	885 class Parrot(object):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	886 def __init__(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	887 self._voltage = 100000
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	888
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	889 @property
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	890 def voltage(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	891 """Get the current voltage."""
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	892 return self._voltage
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	893
46866 fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	894 turns the :meth:`voltage` method into a "getter" for a read-only attribute
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	895 with the same name.
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	896
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	897 A property object has :attr:`getter`, :attr:`setter`, and :attr:`deleter`
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	898 methods usable as decorators that create a copy of the property with the
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	899 corresponding accessor function set to the decorated function. This is
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	900 best explained with an example::
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	901
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	902 class C(object):
49511 4737e5df50f4 add a much requested newline Benjamin Peterson <benjamin@python.org> parents: 49489 diff changeset	903 def __init__(self):
4737e5df50f4 add a much requested newline Benjamin Peterson <benjamin@python.org> parents: 49489 diff changeset	904 self._x = None
46866 fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	905
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	906 @property
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	907 def x(self):
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	908 """I'm the 'x' property."""
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	909 return self._x
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	910
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	911 @x.setter
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	912 def x(self, value):
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	913 self._x = value
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	914
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	915 @x.deleter
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	916 def x(self):
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	917 del self._x
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	918
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	919 This code is exactly equivalent to the first example. Be sure to give the
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	920 additional functions the same name as the original property (``x`` in this
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	921 case.)
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	922
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	923 The returned property also has the attributes ``fget``, ``fset``, and
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	924 ``fdel`` corresponding to the constructor arguments.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	925
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	926 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	927
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	928 .. versionchanged:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	929 Use fget's docstring if no doc given.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	930
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50085 diff changeset	931 .. versionchanged:: 2.6
46866 fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	932 The ``getter``, ``setter``, and ``deleter`` attributes were added.
fdef71797e83 #2812: document property.getter/setter/deleter. Georg Brandl <georg@python.org> parents: 46607 diff changeset	933
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	934
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	935 .. function:: range([start,] stop[, step])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	936
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	937 This is a versatile function to create lists containing arithmetic progressions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	938 It is most often used in :keyword:`for` loops. The arguments must be plain
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	939 integers. If the step argument is omitted, it defaults to ``1``. If the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	940 start argument is omitted, it defaults to ``0``. The full form returns a list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	941 of plain integers ``[start, start + step, start + 2 * step, ...]``. If step
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	942 is positive, the last element is the largest ``start + i * step`` less than
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	943 stop; if step is negative, the last element is the smallest ``start + i *
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	944 step`` greater than stop. step must not be zero (or else :exc:`ValueError`
46013 d6f0e3e556a4 Enable doctests in functions.rst. Already found two errors :) Georg Brandl <georg@python.org> parents: 45978 diff changeset	945 is raised). Example:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	946
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	947 >>> range(10)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	948 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	949 >>> range(1, 11)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	950 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	951 >>> range(0, 30, 5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	952 [0, 5, 10, 15, 20, 25]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	953 >>> range(0, 10, 3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	954 [0, 3, 6, 9]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	955 >>> range(0, -10, -1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	956 [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	957 >>> range(0)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	958 []
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	959 >>> range(1, 0)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	960 []
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	961
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	962
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	963 .. function:: raw_input([prompt])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	964
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	965 If the prompt argument is present, it is written to standard output without a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	966 trailing newline. The function then reads a line from input, converts it to a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	967 string (stripping a trailing newline), and returns that. When EOF is read,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	968 :exc:`EOFError` is raised. Example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	969
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	970 >>> s = raw_input('--> ')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	971 --> Monty Python's Flying Circus
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	972 >>> s
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	973 "Monty Python's Flying Circus"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	974
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	975 If the :mod:`readline` module was loaded, then :func:`raw_input` will use it to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	976 provide elaborate line editing and history features.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	977
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	978
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	979 .. function:: reduce(function, iterable[, initializer])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	980
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	981 Apply function of two arguments cumulatively to the items of iterable, from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	982 left to right, so as to reduce the iterable to a single value. For example,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	983 ``reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])`` calculates ``((((1+2)+3)+4)+5)``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	984 The left argument, x, is the accumulated value and the right argument, y, is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	985 the update value from the iterable. If the optional initializer is present,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	986 it is placed before the items of the iterable in the calculation, and serves as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	987 a default when the iterable is empty. If initializer is not given and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	988 iterable contains only one item, the first item is returned.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	989
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	990
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	991 .. function:: reload(module)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	992
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	993 Reload a previously imported module. The argument must be a module object, so
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	994 it must have been successfully imported before. This is useful if you have
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	995 edited the module source file using an external editor and want to try out the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	996 new version without leaving the Python interpreter. The return value is the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	997 module object (the same as the module argument).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	998
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	999 When ``reload(module)`` is executed:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1000
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1001 * Python modules' code is recompiled and the module-level code reexecuted,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1002 defining a new set of objects which are bound to names in the module's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1003 dictionary. The ``init`` function of extension modules is not called a second
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1004 time.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1005
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1006 * As with all other objects in Python the old objects are only reclaimed after
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1007 their reference counts drop to zero.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1008
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1009 * The names in the module namespace are updated to point to any new or changed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1010 objects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1011
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1012 * Other references to the old objects (such as names external to the module) are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1013 not rebound to refer to the new objects and must be updated in each namespace
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1014 where they occur if that is desired.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1015
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1016 There are a number of other caveats:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1017
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1018 If a module is syntactically correct but its initialization fails, the first
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1019 :keyword:`import` statement for it does not bind its name locally, but does
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1020 store a (partially initialized) module object in ``sys.modules``. To reload the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1021 module you must first :keyword:`import` it again (this will bind the name to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1022 partially initialized module object) before you can :func:`reload` it.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1023
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1024 When a module is reloaded, its dictionary (containing the module's global
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1025 variables) is retained. Redefinitions of names will override the old
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1026 definitions, so this is generally not a problem. If the new version of a module
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1027 does not define a name that was defined by the old version, the old definition
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1028 remains. This feature can be used to the module's advantage if it maintains a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1029 global table or cache of objects --- with a :keyword:`try` statement it can test
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1030 for the table's presence and skip its initialization if desired::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1031
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1032 try:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1033 cache
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1034 except NameError:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1035 cache = {}
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1036
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1037 It is legal though generally not very useful to reload built-in or dynamically
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1038 loaded modules, except for :mod:`sys`, :mod:`__main__` and :mod:`__builtin__`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1039 In many cases, however, extension modules are not designed to be initialized
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1040 more than once, and may fail in arbitrary ways when reloaded.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1041
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1042 If a module imports objects from another module using :keyword:`from` ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1043 :keyword:`import` ..., calling :func:`reload` for the other module does not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1044 redefine the objects imported from it --- one way around this is to re-execute
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1045 the :keyword:`from` statement, another is to use :keyword:`import` and qualified
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1046 names (module.name) instead.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1047
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1048 If a module instantiates instances of a class, reloading the module that defines
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1049 the class does not affect the method definitions of the instances --- they
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1050 continue to use the old class definition. The same is true for derived classes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1051
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1052
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1053 .. function:: repr(object)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1054
46067 958cf0c27da9 #868845: document <...> reprs. Georg Brandl <georg@python.org> parents: 46013 diff changeset	1055 Return a string containing a printable representation of an object. This is
958cf0c27da9 #868845: document <...> reprs. Georg Brandl <georg@python.org> parents: 46013 diff changeset	1056 the same value yielded by conversions (reverse quotes). It is sometimes
958cf0c27da9 #868845: document <...> reprs. Georg Brandl <georg@python.org> parents: 46013 diff changeset	1057 useful to be able to access this operation as an ordinary function. For many
958cf0c27da9 #868845: document <...> reprs. Georg Brandl <georg@python.org> parents: 46013 diff changeset	1058 types, this function makes an attempt to return a string that would yield an
958cf0c27da9 #868845: document <...> reprs. Georg Brandl <georg@python.org> parents: 46013 diff changeset	1059 object with the same value when passed to :func:`eval`, otherwise the
958cf0c27da9 #868845: document <...> reprs. Georg Brandl <georg@python.org> parents: 46013 diff changeset	1060 representation is a string enclosed in angle brackets that contains the name
958cf0c27da9 #868845: document <...> reprs. Georg Brandl <georg@python.org> parents: 46013 diff changeset	1061 of the type of the object together with additional information often
958cf0c27da9 #868845: document <...> reprs. Georg Brandl <georg@python.org> parents: 46013 diff changeset	1062 including the name and address of the object. A class can control what this
958cf0c27da9 #868845: document <...> reprs. Georg Brandl <georg@python.org> parents: 46013 diff changeset	1063 function returns for its instances by defining a :meth:`__repr__` method.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1064
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1065
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1066 .. function:: reversed(seq)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1067
44532 090083a233f8 #1582: document __reversed__, patch by Mark Russell. Georg Brandl <georg@python.org> parents: 44527 diff changeset	1068 Return a reverse :term:`iterator`. seq must be an object which has
090083a233f8 #1582: document __reversed__, patch by Mark Russell. Georg Brandl <georg@python.org> parents: 44527 diff changeset	1069 a :meth:`__reversed__` method or supports the sequence protocol (the
090083a233f8 #1582: document __reversed__, patch by Mark Russell. Georg Brandl <georg@python.org> parents: 44527 diff changeset	1070 :meth:`__len__` method and the :meth:`__getitem__` method with integer
090083a233f8 #1582: document __reversed__, patch by Mark Russell. Georg Brandl <georg@python.org> parents: 44527 diff changeset	1071 arguments starting at ``0``).
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1072
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1073 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1074
44532 090083a233f8 #1582: document __reversed__, patch by Mark Russell. Georg Brandl <georg@python.org> parents: 44527 diff changeset	1075 .. versionchanged:: 2.6
090083a233f8 #1582: document __reversed__, patch by Mark Russell. Georg Brandl <georg@python.org> parents: 44527 diff changeset	1076 Added the possibility to write a custom :meth:`__reversed__` method.
090083a233f8 #1582: document __reversed__, patch by Mark Russell. Georg Brandl <georg@python.org> parents: 44527 diff changeset	1077
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1078
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1079 .. function:: round(x[, n])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1080
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1081 Return the floating point value x rounded to n digits after the decimal
44488 94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	1082 point. If n is omitted, it defaults to zero. The result is a floating point
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	1083 number. Values are rounded to the closest multiple of 10 to the power minus
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	1084 n; if two multiples are equally close, rounding is done away from 0 (so. for
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	1085 example, ``round(0.5)`` is ``1.0`` and ``round(-0.5)`` is ``-1.0``).
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1086
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1087
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1088 .. function:: set([iterable])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1089 :noindex:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1090
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1091 Return a new set, optionally with elements are taken from iterable.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1092 The set type is described in :ref:`types-set`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1093
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1094 For other containers see the built in :class:`dict`, :class:`list`, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1095 :class:`tuple` classes, and the :mod:`collections` module.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1096
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1097 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1098
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1099
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1100 .. function:: setattr(object, name, value)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1101
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1102 This is the counterpart of :func:`getattr`. The arguments are an object, a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1103 string and an arbitrary value. The string may name an existing attribute or a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1104 new attribute. The function assigns the value to the attribute, provided the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1105 object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1106 ``x.foobar = 123``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1107
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1108
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1109 .. function:: slice([start,] stop[, step])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1110
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1111 .. index:: single: Numerical Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1112
44103 1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1113 Return a :term:`slice` object representing the set of indices specified by
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1114 ``range(start, stop, step)``. The start and step arguments default to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1115 ``None``. Slice objects have read-only data attributes :attr:`start`,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1116 :attr:`stop` and :attr:`step` which merely return the argument values (or their
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1117 default). They have no other explicit functionality; however they are used by
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1118 Numerical Python and other third party extensions. Slice objects are also
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1119 generated when extended indexing syntax is used. For example:
51724 302263e3c8f1 Add some cross-references to the docs. Simplify the python code equivalent for izip(). Supply an optional argument for the nth() recipe. Raymond Hettinger <python@rcn.com> parents: 51679 diff changeset	1120 ``a[start:stop:step]`` or ``a[start:stop, i]``. See :func:`itertools.islice`
302263e3c8f1 Add some cross-references to the docs. Simplify the python code equivalent for izip(). Supply an optional argument for the nth() recipe. Raymond Hettinger <python@rcn.com> parents: 51679 diff changeset	1121 for an alternate version that returns an iterator.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1122
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1123
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1124 .. function:: sorted(iterable[, cmp[, key[, reverse]]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1125
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1126 Return a new sorted list from the items in iterable.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1127
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1128 The optional arguments cmp, key, and reverse have the same meaning as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1129 those for the :meth:`list.sort` method (described in section
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1130 :ref:`typesseq-mutable`).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1131
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1132 cmp specifies a custom comparison function of two arguments (iterable
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1133 elements) which should return a negative, zero or positive number depending on
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1134 whether the first argument is considered smaller than, equal to, or larger than
44525 66197f8d0fdf #1755097: document default values for [].sort() and sorted(). Georg Brandl <georg@python.org> parents: 44497 diff changeset	1135 the second argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``. The default
66197f8d0fdf #1755097: document default values for [].sort() and sorted(). Georg Brandl <georg@python.org> parents: 44497 diff changeset	1136 value is ``None``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1137
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1138 key specifies a function of one argument that is used to extract a comparison
44525 66197f8d0fdf #1755097: document default values for [].sort() and sorted(). Georg Brandl <georg@python.org> parents: 44497 diff changeset	1139 key from each list element: ``key=str.lower``. The default value is ``None``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1140
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1141 reverse is a boolean value. If set to ``True``, then the list elements are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1142 sorted as if each comparison were reversed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1143
51732 9800ab236c09 Add links to helpful external resources. Raymond Hettinger <python@rcn.com> parents: 51724 diff changeset	1144 In general, the key and reverse conversion processes are much faster
9800ab236c09 Add links to helpful external resources. Raymond Hettinger <python@rcn.com> parents: 51724 diff changeset	1145 than specifying an equivalent cmp function. This is because cmp is
9800ab236c09 Add links to helpful external resources. Raymond Hettinger <python@rcn.com> parents: 51724 diff changeset	1146 called multiple times for each list element while key and reverse touch
9800ab236c09 Add links to helpful external resources. Raymond Hettinger <python@rcn.com> parents: 51724 diff changeset	1147 each element only once. To convert an old-style cmp function to a key
9800ab236c09 Add links to helpful external resources. Raymond Hettinger <python@rcn.com> parents: 51724 diff changeset	1148 function, see the `CmpToKey recipe in the ASPN cookbook
9800ab236c09 Add links to helpful external resources. Raymond Hettinger <python@rcn.com> parents: 51724 diff changeset	1149 <http://code.activestate.com/recipes/576653/>`_\.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1150
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1151 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1152
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1153
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1154 .. function:: staticmethod(function)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1155
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1156 Return a static method for function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1157
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1158 A static method does not receive an implicit first argument. To declare a static
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1159 method, use this idiom::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1160
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1161 class C:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1162 @staticmethod
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1163 def f(arg1, arg2, ...): ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1164
44103 1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1165 The ``@staticmethod`` form is a function :term:`decorator` -- see the
1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1166 description of function definitions in :ref:`function` for details.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1167
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1168 It can be called either on the class (such as ``C.f()``) or on an instance (such
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1169 as ``C().f()``). The instance is ignored except for its class.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1170
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1171 Static methods in Python are similar to those found in Java or C++. For a more
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1172 advanced concept, see :func:`classmethod` in this section.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1173
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1174 For more information on static methods, consult the documentation on the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1175 standard type hierarchy in :ref:`types`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1176
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1177 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1178
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1179 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1180 Function decorator syntax added.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1181
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1182
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1183 .. function:: str([object])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1184
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1185 Return a string containing a nicely printable representation of an object. For
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1186 strings, this returns the string itself. The difference with ``repr(object)``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1187 is that ``str(object)`` does not always attempt to return a string that is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1188 acceptable to :func:`eval`; its goal is to return a printable string. If no
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1189 argument is given, returns the empty string, ``''``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1190
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1191 For more information on strings see :ref:`typesseq` which describes sequence
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1192 functionality (strings are sequences), and also the string-specific methods
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1193 described in the :ref:`string-methods` section. To output formatted strings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1194 use template strings or the ``%`` operator described in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1195 :ref:`string-formatting` section. In addition see the :ref:`stringservices`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1196 section. See also :func:`unicode`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1197
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1198
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1199 .. function:: sum(iterable[, start])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1200
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1201 Sums start and the items of an iterable from left to right and returns the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1202 total. start defaults to ``0``. The iterable's items are normally numbers,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1203 and are not allowed to be strings. The fast, correct way to concatenate a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1204 sequence of strings is by calling ``''.join(sequence)``. Note that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1205 ``sum(range(n), m)`` is equivalent to ``reduce(operator.add, range(n), m)``
51724 302263e3c8f1 Add some cross-references to the docs. Simplify the python code equivalent for izip(). Supply an optional argument for the nth() recipe. Raymond Hettinger <python@rcn.com> parents: 51679 diff changeset	1206 To add floating point values with extended precision, see :func:`math.fsum`\.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1207
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1208 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1209
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1210
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1211 .. function:: super(type[, object-or-type])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1212
51844 1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1213 Return a proxy object that delegates method calls to a parent or sibling
1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1214 class of type. This is useful for accessing inherited methods that have
1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1215 been overridden in a class. The search order is same as that used by
1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1216 :func:`getattr` except that the type itself is skipped.
49232 5a71a6068e30 Improve docs for super(). Raymond Hettinger <python@rcn.com> parents: 49190 diff changeset	1217
51847 46cbe67b9661 More markup and spelling fixes. Raymond Hettinger <python@rcn.com> parents: 51845 diff changeset	1218 The :attr:`__mro__` attribute of the type lists the method resolution
46cbe67b9661 More markup and spelling fixes. Raymond Hettinger <python@rcn.com> parents: 51845 diff changeset	1219 search order used by both :func:`getattr` and :func:`super`. The attribute
46cbe67b9661 More markup and spelling fixes. Raymond Hettinger <python@rcn.com> parents: 51845 diff changeset	1220 is dynamic and can change whenever the inheritance hierarchy is updated.
51844 1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1221
1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1222 If the second argument is omitted, the super object returned is unbound. If
1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1223 the second argument is an object, ``isinstance(obj, type)`` must be true. If
1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1224 the second argument is a type, ``issubclass(type2, type)`` must be true (this
1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1225 is useful for classmethods).
51445 9899afe0ff8c make "super only for new-style classes" a note. Georg Brandl <georg@python.org> parents: 50508 diff changeset	1226
9899afe0ff8c make "super only for new-style classes" a note. Georg Brandl <georg@python.org> parents: 50508 diff changeset	1227 .. note::
9899afe0ff8c make "super only for new-style classes" a note. Georg Brandl <georg@python.org> parents: 50508 diff changeset	1228 :func:`super` only works for :term:`new-style class`\es.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1229
51847 46cbe67b9661 More markup and spelling fixes. Raymond Hettinger <python@rcn.com> parents: 51845 diff changeset	1230 There are two typical use cases for super. In a class hierarchy with
46cbe67b9661 More markup and spelling fixes. Raymond Hettinger <python@rcn.com> parents: 51845 diff changeset	1231 single inheritance, super can be used to refer to parent classes without
49232 5a71a6068e30 Improve docs for super(). Raymond Hettinger <python@rcn.com> parents: 49190 diff changeset	1232 naming them explicitly, thus making the code more maintainable. This use
51847 46cbe67b9661 More markup and spelling fixes. Raymond Hettinger <python@rcn.com> parents: 51845 diff changeset	1233 closely parallels the use of super in other programming languages.
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50085 diff changeset	1234
51844 1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1235 The second use case is to support cooperative multiple inheritance in a
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50085 diff changeset	1236 dynamic execution environment. This use case is unique to Python and is
c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50085 diff changeset	1237 not found in statically compiled languages or languages that only support
51862 c07d7fd27469 Fix typo. Raymond Hettinger <python@rcn.com> parents: 51851 diff changeset	1238 single inheritance. This makes it possible to implement "diamond diagrams"
49232 5a71a6068e30 Improve docs for super(). Raymond Hettinger <python@rcn.com> parents: 49190 diff changeset	1239 where multiple base classes implement the same method. Good design dictates
5a71a6068e30 Improve docs for super(). Raymond Hettinger <python@rcn.com> parents: 49190 diff changeset	1240 that this method have the same calling signature in every case (because the
51844 1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1241 order of calls is determined at runtime, because that order adapts
1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1242 to changes in the class hierarchy, and because that order can include
1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1243 sibling classes that are unknown prior to runtime).
49232 5a71a6068e30 Improve docs for super(). Raymond Hettinger <python@rcn.com> parents: 49190 diff changeset	1244
5a71a6068e30 Improve docs for super(). Raymond Hettinger <python@rcn.com> parents: 49190 diff changeset	1245 For both use cases, a typical superclass call looks like this::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1246
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1247 class C(B):
51844 1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1248 def method(self, arg):
51845 b8c4a3793d0f Restore Py2.x version of sample call to super(). Raymond Hettinger <python@rcn.com> parents: 51844 diff changeset	1249 super(C, self).method(arg)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1250
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1251 Note that :func:`super` is implemented as part of the binding process for
51844 1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1252 explicit dotted attribute lookups such as ``super().__getitem__(name)``.
49232 5a71a6068e30 Improve docs for super(). Raymond Hettinger <python@rcn.com> parents: 49190 diff changeset	1253 It does so by implementing its own :meth:`__getattribute__` method for searching
51844 1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1254 classes in a predictable order that supports cooperative multiple inheritance.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1255 Accordingly, :func:`super` is undefined for implicit lookups using statements or
51844 1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1256 operators such as ``super()[name]``.
1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1257
1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1258 Also note that :func:`super` is not limited to use inside methods. The two
1d24739511c9 Sync-up py3.1 doc updates for super(). Raymond Hettinger <python@rcn.com> parents: 51807 diff changeset	1259 argument form specifies the arguments exactly and makes the appropriate
51851 177ba122bb1b Remove reference to zero argument form of super() in 2.x docs. Raymond Hettinger <python@rcn.com> parents: 51847 diff changeset	1260 references.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1261
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1262 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1263
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1264
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1265 .. function:: tuple([iterable])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1266
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1267 Return a tuple whose items are the same and in the same order as iterable's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1268 items. iterable may be a sequence, a container that supports iteration, or an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1269 iterator object. If iterable is already a tuple, it is returned unchanged.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1270 For instance, ``tuple('abc')`` returns ``('a', 'b', 'c')`` and ``tuple([1, 2,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1271 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1272 tuple, ``()``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1273
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1274 :class:`tuple` is an immutable sequence type, as documented in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1275 :ref:`typesseq`. For other containers see the built in :class:`dict`,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1276 :class:`list`, and :class:`set` classes, and the :mod:`collections` module.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1277
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1278
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1279 .. function:: type(object)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1280
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1281 .. index:: object: type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1282
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1283 Return the type of an object. The return value is a type object. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1284 :func:`isinstance` built-in function is recommended for testing the type of an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1285 object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1286
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1287 With three arguments, :func:`type` functions as a constructor as detailed below.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1288
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1289
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1290 .. function:: type(name, bases, dict)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1291 :noindex:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1292
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1293 Return a new type object. This is essentially a dynamic form of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1294 :keyword:`class` statement. The name string is the class name and becomes the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1295 :attr:`__name__` attribute; the bases tuple itemizes the base classes and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1296 becomes the :attr:`__bases__` attribute; and the dict dictionary is the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1297 namespace containing definitions for class body and becomes the :attr:`__dict__`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1298 attribute. For example, the following two statements create identical
46013 d6f0e3e556a4 Enable doctests in functions.rst. Already found two errors :) Georg Brandl <georg@python.org> parents: 45978 diff changeset	1299 :class:`type` objects:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1300
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1301 >>> class X(object):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1302 ... a = 1
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50085 diff changeset	1303 ...
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1304 >>> X = type('X', (object,), dict(a=1))
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1305
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1306 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1307
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1308
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1309 .. function:: unichr(i)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1310
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1311 Return the Unicode string of one character whose Unicode code is the integer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1312 i. For example, ``unichr(97)`` returns the string ``u'a'``. This is the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1313 inverse of :func:`ord` for Unicode strings. The valid range for the argument
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1314 depends how Python was configured -- it may be either UCS2 [0..0xFFFF] or UCS4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1315 [0..0x10FFFF]. :exc:`ValueError` is raised otherwise. For ASCII and 8-bit
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1316 strings see :func:`chr`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1317
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1318 .. versionadded:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1319
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1320
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1321 .. function:: unicode([object[, encoding [, errors]]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1322
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1323 Return the Unicode string version of object using one of the following modes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1324
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1325 If encoding and/or errors are given, ``unicode()`` will decode the object
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1326 which can either be an 8-bit string or a character buffer using the codec for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1327 encoding. The encoding parameter is a string giving the name of an encoding;
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1328 if the encoding is not known, :exc:`LookupError` is raised. Error handling is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1329 done according to errors; this specifies the treatment of characters which are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1330 invalid in the input encoding. If errors is ``'strict'`` (the default), a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1331 :exc:`ValueError` is raised on errors, while a value of ``'ignore'`` causes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1332 errors to be silently ignored, and a value of ``'replace'`` causes the official
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1333 Unicode replacement character, ``U+FFFD``, to be used to replace input
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1334 characters which cannot be decoded. See also the :mod:`codecs` module.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1335
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1336 If no optional parameters are given, ``unicode()`` will mimic the behaviour of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1337 ``str()`` except that it returns Unicode strings instead of 8-bit strings. More
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1338 precisely, if object is a Unicode string or subclass it will return that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1339 Unicode string without any additional decoding applied.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1340
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1341 For objects which provide a :meth:`__unicode__` method, it will call this method
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1342 without arguments to create a Unicode string. For all other objects, the 8-bit
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1343 string version or representation is requested and then converted to a Unicode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1344 string using the codec for the default encoding in ``'strict'`` mode.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1345
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1346 For more information on Unicode strings see :ref:`typesseq` which describes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1347 sequence functionality (Unicode strings are sequences), and also the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1348 string-specific methods described in the :ref:`string-methods` section. To
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1349 output formatted strings use template strings or the ``%`` operator described
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1350 in the :ref:`string-formatting` section. In addition see the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1351 :ref:`stringservices` section. See also :func:`str`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1352
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1353 .. versionadded:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1354
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1355 .. versionchanged:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1356 Support for :meth:`__unicode__` added.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1357
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1358
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1359 .. function:: vars([object])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1360
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1361 Without arguments, return a dictionary corresponding to the current local symbol
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1362 table. With a module, class or class instance object as argument (or anything
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1363 else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
52483 4239fa562735 #5199: make warning about vars() assignment more visible. Georg Brandl <georg@python.org> parents: 52220 diff changeset	1364 to the object's symbol table.
4239fa562735 #5199: make warning about vars() assignment more visible. Georg Brandl <georg@python.org> parents: 52220 diff changeset	1365
53508 57812944c961 Demote warnings to notices where appropriate, following the goal that as few "red box" warnings Georg Brandl <georg@python.org> parents: 53304 diff changeset	1366 .. note::
52483 4239fa562735 #5199: make warning about vars() assignment more visible. Georg Brandl <georg@python.org> parents: 52220 diff changeset	1367
4239fa562735 #5199: make warning about vars() assignment more visible. Georg Brandl <georg@python.org> parents: 52220 diff changeset	1368 The returned dictionary should not be modified:
4239fa562735 #5199: make warning about vars() assignment more visible. Georg Brandl <georg@python.org> parents: 52220 diff changeset	1369 the effects on the corresponding symbol table are undefined. [#]_
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1370
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1371
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1372 .. function:: xrange([start,] stop[, step])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1373
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1374 This function is very similar to :func:`range`, but returns an "xrange object"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1375 instead of a list. This is an opaque sequence type which yields the same values
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1376 as the corresponding list, without actually storing them all simultaneously.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1377 The advantage of :func:`xrange` over :func:`range` is minimal (since
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1378 :func:`xrange` still has to create the values when asked for them) except when a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1379 very large range is used on a memory-starved machine or when all of the range's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1380 elements are never used (such as when the loop is usually terminated with
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1381 :keyword:`break`).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1382
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1383 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1384
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1385 :func:`xrange` is intended to be simple and fast. Implementations may impose
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1386 restrictions to achieve this. The C implementation of Python restricts all
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1387 arguments to native C longs ("short" Python integers), and also requires that
51724 302263e3c8f1 Add some cross-references to the docs. Simplify the python code equivalent for izip(). Supply an optional argument for the nth() recipe. Raymond Hettinger <python@rcn.com> parents: 51679 diff changeset	1388 the number of elements fit in a native C long. If a larger range is needed,
302263e3c8f1 Add some cross-references to the docs. Simplify the python code equivalent for izip(). Supply an optional argument for the nth() recipe. Raymond Hettinger <python@rcn.com> parents: 51679 diff changeset	1389 an alternate version can be crafted using the :mod:`itertools` module:
302263e3c8f1 Add some cross-references to the docs. Simplify the python code equivalent for izip(). Supply an optional argument for the nth() recipe. Raymond Hettinger <python@rcn.com> parents: 51679 diff changeset	1390 ``islice(count(start, step), (stop-start+step-1)//step)``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1391
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1392
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1393 .. function:: zip([iterable, ...])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1394
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1395 This function returns a list of tuples, where the i-th tuple contains the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1396 i-th element from each of the argument sequences or iterables. The returned
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1397 list is truncated in length to the length of the shortest argument sequence.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1398 When there are multiple arguments which are all of the same length, :func:`zip`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1399 is similar to :func:`map` with an initial argument of ``None``. With a single
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1400 sequence argument, it returns a list of 1-tuples. With no arguments, it returns
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1401 an empty list.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1402
44878 56f0fbaeb67f Give zip() the same guarantee as izip() for left-to-right evaluation. Raymond Hettinger <python@rcn.com> parents: 44821 diff changeset	1403 The left-to-right evaluation order of the iterables is guaranteed. This
56f0fbaeb67f Give zip() the same guarantee as izip() for left-to-right evaluation. Raymond Hettinger <python@rcn.com> parents: 44821 diff changeset	1404 makes possible an idiom for clustering a data series into n-length groups
56f0fbaeb67f Give zip() the same guarantee as izip() for left-to-right evaluation. Raymond Hettinger <python@rcn.com> parents: 44821 diff changeset	1405 using ``zip([iter(s)]n)``.
56f0fbaeb67f Give zip() the same guarantee as izip() for left-to-right evaluation. Raymond Hettinger <python@rcn.com> parents: 44821 diff changeset	1406
49489 342f70189ea9 talk about how you can unzip with zip Benjamin Peterson <benjamin@python.org> parents: 49431 diff changeset	1407 :func:`zip` in conjunction with the ``*`` operator can be used to unzip a
342f70189ea9 talk about how you can unzip with zip Benjamin Peterson <benjamin@python.org> parents: 49431 diff changeset	1408 list::
342f70189ea9 talk about how you can unzip with zip Benjamin Peterson <benjamin@python.org> parents: 49431 diff changeset	1409
342f70189ea9 talk about how you can unzip with zip Benjamin Peterson <benjamin@python.org> parents: 49431 diff changeset	1410 >>> x = [1, 2, 3]
342f70189ea9 talk about how you can unzip with zip Benjamin Peterson <benjamin@python.org> parents: 49431 diff changeset	1411 >>> y = [4, 5, 6]
342f70189ea9 talk about how you can unzip with zip Benjamin Peterson <benjamin@python.org> parents: 49431 diff changeset	1412 >>> zipped = zip(x, y)
342f70189ea9 talk about how you can unzip with zip Benjamin Peterson <benjamin@python.org> parents: 49431 diff changeset	1413 >>> zipped
342f70189ea9 talk about how you can unzip with zip Benjamin Peterson <benjamin@python.org> parents: 49431 diff changeset	1414 [(1, 4), (2, 5), (3, 6)]
342f70189ea9 talk about how you can unzip with zip Benjamin Peterson <benjamin@python.org> parents: 49431 diff changeset	1415 >>> x2, y2 = zip(*zipped)
54244 6074fb411621 #6084: fix example. Georg Brandl <georg@python.org> parents: 53508 diff changeset	1416 >>> x == list(x2) and y == list(y2)
49489 342f70189ea9 talk about how you can unzip with zip Benjamin Peterson <benjamin@python.org> parents: 49431 diff changeset	1417 True
342f70189ea9 talk about how you can unzip with zip Benjamin Peterson <benjamin@python.org> parents: 49431 diff changeset	1418
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1419 .. versionadded:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1420
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1421 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1422 Formerly, :func:`zip` required at least one argument and ``zip()`` raised a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1423 :exc:`TypeError` instead of returning an empty list.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1424
50020 a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1425
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1426 .. function:: __import__(name[, globals[, locals[, fromlist[, level]]]])
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1427
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1428 .. index::
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1429 statement: import
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1430 module: imp
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1431
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1432 .. note::
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1433
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1434 This is an advanced function that is not needed in everyday Python
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1435 programming.
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1436
50085 a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1437 This function is invoked by the :keyword:`import` statement. It can be
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1438 replaced (by importing the :mod:`builtins` module and assigning to
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1439 ``builtins.__import__``) in order to change semantics of the
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1440 :keyword:`import` statement, but nowadays it is usually simpler to use import
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1441 hooks (see :pep:`302`). Direct use of :func:`__import__` is rare, except in
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1442 cases where you want to import a module whose name is only known at runtime.
50020 a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1443
50085 a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1444 The function imports the module name, potentially using the given globals
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1445 and locals to determine how to interpret the name in a package context.
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1446 The fromlist gives the names of objects or submodules that should be
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1447 imported from the module given by name. The standard implementation does
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1448 not use its locals argument at all, and uses its globals only to
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1449 determine the package context of the :keyword:`import` statement.
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1450
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1451 level specifies whether to use absolute or relative imports. The default
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1452 is ``-1`` which indicates both absolute and relative imports will be
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1453 attempted. ``0`` means only perform absolute imports. Positive values for
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1454 level indicate the number of parent directories to search relative to the
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1455 directory of the module calling :func:`__import__`.
50020 a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1456
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1457 When the name variable is of the form ``package.module``, normally, the
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1458 top-level package (the name up till the first dot) is returned, not the
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1459 module named by name. However, when a non-empty fromlist argument is
50085 a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1460 given, the module named by name is returned.
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1461
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1462 For example, the statement ``import spam`` results in bytecode resembling the
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1463 following code::
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50085 diff changeset	1464
50085 a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1465 spam = __import__('spam', globals(), locals(), [], -1)
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1466
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1467 The statement ``import spam.ham`` results in this call::
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1468
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1469 spam = __import__('spam.ham', globals(), locals(), [], -1)
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1470
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1471 Note how :func:`__import__` returns the toplevel module here because this is
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1472 the object that is bound to a name by the :keyword:`import` statement.
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1473
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1474 On the other hand, the statement ``from spam.ham import eggs, sausage as
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1475 saus`` results in ::
50020 a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1476
50085 a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1477 _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], -1)
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1478 eggs = _temp.eggs
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1479 saus = _temp.sausage
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1480
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1481 Here, the ``spam.ham`` module is returned from :func:`__import__`. From this
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1482 object, the names to import are retrieved and assigned to their respective
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1483 names.
50020 a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1484
50085 a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1485 If you simply want to import a module (potentially within a package) by name,
54249 840a09de68c3 s/use/call/ Georg Brandl <georg@python.org> parents: 54248 diff changeset	1486 you can call :func:`__import__` and then look it up in :data:`sys.modules`::
50085 a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1487
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1488 >>> import sys
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1489 >>> name = 'foo.bar.baz'
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1490 >>> __import__(name)
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1491 <module 'foo' from ...>
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1492 >>> baz = sys.modules[name]
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1493 >>> baz
a9e30250ed20 #4457: rewrite __import__() documentation. Georg Brandl <georg@python.org> parents: 50020 diff changeset	1494 <module 'foo.bar.baz' from ...>
50020 a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1495
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1496 .. versionchanged:: 2.5
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1497 The level parameter was added.
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1498
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1499 .. versionchanged:: 2.5
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1500 Keyword support for parameters was added.
a3ab95345b52 Move __import__ to the bottom of the functions list. Georg Brandl <georg@python.org> parents: 49693 diff changeset	1501
44547 42646a872772 Remove latex trace. Georg Brandl <georg@python.org> parents: 44533 diff changeset	1502 .. ---------------------------------------------------------------------------
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1503
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1504
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1505 .. _non-essential-built-in-funcs:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1506
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1507 Non-essential Built-in Functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1508 ================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1509
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1510 There are several built-in functions that are no longer essential to learn, know
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1511 or use in modern Python programming. They have been kept here to maintain
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1512 backwards compatibility with programs written for older versions of Python.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1513
47937 38d3a50defec fix various doc typos #3320 Benjamin Peterson <benjamin@python.org> parents: 46982 diff changeset	1514 Python programmers, trainers, students and book writers should feel free to
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1515 bypass these functions without concerns about missing something important.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1516
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1517
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1518 .. function:: apply(function, args[, keywords])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1519
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1520 The function argument must be a callable object (a user-defined or built-in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1521 function or method, or a class object) and the args argument must be a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1522 sequence. The function is called with args as the argument list; the number
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1523 of arguments is the length of the tuple. If the optional keywords argument is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1524 present, it must be a dictionary whose keys are strings. It specifies keyword
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1525 arguments to be added to the end of the argument list. Calling :func:`apply` is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1526 different from just calling ``function(args)``, since in that case there is
46566 5238327f45bd #2668: nit in apply() docs. Georg Brandl <georg@python.org> parents: 46162 diff changeset	1527 always exactly one argument. The use of :func:`apply` is equivalent to
43596 548d06e98f56 Clarify wording for apply(). Georg Brandl <georg@python.org> parents: 43431 diff changeset	1528 ``function(args, *keywords)``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1529
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1530 .. deprecated:: 2.3
43596 548d06e98f56 Clarify wording for apply(). Georg Brandl <georg@python.org> parents: 43431 diff changeset	1531 Use the extended call syntax with ``args`` and ``*keywords`` instead.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1532
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1533
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1534 .. function:: buffer(object[, offset[, size]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1535
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1536 The object argument must be an object that supports the buffer call interface
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1537 (such as strings, arrays, and buffers). A new buffer object will be created
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1538 which references the object argument. The buffer object will be a slice from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1539 the beginning of object (or from the specified offset). The slice will
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1540 extend to the end of object (or will have a length given by the size
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1541 argument).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1542
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1543
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1544 .. function:: coerce(x, y)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1545
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1546 Return a tuple consisting of the two numeric arguments converted to a common
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1547 type, using the same rules as used by arithmetic operations. If coercion is not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1548 possible, raise :exc:`TypeError`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1549
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1550
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1551 .. function:: intern(string)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1552
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1553 Enter string in the table of "interned" strings and return the interned string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1554 -- which is string itself or a copy. Interning strings is useful to gain a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1555 little performance on dictionary lookup -- if the keys in a dictionary are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1556 interned, and the lookup key is interned, the key comparisons (after hashing)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1557 can be done by a pointer compare instead of a string compare. Normally, the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1558 names used in Python programs are automatically interned, and the dictionaries
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1559 used to hold module, class or instance attributes have interned keys.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1560
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1561 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1562 Interned strings are not immortal (like they used to be in Python 2.2 and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1563 before); you must keep a reference to the return value of :func:`intern` around
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1564 to benefit from it.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1565
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1566 .. rubric:: Footnotes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1567
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1568 .. [#] It is used relatively rarely so does not warrant being made into a statement.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1569
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1570 .. [#] Specifying a buffer size currently has no effect on systems that don't have
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1571 :cfunc:`setvbuf`. The interface to specify the buffer size is not done using a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1572 method that calls :cfunc:`setvbuf`, because that may dump core when called after
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1573 any I/O has been performed, and there's no reliable way to determine whether
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1574 this is the case.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1575
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1576 .. [#] In the current implementation, local variable bindings cannot normally be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1577 affected this way, but variables retrieved from other scopes (such as modules)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1578 can be. This may change.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1579

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/functions.rst @ 54294:dba767bc3155 legacy-trunk