blob: 43164af5e2245aefdffc4def5566788d531831a6 [file] [log] [blame]
Georg Brandl68ee3a52008-03-25 07:21:32 +00001.. XXX document all delegations to __special__ methods
Georg Brandl116aa622007-08-15 14:28:22 +00002.. _built-in-funcs:
3
4Built-in Functions
5==================
6
Georg Brandl42514812008-05-05 21:05:32 +00007The Python interpreter has a number of functions and types built into it that
8are always available. They are listed here in alphabetical order.
Georg Brandl116aa622007-08-15 14:28:22 +00009
Ezio Melottif21c7ed2010-11-24 20:18:02 +000010=================== ================= ================== ================ ====================
11.. .. Built-in Functions .. ..
12=================== ================= ================== ================ ====================
Éric Araujo9edd9f02011-09-01 23:08:55 +020013:func:`abs` |func-dict|_ :func:`help` :func:`min` :func:`setattr`
Ezio Melotti1de91152010-11-28 04:18:54 +000014:func:`all` :func:`dir` :func:`hex` :func:`next` :func:`slice`
15:func:`any` :func:`divmod` :func:`id` :func:`object` :func:`sorted`
16:func:`ascii` :func:`enumerate` :func:`input` :func:`oct` :func:`staticmethod`
Chris Jerdonekbb4e9412012-11-28 01:38:40 -080017:func:`bin` :func:`eval` :func:`int` :func:`open` |func-str|_
Ezio Melotti1de91152010-11-28 04:18:54 +000018:func:`bool` :func:`exec` :func:`isinstance` :func:`ord` :func:`sum`
19:func:`bytearray` :func:`filter` :func:`issubclass` :func:`pow` :func:`super`
Nick Coghlan83c0ae52012-08-21 17:42:52 +100020:func:`bytes` :func:`float` :func:`iter` :func:`print` |func-tuple|_
Ezio Melotti1de91152010-11-28 04:18:54 +000021:func:`callable` :func:`format` :func:`len` :func:`property` :func:`type`
Nick Coghlan83c0ae52012-08-21 17:42:52 +100022:func:`chr` |func-frozenset|_ |func-list|_ |func-range|_ :func:`vars`
Ezio Melotti17f9b3d2010-11-24 22:02:18 +000023:func:`classmethod` :func:`getattr` :func:`locals` :func:`repr` :func:`zip`
24:func:`compile` :func:`globals` :func:`map` :func:`reversed` :func:`__import__`
25:func:`complex` :func:`hasattr` :func:`max` :func:`round`
Éric Araujo9edd9f02011-09-01 23:08:55 +020026:func:`delattr` :func:`hash` |func-memoryview|_ |func-set|_
Ezio Melottif21c7ed2010-11-24 20:18:02 +000027=================== ================= ================== ================ ====================
Georg Brandl116aa622007-08-15 14:28:22 +000028
Éric Araujo9edd9f02011-09-01 23:08:55 +020029.. using :func:`dict` would create a link to another page, so local targets are
30 used, with replacement texts to make the output in the table consistent
31
32.. |func-dict| replace:: ``dict()``
33.. |func-frozenset| replace:: ``frozenset()``
34.. |func-memoryview| replace:: ``memoryview()``
35.. |func-set| replace:: ``set()``
Nick Coghlan83c0ae52012-08-21 17:42:52 +100036.. |func-list| replace:: ``list()``
Chris Jerdonekbb4e9412012-11-28 01:38:40 -080037.. |func-str| replace:: ``str()``
Nick Coghlan83c0ae52012-08-21 17:42:52 +100038.. |func-tuple| replace:: ``tuple()``
39.. |func-range| replace:: ``range()``
Éric Araujo9edd9f02011-09-01 23:08:55 +020040
41
Georg Brandl116aa622007-08-15 14:28:22 +000042.. function:: abs(x)
43
Georg Brandlba956ae2007-11-29 17:24:34 +000044 Return the absolute value of a number. The argument may be an
Georg Brandl116aa622007-08-15 14:28:22 +000045 integer or a floating point number. If the argument is a complex number, its
46 magnitude is returned.
47
48
49.. function:: all(iterable)
50
Georg Brandl0192bff2009-04-27 16:49:41 +000051 Return True if all elements of the *iterable* are true (or if the iterable
52 is empty). Equivalent to::
Georg Brandl116aa622007-08-15 14:28:22 +000053
54 def all(iterable):
55 for element in iterable:
56 if not element:
57 return False
58 return True
59
Georg Brandl116aa622007-08-15 14:28:22 +000060
61.. function:: any(iterable)
62
Georg Brandl0192bff2009-04-27 16:49:41 +000063 Return True if any element of the *iterable* is true. If the iterable
64 is empty, return False. Equivalent to::
Georg Brandl116aa622007-08-15 14:28:22 +000065
66 def any(iterable):
67 for element in iterable:
68 if element:
69 return True
70 return False
71
Georg Brandl116aa622007-08-15 14:28:22 +000072
Georg Brandl559e5d72008-06-11 18:37:52 +000073.. function:: ascii(object)
74
75 As :func:`repr`, return a string containing a printable representation of an
76 object, but escape the non-ASCII characters in the string returned by
77 :func:`repr` using ``\x``, ``\u`` or ``\U`` escapes. This generates a string
78 similar to that returned by :func:`repr` in Python 2.
79
80
Georg Brandl116aa622007-08-15 14:28:22 +000081.. function:: bin(x)
82
83 Convert an integer number to a binary string. The result is a valid Python
84 expression. If *x* is not a Python :class:`int` object, it has to define an
85 :meth:`__index__` method that returns an integer.
86
Georg Brandl116aa622007-08-15 14:28:22 +000087
88.. function:: bool([x])
89
Éric Araujo18ddf822011-09-01 23:10:36 +020090 Convert a value to a Boolean, using the standard :ref:`truth testing
91 procedure <truth>`. If *x* is false or omitted, this returns ``False``;
92 otherwise it returns ``True``. :class:`bool` is also a class, which is a
93 subclass of :class:`int` (see :ref:`typesnumeric`). Class :class:`bool`
94 cannot be subclassed further. Its only instances are ``False`` and
95 ``True`` (see :ref:`bltin-boolean-values`).
Georg Brandl116aa622007-08-15 14:28:22 +000096
97 .. index:: pair: Boolean; type
98
Georg Brandl116aa622007-08-15 14:28:22 +000099
Nick Coghlan83c0ae52012-08-21 17:42:52 +1000100.. _func-bytearray:
Georg Brandl036490d2009-05-17 13:00:36 +0000101.. function:: bytearray([source[, encoding[, errors]]])
Georg Brandl85eb8c12007-08-31 16:33:38 +0000102
Georg Brandl24eac032007-11-22 14:16:00 +0000103 Return a new array of bytes. The :class:`bytearray` type is a mutable
Georg Brandl95414632007-11-22 11:00:28 +0000104 sequence of integers in the range 0 <= x < 256. It has most of the usual
105 methods of mutable sequences, described in :ref:`typesseq-mutable`, as well
Antoine Pitroub85b3af2010-11-20 19:36:05 +0000106 as most methods that the :class:`bytes` type has, see :ref:`bytes-methods`.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000107
Georg Brandl036490d2009-05-17 13:00:36 +0000108 The optional *source* parameter can be used to initialize the array in a few
Georg Brandl85eb8c12007-08-31 16:33:38 +0000109 different ways:
110
111 * If it is a *string*, you must also give the *encoding* (and optionally,
Georg Brandlf6945182008-02-01 11:56:49 +0000112 *errors*) parameters; :func:`bytearray` then converts the string to
Guido van Rossum98297ee2007-11-06 21:34:58 +0000113 bytes using :meth:`str.encode`.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000114
115 * If it is an *integer*, the array will have that size and will be
116 initialized with null bytes.
117
118 * If it is an object conforming to the *buffer* interface, a read-only buffer
119 of the object will be used to initialize the bytes array.
120
Guido van Rossum98297ee2007-11-06 21:34:58 +0000121 * If it is an *iterable*, it must be an iterable of integers in the range
122 ``0 <= x < 256``, which are used as the initial contents of the array.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000123
124 Without an argument, an array of size 0 is created.
125
Chris Jerdonek006d9072012-10-12 20:28:26 -0700126 See also :ref:`binaryseq` and :ref:`typebytearray`.
127
Georg Brandl85eb8c12007-08-31 16:33:38 +0000128
Nick Coghlan83c0ae52012-08-21 17:42:52 +1000129.. _func-bytes:
Georg Brandl036490d2009-05-17 13:00:36 +0000130.. function:: bytes([source[, encoding[, errors]]])
Guido van Rossum98297ee2007-11-06 21:34:58 +0000131
132 Return a new "bytes" object, which is an immutable sequence of integers in
133 the range ``0 <= x < 256``. :class:`bytes` is an immutable version of
Georg Brandl95414632007-11-22 11:00:28 +0000134 :class:`bytearray` -- it has the same non-mutating methods and the same
135 indexing and slicing behavior.
Georg Brandl48310cd2009-01-03 21:18:54 +0000136
Georg Brandl476b3552009-04-29 06:37:12 +0000137 Accordingly, constructor arguments are interpreted as for :func:`bytearray`.
Guido van Rossum98297ee2007-11-06 21:34:58 +0000138
139 Bytes objects can also be created with literals, see :ref:`strings`.
140
Chris Jerdonek006d9072012-10-12 20:28:26 -0700141 See also :ref:`binaryseq`, :ref:`typebytes`, and :ref:`bytes-methods`.
142
Guido van Rossum98297ee2007-11-06 21:34:58 +0000143
Antoine Pitroue71362d2010-11-27 22:00:11 +0000144.. function:: callable(object)
145
146 Return :const:`True` if the *object* argument appears callable,
147 :const:`False` if not. If this returns true, it is still possible that a
148 call fails, but if it is false, calling *object* will never succeed.
149 Note that classes are callable (calling a class returns a new instance);
150 instances are callable if their class has a :meth:`__call__` method.
151
152 .. versionadded:: 3.2
153 This function was first removed in Python 3.0 and then brought back
154 in Python 3.2.
155
156
Georg Brandl116aa622007-08-15 14:28:22 +0000157.. function:: chr(i)
158
Alexander Belopolsky5d4dd3e2010-11-18 18:50:13 +0000159 Return the string representing a character whose Unicode codepoint is the integer
Georg Brandl85eb8c12007-08-31 16:33:38 +0000160 *i*. For example, ``chr(97)`` returns the string ``'a'``. This is the
Alexander Belopolsky5d4dd3e2010-11-18 18:50:13 +0000161 inverse of :func:`ord`. The valid range for the argument is from 0 through
162 1,114,111 (0x10FFFF in base 16). :exc:`ValueError` will be raised if *i* is
163 outside that range.
164
Georg Brandl116aa622007-08-15 14:28:22 +0000165
166.. function:: classmethod(function)
167
168 Return a class method for *function*.
169
170 A class method receives the class as implicit first argument, just like an
171 instance method receives the instance. To declare a class method, use this
172 idiom::
173
174 class C:
175 @classmethod
176 def f(cls, arg1, arg2, ...): ...
177
Christian Heimesd8654cf2007-12-02 15:22:16 +0000178 The ``@classmethod`` form is a function :term:`decorator` -- see the description
179 of function definitions in :ref:`function` for details.
Georg Brandl116aa622007-08-15 14:28:22 +0000180
181 It can be called either on the class (such as ``C.f()``) or on an instance (such
182 as ``C().f()``). The instance is ignored except for its class. If a class
183 method is called for a derived class, the derived class object is passed as the
184 implied first argument.
185
186 Class methods are different than C++ or Java static methods. If you want those,
187 see :func:`staticmethod` in this section.
188
189 For more information on class methods, consult the documentation on the standard
190 type hierarchy in :ref:`types`.
191
Georg Brandl116aa622007-08-15 14:28:22 +0000192
Georg Brandl8334fd92010-12-04 10:26:46 +0000193.. function:: compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1)
Georg Brandl116aa622007-08-15 14:28:22 +0000194
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000195 Compile the *source* into a code or AST object. Code objects can be executed
Ezio Melotti6e40e272010-01-04 09:29:10 +0000196 by :func:`exec` or :func:`eval`. *source* can either be a string or an AST
Benjamin Peterson45abfbc2009-12-13 00:32:14 +0000197 object. Refer to the :mod:`ast` module documentation for information on how
198 to work with AST objects.
Georg Brandl116aa622007-08-15 14:28:22 +0000199
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000200 The *filename* argument should give the file from which the code was read;
201 pass some recognizable value if it wasn't read from a file (``'<string>'`` is
202 commonly used).
203
204 The *mode* argument specifies what kind of code must be compiled; it can be
205 ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
206 consists of a single expression, or ``'single'`` if it consists of a single
207 interactive statement (in the latter case, expression statements that
R. David Murray66011262009-06-25 17:37:57 +0000208 evaluate to something other than ``None`` will be printed).
Georg Brandl116aa622007-08-15 14:28:22 +0000209
Georg Brandle06de8b2008-05-05 21:42:51 +0000210 The optional arguments *flags* and *dont_inherit* control which future
211 statements (see :pep:`236`) affect the compilation of *source*. If neither
212 is present (or both are zero) the code is compiled with those future
213 statements that are in effect in the code that is calling compile. If the
214 *flags* argument is given and *dont_inherit* is not (or is zero) then the
Georg Brandl116aa622007-08-15 14:28:22 +0000215 future statements specified by the *flags* argument are used in addition to
216 those that would be used anyway. If *dont_inherit* is a non-zero integer then
Georg Brandle06de8b2008-05-05 21:42:51 +0000217 the *flags* argument is it -- the future statements in effect around the call
218 to compile are ignored.
Georg Brandl116aa622007-08-15 14:28:22 +0000219
Christian Heimesfaf2f632008-01-06 16:59:19 +0000220 Future statements are specified by bits which can be bitwise ORed together to
Georg Brandl116aa622007-08-15 14:28:22 +0000221 specify multiple statements. The bitfield required to specify a given feature
222 can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
223 instance in the :mod:`__future__` module.
224
Georg Brandl8334fd92010-12-04 10:26:46 +0000225 The argument *optimize* specifies the optimization level of the compiler; the
226 default value of ``-1`` selects the optimization level of the interpreter as
227 given by :option:`-O` options. Explicit levels are ``0`` (no optimization;
228 ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)
229 or ``2`` (docstrings are removed too).
230
Christian Heimes7f044312008-01-06 17:05:40 +0000231 This function raises :exc:`SyntaxError` if the compiled source is invalid,
232 and :exc:`TypeError` if the source contains null bytes.
233
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000234 .. note::
235
Benjamin Peterson20211002009-11-25 18:34:42 +0000236 When compiling a string with multi-line code in ``'single'`` or
Benjamin Petersonaeaa5922009-11-13 00:17:59 +0000237 ``'eval'`` mode, input must be terminated by at least one newline
238 character. This is to facilitate detection of incomplete and complete
239 statements in the :mod:`code` module.
240
Benjamin Petersonaeaa5922009-11-13 00:17:59 +0000241 .. versionchanged:: 3.2
242 Allowed use of Windows and Mac newlines. Also input in ``'exec'`` mode
Georg Brandl8334fd92010-12-04 10:26:46 +0000243 does not have to end in a newline anymore. Added the *optimize* parameter.
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000244
Georg Brandl116aa622007-08-15 14:28:22 +0000245
246.. function:: complex([real[, imag]])
247
248 Create a complex number with the value *real* + *imag*\*j or convert a string or
249 number to a complex number. If the first parameter is a string, it will be
250 interpreted as a complex number and the function must be called without a second
251 parameter. The second parameter can never be a string. Each argument may be any
252 numeric type (including complex). If *imag* is omitted, it defaults to zero and
Georg Brandl5c106642007-11-29 17:41:05 +0000253 the function serves as a numeric conversion function like :func:`int`
254 and :func:`float`. If both arguments are omitted, returns ``0j``.
Georg Brandl116aa622007-08-15 14:28:22 +0000255
Mark Dickinson328dd0d2012-03-10 16:09:35 +0000256 .. note::
257
258 When converting from a string, the string must not contain whitespace
259 around the central ``+`` or ``-`` operator. For example,
260 ``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` raises
261 :exc:`ValueError`.
262
Georg Brandl116aa622007-08-15 14:28:22 +0000263 The complex type is described in :ref:`typesnumeric`.
264
265
266.. function:: delattr(object, name)
267
268 This is a relative of :func:`setattr`. The arguments are an object and a
269 string. The string must be the name of one of the object's attributes. The
270 function deletes the named attribute, provided the object allows it. For
271 example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
272
273
Éric Araujo9edd9f02011-09-01 23:08:55 +0200274.. _func-dict:
Chris Jerdonekf3413172012-10-13 03:22:33 -0700275.. function:: dict(**kwarg)
276 dict(mapping, **kwarg)
277 dict(iterable, **kwarg)
Georg Brandl116aa622007-08-15 14:28:22 +0000278 :noindex:
279
Chris Jerdonekf3413172012-10-13 03:22:33 -0700280 Create a new dictionary. The :class:`dict` object is the dictionary class.
281 See :class:`dict` and :ref:`typesmapping` for documentation about this
282 class.
Georg Brandl116aa622007-08-15 14:28:22 +0000283
Chris Jerdonekf3413172012-10-13 03:22:33 -0700284 For other containers see the built-in :class:`list`, :class:`set`, and
285 :class:`tuple` classes, as well as the :mod:`collections` module.
Georg Brandl116aa622007-08-15 14:28:22 +0000286
287
288.. function:: dir([object])
289
290 Without arguments, return the list of names in the current local scope. With an
291 argument, attempt to return a list of valid attributes for that object.
292
293 If the object has a method named :meth:`__dir__`, this method will be called and
294 must return the list of attributes. This allows objects that implement a custom
295 :func:`__getattr__` or :func:`__getattribute__` function to customize the way
296 :func:`dir` reports their attributes.
297
298 If the object does not provide :meth:`__dir__`, the function tries its best to
299 gather information from the object's :attr:`__dict__` attribute, if defined, and
300 from its type object. The resulting list is not necessarily complete, and may
301 be inaccurate when the object has a custom :func:`__getattr__`.
302
303 The default :func:`dir` mechanism behaves differently with different types of
304 objects, as it attempts to produce the most relevant, rather than complete,
305 information:
306
307 * If the object is a module object, the list contains the names of the module's
308 attributes.
309
310 * If the object is a type or class object, the list contains the names of its
311 attributes, and recursively of the attributes of its bases.
312
313 * Otherwise, the list contains the object's attributes' names, the names of its
314 class's attributes, and recursively of the attributes of its class's base
315 classes.
316
Christian Heimesfe337bf2008-03-23 21:54:12 +0000317 The resulting list is sorted alphabetically. For example:
318
319 >>> import struct
Raymond Hettinger90289282011-06-01 16:17:23 -0700320 >>> dir() # show the names in the module namespace
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300321 ['__builtins__', '__name__', 'struct']
322 >>> dir(struct) # show the names in the struct module # doctest: +SKIP
323 ['Struct', '__all__', '__builtins__', '__cached__', '__doc__', '__file__',
324 '__initializing__', '__loader__', '__name__', '__package__',
325 '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
Christian Heimesfe337bf2008-03-23 21:54:12 +0000326 'unpack', 'unpack_from']
Ezio Melottiaf8838f2013-03-11 09:30:21 +0200327 >>> class Shape:
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300328 ... def __dir__(self):
329 ... return ['area', 'perimeter', 'location']
Raymond Hettinger90289282011-06-01 16:17:23 -0700330 >>> s = Shape()
331 >>> dir(s)
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300332 ['area', 'location', 'perimeter']
Georg Brandl116aa622007-08-15 14:28:22 +0000333
334 .. note::
335
336 Because :func:`dir` is supplied primarily as a convenience for use at an
Georg Brandl036490d2009-05-17 13:00:36 +0000337 interactive prompt, it tries to supply an interesting set of names more
338 than it tries to supply a rigorously or consistently defined set of names,
339 and its detailed behavior may change across releases. For example,
340 metaclass attributes are not in the result list when the argument is a
341 class.
Georg Brandl116aa622007-08-15 14:28:22 +0000342
343
344.. function:: divmod(a, b)
345
346 Take two (non complex) numbers as arguments and return a pair of numbers
Georg Brandl036490d2009-05-17 13:00:36 +0000347 consisting of their quotient and remainder when using integer division. With
348 mixed operand types, the rules for binary arithmetic operators apply. For
349 integers, the result is the same as ``(a // b, a % b)``. For floating point
350 numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a /
351 b)`` but may be 1 less than that. In any case ``q * b + a % b`` is very
352 close to *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0
353 <= abs(a % b) < abs(b)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000354
Georg Brandl116aa622007-08-15 14:28:22 +0000355
Georg Brandl036490d2009-05-17 13:00:36 +0000356.. function:: enumerate(iterable, start=0)
Georg Brandl116aa622007-08-15 14:28:22 +0000357
Georg Brandld11ae5d2008-05-16 13:27:32 +0000358 Return an enumerate object. *iterable* must be a sequence, an
Ezio Melotti7fa82222012-10-12 13:42:08 +0300359 :term:`iterator`, or some other object which supports iteration.
360 The :meth:`~iterator.__next__` method of the iterator returned by
361 :func:`enumerate` returns a tuple containing a count (from *start* which
362 defaults to 0) and the values obtained from iterating over *iterable*.
Georg Brandl116aa622007-08-15 14:28:22 +0000363
Raymond Hettinger9d3df6d2011-06-25 15:00:14 +0200364 >>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
365 >>> list(enumerate(seasons))
366 [(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
367 >>> list(enumerate(seasons, start=1))
368 [(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]
Raymond Hettinger90289282011-06-01 16:17:23 -0700369
370 Equivalent to::
371
372 def enumerate(sequence, start=0):
373 n = start
374 for elem in sequence:
375 yield n, elem
376 n += 1
Georg Brandl116aa622007-08-15 14:28:22 +0000377
Georg Brandl116aa622007-08-15 14:28:22 +0000378
Georg Brandl036490d2009-05-17 13:00:36 +0000379.. function:: eval(expression, globals=None, locals=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000380
381 The arguments are a string and optional globals and locals. If provided,
382 *globals* must be a dictionary. If provided, *locals* can be any mapping
383 object.
384
Georg Brandl116aa622007-08-15 14:28:22 +0000385 The *expression* argument is parsed and evaluated as a Python expression
386 (technically speaking, a condition list) using the *globals* and *locals*
Georg Brandl9afde1c2007-11-01 20:32:30 +0000387 dictionaries as global and local namespace. If the *globals* dictionary is
Georg Brandl116aa622007-08-15 14:28:22 +0000388 present and lacks '__builtins__', the current globals are copied into *globals*
389 before *expression* is parsed. This means that *expression* normally has full
Georg Brandl1a3284e2007-12-02 09:40:06 +0000390 access to the standard :mod:`builtins` module and restricted environments are
Georg Brandl116aa622007-08-15 14:28:22 +0000391 propagated. If the *locals* dictionary is omitted it defaults to the *globals*
392 dictionary. If both dictionaries are omitted, the expression is executed in the
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000393 environment where :func:`eval` is called. The return value is the result of
Christian Heimesfe337bf2008-03-23 21:54:12 +0000394 the evaluated expression. Syntax errors are reported as exceptions. Example:
Georg Brandl116aa622007-08-15 14:28:22 +0000395
396 >>> x = 1
Georg Brandl6911e3c2007-09-04 07:15:32 +0000397 >>> eval('x+1')
Georg Brandl116aa622007-08-15 14:28:22 +0000398 2
399
Benjamin Peterson3e4f0552008-09-02 00:31:15 +0000400 This function can also be used to execute arbitrary code objects (such as
401 those created by :func:`compile`). In this case pass a code object instead
402 of a string. If the code object has been compiled with ``'exec'`` as the
Georg Brandl1f70cdf2010-03-21 09:04:24 +0000403 *mode* argument, :func:`eval`\'s return value will be ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000404
405 Hints: dynamic execution of statements is supported by the :func:`exec`
406 function. The :func:`globals` and :func:`locals` functions
407 returns the current global and local dictionary, respectively, which may be
408 useful to pass around for use by :func:`eval` or :func:`exec`.
409
Georg Brandl05bfcc52010-07-11 09:42:10 +0000410 See :func:`ast.literal_eval` for a function that can safely evaluate strings
411 with expressions containing only literals.
412
Georg Brandl116aa622007-08-15 14:28:22 +0000413
414.. function:: exec(object[, globals[, locals]])
415
Benjamin Petersond3013ff2008-11-11 21:43:42 +0000416 This function supports dynamic execution of Python code. *object* must be
417 either a string or a code object. If it is a string, the string is parsed as
418 a suite of Python statements which is then executed (unless a syntax error
Georg Brandl47f27a32009-03-31 16:57:13 +0000419 occurs). [#]_ If it is a code object, it is simply executed. In all cases,
420 the code that's executed is expected to be valid as file input (see the
421 section "File input" in the Reference Manual). Be aware that the
422 :keyword:`return` and :keyword:`yield` statements may not be used outside of
423 function definitions even within the context of code passed to the
424 :func:`exec` function. The return value is ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000425
426 In all cases, if the optional parts are omitted, the code is executed in the
427 current scope. If only *globals* is provided, it must be a dictionary, which
428 will be used for both the global and the local variables. If *globals* and
429 *locals* are given, they are used for the global and local variables,
Terry Jan Reedy83efd6c2012-07-08 17:36:14 -0400430 respectively. If provided, *locals* can be any mapping object. Remember
431 that at module level, globals and locals are the same dictionary. If exec
432 gets two separate objects as *globals* and *locals*, the code will be
433 executed as if it were embedded in a class definition.
Georg Brandl116aa622007-08-15 14:28:22 +0000434
435 If the *globals* dictionary does not contain a value for the key
436 ``__builtins__``, a reference to the dictionary of the built-in module
Georg Brandl1a3284e2007-12-02 09:40:06 +0000437 :mod:`builtins` is inserted under that key. That way you can control what
Georg Brandl116aa622007-08-15 14:28:22 +0000438 builtins are available to the executed code by inserting your own
439 ``__builtins__`` dictionary into *globals* before passing it to :func:`exec`.
440
441 .. note::
442
443 The built-in functions :func:`globals` and :func:`locals` return the current
444 global and local dictionary, respectively, which may be useful to pass around
445 for use as the second and third argument to :func:`exec`.
446
Georg Brandle720c0a2009-04-27 16:20:50 +0000447 .. note::
Georg Brandl116aa622007-08-15 14:28:22 +0000448
449 The default *locals* act as described for function :func:`locals` below:
Georg Brandlf6945182008-02-01 11:56:49 +0000450 modifications to the default *locals* dictionary should not be attempted.
451 Pass an explicit *locals* dictionary if you need to see effects of the
452 code on *locals* after function :func:`exec` returns.
Georg Brandl116aa622007-08-15 14:28:22 +0000453
454
455.. function:: filter(function, iterable)
456
Georg Brandl952aea22007-09-04 17:50:40 +0000457 Construct an iterator from those elements of *iterable* for which *function*
458 returns true. *iterable* may be either a sequence, a container which
Georg Brandl9afde1c2007-11-01 20:32:30 +0000459 supports iteration, or an iterator. If *function* is ``None``, the identity
460 function is assumed, that is, all elements of *iterable* that are false are
461 removed.
Georg Brandl116aa622007-08-15 14:28:22 +0000462
Georg Brandl952aea22007-09-04 17:50:40 +0000463 Note that ``filter(function, iterable)`` is equivalent to the generator
464 expression ``(item for item in iterable if function(item))`` if function is
465 not ``None`` and ``(item for item in iterable if item)`` if function is
466 ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000467
Raymond Hettingercdf8ba32009-02-19 04:45:07 +0000468 See :func:`itertools.filterfalse` for the complementary function that returns
469 elements of *iterable* for which *function* returns false.
470
Georg Brandl116aa622007-08-15 14:28:22 +0000471
472.. function:: float([x])
473
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000474 .. index::
475 single: NaN
476 single: Infinity
Georg Brandl116aa622007-08-15 14:28:22 +0000477
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000478 Convert a string or a number to floating point.
Georg Brandl116aa622007-08-15 14:28:22 +0000479
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000480 If the argument is a string, it should contain a decimal number, optionally
481 preceded by a sign, and optionally embedded in whitespace. The optional
482 sign may be ``'+'`` or ``'-'``; a ``'+'`` sign has no effect on the value
483 produced. The argument may also be a string representing a NaN
484 (not-a-number), or a positive or negative infinity. More precisely, the
485 input must conform to the following grammar after leading and trailing
486 whitespace characters are removed:
Georg Brandl116aa622007-08-15 14:28:22 +0000487
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000488 .. productionlist::
489 sign: "+" | "-"
490 infinity: "Infinity" | "inf"
491 nan: "nan"
Georg Brandl46402372010-12-04 19:06:18 +0000492 numeric_value: `floatnumber` | `infinity` | `nan`
493 numeric_string: [`sign`] `numeric_value`
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000494
495 Here ``floatnumber`` is the form of a Python floating-point literal,
496 described in :ref:`floating`. Case is not significant, so, for example,
497 "inf", "Inf", "INFINITY" and "iNfINity" are all acceptable spellings for
498 positive infinity.
499
500 Otherwise, if the argument is an integer or a floating point number, a
501 floating point number with the same value (within Python's floating point
502 precision) is returned. If the argument is outside the range of a Python
503 float, an :exc:`OverflowError` will be raised.
504
505 For a general Python object ``x``, ``float(x)`` delegates to
506 ``x.__float__()``.
507
508 If no argument is given, ``0.0`` is returned.
509
510 Examples::
511
512 >>> float('+1.23')
513 1.23
514 >>> float(' -12345\n')
515 -12345.0
516 >>> float('1e-003')
517 0.001
518 >>> float('+1E6')
519 1000000.0
520 >>> float('-Infinity')
521 -inf
Georg Brandl116aa622007-08-15 14:28:22 +0000522
523 The float type is described in :ref:`typesnumeric`.
524
Chris Jerdonekbb4e9412012-11-28 01:38:40 -0800525 .. index::
526 single: __format__
527 single: string; format() (built-in function)
528
Éric Araujo9edd9f02011-09-01 23:08:55 +0200529
Georg Brandl4b491312007-08-31 09:22:56 +0000530.. function:: format(value[, format_spec])
531
Georg Brandl5579ba92009-02-23 10:24:05 +0000532 Convert a *value* to a "formatted" representation, as controlled by
533 *format_spec*. The interpretation of *format_spec* will depend on the type
534 of the *value* argument, however there is a standard formatting syntax that
535 is used by most built-in types: :ref:`formatspec`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000536
Raymond Hettinger30439b22011-05-11 10:47:27 -0700537 The default *format_spec* is an empty string which usually gives the same
Chris Jerdonek5fae0e52012-11-20 17:45:51 -0800538 effect as calling :func:`str(value) <str>`.
Georg Brandl4b491312007-08-31 09:22:56 +0000539
Raymond Hettinger30439b22011-05-11 10:47:27 -0700540 A call to ``format(value, format_spec)`` is translated to
541 ``type(value).__format__(format_spec)`` which bypasses the instance
542 dictionary when searching for the value's :meth:`__format__` method. A
543 :exc:`TypeError` exception is raised if the method is not found or if either
544 the *format_spec* or the return value are not strings.
Georg Brandl4b491312007-08-31 09:22:56 +0000545
Andrew Svetlov0794fe02012-12-23 15:12:19 +0200546 .. versionadded:: 3.4
547 ``object().__format__(format_spec)`` raises :exc:`TypeError`
548 if *format_spec* is not empty string.
549
Éric Araujo9edd9f02011-09-01 23:08:55 +0200550
551.. _func-frozenset:
Georg Brandl116aa622007-08-15 14:28:22 +0000552.. function:: frozenset([iterable])
553 :noindex:
554
Chris Jerdonekdf3abec2012-11-09 18:57:32 -0800555 Return a new :class:`frozenset` object, optionally with elements taken from
556 *iterable*. ``frozenset`` is a built-in class. See :class:`frozenset` and
557 :ref:`types-set` for documentation about this class.
Georg Brandl116aa622007-08-15 14:28:22 +0000558
Chris Jerdonekdf3abec2012-11-09 18:57:32 -0800559 For other containers see the built-in :class:`set`, :class:`list`,
560 :class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections`
561 module.
Georg Brandl116aa622007-08-15 14:28:22 +0000562
Georg Brandl116aa622007-08-15 14:28:22 +0000563
564.. function:: getattr(object, name[, default])
565
Georg Brandl8e4ddcf2010-10-16 18:51:05 +0000566 Return the value of the named attribute of *object*. *name* must be a string.
Georg Brandl116aa622007-08-15 14:28:22 +0000567 If the string is the name of one of the object's attributes, the result is the
568 value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
569 ``x.foobar``. If the named attribute does not exist, *default* is returned if
570 provided, otherwise :exc:`AttributeError` is raised.
571
572
573.. function:: globals()
574
575 Return a dictionary representing the current global symbol table. This is always
576 the dictionary of the current module (inside a function or method, this is the
577 module where it is defined, not the module from which it is called).
578
579
580.. function:: hasattr(object, name)
581
Benjamin Peterson17689992010-08-24 03:26:23 +0000582 The arguments are an object and a string. The result is ``True`` if the
583 string is the name of one of the object's attributes, ``False`` if not. (This
584 is implemented by calling ``getattr(object, name)`` and seeing whether it
585 raises an :exc:`AttributeError` or not.)
Georg Brandl116aa622007-08-15 14:28:22 +0000586
587
588.. function:: hash(object)
589
590 Return the hash value of the object (if it has one). Hash values are integers.
591 They are used to quickly compare dictionary keys during a dictionary lookup.
592 Numeric values that compare equal have the same hash value (even if they are of
593 different types, as is the case for 1 and 1.0).
594
595
596.. function:: help([object])
597
598 Invoke the built-in help system. (This function is intended for interactive
599 use.) If no argument is given, the interactive help system starts on the
600 interpreter console. If the argument is a string, then the string is looked up
601 as the name of a module, function, class, method, keyword, or documentation
602 topic, and a help page is printed on the console. If the argument is any other
603 kind of object, a help page on the object is generated.
604
Christian Heimes9bd667a2008-01-20 15:14:11 +0000605 This function is added to the built-in namespace by the :mod:`site` module.
606
Georg Brandl116aa622007-08-15 14:28:22 +0000607
608.. function:: hex(x)
609
610 Convert an integer number to a hexadecimal string. The result is a valid Python
611 expression. If *x* is not a Python :class:`int` object, it has to define an
612 :meth:`__index__` method that returns an integer.
613
Mark Dickinson36cea392009-10-03 10:18:40 +0000614 .. note::
615
616 To obtain a hexadecimal string representation for a float, use the
617 :meth:`float.hex` method.
618
Georg Brandl116aa622007-08-15 14:28:22 +0000619
620.. function:: id(object)
621
Georg Brandlba956ae2007-11-29 17:24:34 +0000622 Return the "identity" of an object. This is an integer which
Georg Brandl116aa622007-08-15 14:28:22 +0000623 is guaranteed to be unique and constant for this object during its lifetime.
Georg Brandl495f7b52009-10-27 15:28:25 +0000624 Two objects with non-overlapping lifetimes may have the same :func:`id`
625 value.
626
Éric Araujof33de712011-05-27 04:42:47 +0200627 .. impl-detail:: This is the address of the object in memory.
Georg Brandl116aa622007-08-15 14:28:22 +0000628
629
Georg Brandlc0902982007-09-12 21:29:27 +0000630.. function:: input([prompt])
631
632 If the *prompt* argument is present, it is written to standard output without
633 a trailing newline. The function then reads a line from input, converts it
634 to a string (stripping a trailing newline), and returns that. When EOF is
635 read, :exc:`EOFError` is raised. Example::
636
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300637 >>> s = input('--> ') # doctest: +SKIP
Georg Brandlc0902982007-09-12 21:29:27 +0000638 --> Monty Python's Flying Circus
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300639 >>> s # doctest: +SKIP
Georg Brandlc0902982007-09-12 21:29:27 +0000640 "Monty Python's Flying Circus"
641
Georg Brandl7b469422007-09-12 21:32:27 +0000642 If the :mod:`readline` module was loaded, then :func:`input` will use it
Georg Brandlc0902982007-09-12 21:29:27 +0000643 to provide elaborate line editing and history features.
644
645
Chris Jerdonek57491e02012-09-28 00:10:44 -0700646.. function:: int(x=0)
647 int(x, base=10)
Georg Brandl116aa622007-08-15 14:28:22 +0000648
Chris Jerdonek57491e02012-09-28 00:10:44 -0700649 Convert a number or string *x* to an integer, or return ``0`` if no
650 arguments are given. If *x* is a number, return :meth:`x.__int__()
651 <object.__int__>`. For floating point numbers, this truncates towards zero.
652
653 If *x* is not a number or if *base* is given, then *x* must be a string,
654 :class:`bytes`, or :class:`bytearray` instance representing an :ref:`integer
655 literal <integers>` in radix *base*. Optionally, the literal can be
656 preceded by ``+`` or ``-`` (with no space in between) and surrounded by
657 whitespace. A base-n literal consists of the digits 0 to n-1, with ``a``
658 to ``z`` (or ``A`` to ``Z``) having
Georg Brandl1b5ab452009-08-13 07:56:35 +0000659 values 10 to 35. The default *base* is 10. The allowed values are 0 and 2-36.
Georg Brandl225d3c82008-04-09 18:45:14 +0000660 Base-2, -8, and -16 literals can be optionally prefixed with ``0b``/``0B``,
Georg Brandl1b5ab452009-08-13 07:56:35 +0000661 ``0o``/``0O``, or ``0x``/``0X``, as with integer literals in code. Base 0
662 means to interpret exactly as a code literal, so that the actual base is 2,
Georg Brandl225d3c82008-04-09 18:45:14 +0000663 8, 10, or 16, and so that ``int('010', 0)`` is not legal, while
664 ``int('010')`` is, as well as ``int('010', 8)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000665
666 The integer type is described in :ref:`typesnumeric`.
667
Mark Dickinson07c71362013-01-27 10:17:52 +0000668 .. versionchanged:: 3.4
669 If *base* is not an instance of :class:`int` and the *base* object has a
670 :meth:`base.__index__ <object.__index__>` method, that method is called
671 to obtain an integer for the base. Previous versions used
672 :meth:`base.__int__ <object.__int__>` instead of :meth:`base.__index__
673 <object.__index__>`.
Georg Brandl116aa622007-08-15 14:28:22 +0000674
675.. function:: isinstance(object, classinfo)
676
Georg Brandl85eb8c12007-08-31 16:33:38 +0000677 Return true if the *object* argument is an instance of the *classinfo*
Éric Araujoe8b7eb02011-08-19 02:17:03 +0200678 argument, or of a (direct, indirect or :term:`virtual <abstract base
679 class>`) subclass thereof. If *object* is not
Georg Brandl85eb8c12007-08-31 16:33:38 +0000680 an object of the given type, the function always returns false. If
681 *classinfo* is not a class (type object), it may be a tuple of type objects,
682 or may recursively contain other such tuples (other sequence types are not
683 accepted). If *classinfo* is not a type or tuple of types and such tuples,
684 a :exc:`TypeError` exception is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000685
Georg Brandl116aa622007-08-15 14:28:22 +0000686
687.. function:: issubclass(class, classinfo)
688
Éric Araujoe8b7eb02011-08-19 02:17:03 +0200689 Return true if *class* is a subclass (direct, indirect or :term:`virtual
690 <abstract base class>`) of *classinfo*. A
Georg Brandl116aa622007-08-15 14:28:22 +0000691 class is considered a subclass of itself. *classinfo* may be a tuple of class
692 objects, in which case every entry in *classinfo* will be checked. In any other
693 case, a :exc:`TypeError` exception is raised.
694
Georg Brandl116aa622007-08-15 14:28:22 +0000695
Georg Brandl036490d2009-05-17 13:00:36 +0000696.. function:: iter(object[, sentinel])
Georg Brandl116aa622007-08-15 14:28:22 +0000697
Georg Brandl036490d2009-05-17 13:00:36 +0000698 Return an :term:`iterator` object. The first argument is interpreted very
699 differently depending on the presence of the second argument. Without a
700 second argument, *object* must be a collection object which supports the
701 iteration protocol (the :meth:`__iter__` method), or it must support the
702 sequence protocol (the :meth:`__getitem__` method with integer arguments
703 starting at ``0``). If it does not support either of those protocols,
704 :exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
705 then *object* must be a callable object. The iterator created in this case
Ezio Melotti7fa82222012-10-12 13:42:08 +0300706 will call *object* with no arguments for each call to its
707 :meth:`~iterator.__next__` method; if the value returned is equal to
708 *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will
709 be returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000710
Chris Jerdonek006d9072012-10-12 20:28:26 -0700711 See also :ref:`typeiter`.
712
Benjamin Petersonf07d0022009-03-21 17:31:58 +0000713 One useful application of the second form of :func:`iter` is to read lines of
714 a file until a certain line is reached. The following example reads a file
Raymond Hettinger90289282011-06-01 16:17:23 -0700715 until the :meth:`readline` method returns an empty string::
Benjamin Petersonf07d0022009-03-21 17:31:58 +0000716
Raymond Hettinger90289282011-06-01 16:17:23 -0700717 with open('mydata.txt') as fp:
718 for line in iter(fp.readline, ''):
Benjamin Petersonf07d0022009-03-21 17:31:58 +0000719 process_line(line)
720
Georg Brandl116aa622007-08-15 14:28:22 +0000721
722.. function:: len(s)
723
724 Return the length (the number of items) of an object. The argument may be a
725 sequence (string, tuple or list) or a mapping (dictionary).
726
727
Nick Coghlan83c0ae52012-08-21 17:42:52 +1000728.. _func-list:
Georg Brandl116aa622007-08-15 14:28:22 +0000729.. function:: list([iterable])
Nick Coghlan83c0ae52012-08-21 17:42:52 +1000730 :noindex:
Georg Brandl116aa622007-08-15 14:28:22 +0000731
Nick Coghlan83c0ae52012-08-21 17:42:52 +1000732 Rather than being a function, :class:`list` is actually a mutable
Chris Jerdonek006d9072012-10-12 20:28:26 -0700733 sequence type, as documented in :ref:`typesseq-list` and :ref:`typesseq`.
Georg Brandl116aa622007-08-15 14:28:22 +0000734
Georg Brandl036490d2009-05-17 13:00:36 +0000735
Georg Brandl116aa622007-08-15 14:28:22 +0000736.. function:: locals()
737
738 Update and return a dictionary representing the current local symbol table.
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000739 Free variables are returned by :func:`locals` when it is called in function
740 blocks, but not in class blocks.
Georg Brandl116aa622007-08-15 14:28:22 +0000741
Georg Brandle720c0a2009-04-27 16:20:50 +0000742 .. note::
Georg Brandl036490d2009-05-17 13:00:36 +0000743 The contents of this dictionary should not be modified; changes may not
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000744 affect the values of local and free variables used by the interpreter.
Georg Brandl116aa622007-08-15 14:28:22 +0000745
746.. function:: map(function, iterable, ...)
747
Georg Brandl952aea22007-09-04 17:50:40 +0000748 Return an iterator that applies *function* to every item of *iterable*,
749 yielding the results. If additional *iterable* arguments are passed,
750 *function* must take that many arguments and is applied to the items from all
Georg Brandlde2b00e2008-05-05 21:04:12 +0000751 iterables in parallel. With multiple iterables, the iterator stops when the
Raymond Hettingercdf8ba32009-02-19 04:45:07 +0000752 shortest iterable is exhausted. For cases where the function inputs are
753 already arranged into argument tuples, see :func:`itertools.starmap`\.
Georg Brandlde2b00e2008-05-05 21:04:12 +0000754
Georg Brandl116aa622007-08-15 14:28:22 +0000755
Ezio Melottie0add762012-09-14 06:32:35 +0300756.. function:: max(iterable, *[, key])
757 max(arg1, arg2, *args[, key])
Georg Brandl116aa622007-08-15 14:28:22 +0000758
Ezio Melottie0add762012-09-14 06:32:35 +0300759 Return the largest item in an iterable or the largest of two or more
760 arguments.
761
762 If one positional argument is provided, *iterable* must be a non-empty
763 iterable (such as a non-empty string, tuple or list). The largest item
764 in the iterable is returned. If two or more positional arguments are
765 provided, the largest of the positional arguments is returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000766
Georg Brandl55ac8f02007-09-01 13:51:09 +0000767 The optional keyword-only *key* argument specifies a one-argument ordering
768 function like that used for :meth:`list.sort`.
Georg Brandl116aa622007-08-15 14:28:22 +0000769
Georg Brandl682d7e02010-10-06 10:26:05 +0000770 If multiple items are maximal, the function returns the first one
771 encountered. This is consistent with other sort-stability preserving tools
772 such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and
Raymond Hettinger476a31e2010-09-14 23:13:42 +0000773 ``heapq.nlargest(1, iterable, key=keyfunc)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000774
Éric Araujo9edd9f02011-09-01 23:08:55 +0200775
776.. _func-memoryview:
Georg Brandl85eb8c12007-08-31 16:33:38 +0000777.. function:: memoryview(obj)
Benjamin Peterson6dfcb022008-09-10 21:02:02 +0000778 :noindex:
Georg Brandl85eb8c12007-08-31 16:33:38 +0000779
Benjamin Peterson1b25b922008-09-09 22:15:27 +0000780 Return a "memory view" object created from the given argument. See
781 :ref:`typememoryview` for more information.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000782
783
Ezio Melottie0add762012-09-14 06:32:35 +0300784.. function:: min(iterable, *[, key])
785 min(arg1, arg2, *args[, key])
Georg Brandl116aa622007-08-15 14:28:22 +0000786
Ezio Melottie0add762012-09-14 06:32:35 +0300787 Return the smallest item in an iterable or the smallest of two or more
788 arguments.
789
790 If one positional argument is provided, *iterable* must be a non-empty
791 iterable (such as a non-empty string, tuple or list). The smallest item
792 in the iterable is returned. If two or more positional arguments are
793 provided, the smallest of the positional arguments is returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000794
Georg Brandl55ac8f02007-09-01 13:51:09 +0000795 The optional keyword-only *key* argument specifies a one-argument ordering
796 function like that used for :meth:`list.sort`.
Georg Brandl116aa622007-08-15 14:28:22 +0000797
Georg Brandl682d7e02010-10-06 10:26:05 +0000798 If multiple items are minimal, the function returns the first one
799 encountered. This is consistent with other sort-stability preserving tools
800 such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1,
801 iterable, key=keyfunc)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000802
803.. function:: next(iterator[, default])
804
Ezio Melotti7fa82222012-10-12 13:42:08 +0300805 Retrieve the next item from the *iterator* by calling its
806 :meth:`~iterator.__next__` method. If *default* is given, it is returned
807 if the iterator is exhausted, otherwise :exc:`StopIteration` is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000808
809
810.. function:: object()
811
Georg Brandl85eb8c12007-08-31 16:33:38 +0000812 Return a new featureless object. :class:`object` is a base for all classes.
Georg Brandl55ac8f02007-09-01 13:51:09 +0000813 It has the methods that are common to all instances of Python classes. This
814 function does not accept any arguments.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000815
816 .. note::
817
818 :class:`object` does *not* have a :attr:`__dict__`, so you can't assign
819 arbitrary attributes to an instance of the :class:`object` class.
Georg Brandl116aa622007-08-15 14:28:22 +0000820
Georg Brandl116aa622007-08-15 14:28:22 +0000821
822.. function:: oct(x)
823
824 Convert an integer number to an octal string. The result is a valid Python
825 expression. If *x* is not a Python :class:`int` object, it has to define an
826 :meth:`__index__` method that returns an integer.
827
Georg Brandl116aa622007-08-15 14:28:22 +0000828
R David Murray9f0c9402012-08-17 20:33:54 -0400829 .. index::
830 single: file object; open() built-in function
831
Ross Lagerwall59142db2011-10-31 20:34:46 +0200832.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000833
R David Murray9f0c9402012-08-17 20:33:54 -0400834 Open *file* and return a corresponding :term:`file object`. If the file
R David Murray8eac5752012-08-17 20:38:19 -0400835 cannot be opened, an :exc:`OSError` is raised.
Georg Brandl48310cd2009-01-03 21:18:54 +0000836
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000837 *file* is either a string or bytes object giving the pathname (absolute or
838 relative to the current working directory) of the file to be opened or
Georg Brandl76e55382008-10-08 16:34:57 +0000839 an integer file descriptor of the file to be wrapped. (If a file descriptor
840 is given, it is closed when the returned I/O object is closed, unless
841 *closefd* is set to ``False``.)
Georg Brandl116aa622007-08-15 14:28:22 +0000842
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000843 *mode* is an optional string that specifies the mode in which the file is
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000844 opened. It defaults to ``'r'`` which means open for reading in text mode.
845 Other common values are ``'w'`` for writing (truncating the file if it
Charles-François Natalib93f9fa2012-05-20 11:41:53 +0200846 already exists), ``'x'`` for exclusive creation and ``'a'`` for appending
847 (which on *some* Unix systems, means that *all* writes append to the end of
848 the file regardless of the current seek position). In text mode, if
Victor Stinnerf86a5e82012-06-05 13:43:22 +0200849 *encoding* is not specified the encoding used is platform dependent:
850 ``locale.getpreferredencoding(False)`` is called to get the current locale
851 encoding. (For reading and writing raw bytes use binary mode and leave
852 *encoding* unspecified.) The available modes are:
Georg Brandl116aa622007-08-15 14:28:22 +0000853
Benjamin Petersondd219122008-04-11 21:17:32 +0000854 ========= ===============================================================
855 Character Meaning
Georg Brandl44ea77b2013-03-28 13:28:44 +0100856 ========= ===============================================================
Benjamin Petersondd219122008-04-11 21:17:32 +0000857 ``'r'`` open for reading (default)
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000858 ``'w'`` open for writing, truncating the file first
Charles-François Natalib93f9fa2012-05-20 11:41:53 +0200859 ``'x'`` open for exclusive creation, failing if the file already exists
Benjamin Petersondd219122008-04-11 21:17:32 +0000860 ``'a'`` open for writing, appending to the end of the file if it exists
Georg Brandl7b6ca4a2009-04-27 06:13:55 +0000861 ``'b'`` binary mode
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000862 ``'t'`` text mode (default)
863 ``'+'`` open a disk file for updating (reading and writing)
R David Murray1b00f252012-08-15 10:43:58 -0400864 ``'U'`` universal newlines mode (for backwards compatibility; should
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000865 not be used in new code)
Benjamin Petersondd219122008-04-11 21:17:32 +0000866 ========= ===============================================================
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000867
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000868 The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``).
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000869 For binary read-write access, the mode ``'w+b'`` opens and truncates the file
870 to 0 bytes. ``'r+b'`` opens the file without truncation.
Skip Montanaro1c639602007-09-23 19:49:54 +0000871
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000872 As mentioned in the :ref:`io-overview`, Python distinguishes between binary
873 and text I/O. Files opened in binary mode (including ``'b'`` in the *mode*
874 argument) return contents as :class:`bytes` objects without any decoding. In
875 text mode (the default, or when ``'t'`` is included in the *mode* argument),
876 the contents of the file are returned as :class:`str`, the bytes having been
877 first decoded using a platform-dependent encoding or using the specified
878 *encoding* if given.
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000879
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000880 .. note::
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000881
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000882 Python doesn't depend on the underlying operating system's notion of text
Ezio Melottie130a522011-10-19 10:58:56 +0300883 files; all the processing is done by Python itself, and is therefore
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000884 platform-independent.
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000885
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000886 *buffering* is an optional integer used to set the buffering policy. Pass 0
887 to switch buffering off (only allowed in binary mode), 1 to select line
888 buffering (only usable in text mode), and an integer > 1 to indicate the size
Terry Jan Reedydff04f42013-03-16 15:56:27 -0400889 in bytes of a fixed-size chunk buffer. When no *buffering* argument is
890 given, the default buffering policy works as follows:
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000891
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000892 * Binary files are buffered in fixed-size chunks; the size of the buffer is
893 chosen using a heuristic trying to determine the underlying device's "block
894 size" and falling back on :attr:`io.DEFAULT_BUFFER_SIZE`. On many systems,
895 the buffer will typically be 4096 or 8192 bytes long.
896
897 * "Interactive" text files (files for which :meth:`isatty` returns True) use
898 line buffering. Other text files use the policy described above for binary
899 files.
Georg Brandl48310cd2009-01-03 21:18:54 +0000900
Benjamin Petersondd219122008-04-11 21:17:32 +0000901 *encoding* is the name of the encoding used to decode or encode the file.
902 This should only be used in text mode. The default encoding is platform
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000903 dependent (whatever :func:`locale.getpreferredencoding` returns), but any
904 encoding supported by Python can be used. See the :mod:`codecs` module for
905 the list of supported encodings.
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000906
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000907 *errors* is an optional string that specifies how encoding and decoding
Andrew Kuchlingc7b6c502013-06-16 12:58:48 -0400908 errors are to be handled--this cannot be used in binary mode.
909 A variety of standard error handlers are available, though any
910 error handling name that has been registered with
911 :func:`codecs.register_error` is also valid. The standard names
912 are:
913
914 * ``'strict'`` to raise a :exc:`ValueError` exception if there is
915 an encoding error. The default value of ``None`` has the same
916 effect.
917
918 * ``'ignore'`` ignores errors. Note that ignoring encoding errors
919 can lead to data loss.
920
921 * ``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted
922 where there is malformed data.
923
924 * ``'surrogateescape'`` will represent any incorrect bytes as code
925 points in the Unicode Private Use Area ranging from U+DC80 to
926 U+DCFF. These private code points will then be turned back into
927 the same bytes when the ``surrogateescape`` error handler is used
928 when writing data. This is useful for processing files in an
929 unknown encoding.
930
931 * ``'xmlcharrefreplace'`` is only supported when writing to a file.
932 Characters not supported by the encoding are replaced with the
933 appropriate XML character reference ``&#nnn;``.
934
935 * ``'backslashreplace'`` (also only supported when writing)
936 replaces unsupported characters with Python's backslashed escape
937 sequences.
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000938
R David Murray1b00f252012-08-15 10:43:58 -0400939 .. index::
940 single: universal newlines; open() built-in function
941
942 *newline* controls how :term:`universal newlines` mode works (it only
R David Murrayee0a9452012-08-15 11:05:36 -0400943 applies to text mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and
944 ``'\r\n'``. It works as follows:
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000945
Georg Brandl296d1be2012-08-14 09:39:07 +0200946 * When reading input from the stream, if *newline* is ``None``, universal
947 newlines mode is enabled. Lines in the input can end in ``'\n'``,
948 ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` before
R David Murray1b00f252012-08-15 10:43:58 -0400949 being returned to the caller. If it is ``''``, universal newlines mode is
Georg Brandl296d1be2012-08-14 09:39:07 +0200950 enabled, but line endings are returned to the caller untranslated. If it
951 has any of the other legal values, input lines are only terminated by the
952 given string, and the line ending is returned to the caller untranslated.
Benjamin Petersondd219122008-04-11 21:17:32 +0000953
Georg Brandl296d1be2012-08-14 09:39:07 +0200954 * When writing output to the stream, if *newline* is ``None``, any ``'\n'``
955 characters written are translated to the system default line separator,
956 :data:`os.linesep`. If *newline* is ``''`` or ``'\n'``, no translation
957 takes place. If *newline* is any of the other legal values, any ``'\n'``
958 characters written are translated to the given string.
Benjamin Petersondd219122008-04-11 21:17:32 +0000959
Benjamin Peterson8cad9c72009-03-23 02:38:01 +0000960 If *closefd* is ``False`` and a file descriptor rather than a filename was
961 given, the underlying file descriptor will be kept open when the file is
962 closed. If a filename is given *closefd* has no effect and must be ``True``
963 (the default).
964
Ross Lagerwall59142db2011-10-31 20:34:46 +0200965 A custom opener can be used by passing a callable as *opener*. The underlying
966 file descriptor for the file object is then obtained by calling *opener* with
967 (*file*, *flags*). *opener* must return an open file descriptor (passing
968 :mod:`os.open` as *opener* results in functionality similar to passing
969 ``None``).
970
Éric Araujo5bd92702012-11-22 00:13:49 -0500971 The following example uses the :ref:`dir_fd <dir_fd>` parameter of the
Éric Araujo8f423c92012-11-03 17:06:52 -0400972 :func:`os.open` function to open a file relative to a given directory::
973
974 >>> import os
Éric Araujo5bd92702012-11-22 00:13:49 -0500975 >>> dir_fd = os.open('somedir', os.O_RDONLY)
976 >>> def opener(path, flags):
977 ... return os.open(path, flags, dir_fd=dir_fd)
Éric Araujo8f423c92012-11-03 17:06:52 -0400978 ...
Éric Araujo8f423c92012-11-03 17:06:52 -0400979 >>> with open('spamspam.txt', 'w', opener=opener) as f:
980 ... print('This will be written to somedir/spamspam.txt', file=f)
981 ...
Éric Araujo309b0432012-11-03 17:39:45 -0400982 >>> os.close(dir_fd) # don't leak a file descriptor
Éric Araujo8f423c92012-11-03 17:06:52 -0400983
Ross Lagerwall59142db2011-10-31 20:34:46 +0200984 .. versionchanged:: 3.3
985 The *opener* parameter was added.
Charles-François Natalib93f9fa2012-05-20 11:41:53 +0200986 The ``'x'`` mode was added.
Ross Lagerwall59142db2011-10-31 20:34:46 +0200987
R David Murray9f0c9402012-08-17 20:33:54 -0400988 The type of :term:`file object` returned by the :func:`open` function
R David Murray433ef3b2012-08-17 20:39:21 -0400989 depends on the mode. When :func:`open` is used to open a file in a text
990 mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000991 :class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used
992 to open a file in a binary mode with buffering, the returned class is a
993 subclass of :class:`io.BufferedIOBase`. The exact class varies: in read
994 binary mode, it returns a :class:`io.BufferedReader`; in write binary and
995 append binary modes, it returns a :class:`io.BufferedWriter`, and in
996 read/write mode, it returns a :class:`io.BufferedRandom`. When buffering is
997 disabled, the raw stream, a subclass of :class:`io.RawIOBase`,
998 :class:`io.FileIO`, is returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000999
1000 .. index::
1001 single: line-buffered I/O
1002 single: unbuffered I/O
1003 single: buffer size, I/O
1004 single: I/O control; buffering
Skip Montanaro4d8c1932007-09-23 21:13:45 +00001005 single: binary mode
1006 single: text mode
1007 module: sys
Georg Brandl116aa622007-08-15 14:28:22 +00001008
Benjamin Petersondd219122008-04-11 21:17:32 +00001009 See also the file handling modules, such as, :mod:`fileinput`, :mod:`io`
Benjamin Peterson8cad9c72009-03-23 02:38:01 +00001010 (where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:`tempfile`,
1011 and :mod:`shutil`.
Georg Brandl116aa622007-08-15 14:28:22 +00001012
Antoine Pitrou62ab10a02011-10-12 20:10:51 +02001013 .. versionchanged:: 3.3
1014 :exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`.
Charles-François Natalib93f9fa2012-05-20 11:41:53 +02001015 :exc:`FileExistsError` is now raised if the file opened in exclusive
1016 creation mode (``'x'``) already exists.
Antoine Pitrou62ab10a02011-10-12 20:10:51 +02001017
Georg Brandlf6945182008-02-01 11:56:49 +00001018
1019.. XXX works for bytes too, but should it?
Georg Brandl116aa622007-08-15 14:28:22 +00001020.. function:: ord(c)
1021
Ezio Melottic99c8582011-10-25 09:32:34 +03001022 Given a string representing one Unicode character, return an integer
Alexander Belopolsky5d4dd3e2010-11-18 18:50:13 +00001023 representing the Unicode code
1024 point of that character. For example, ``ord('a')`` returns the integer ``97``
Georg Brandlf6945182008-02-01 11:56:49 +00001025 and ``ord('\u2020')`` returns ``8224``. This is the inverse of :func:`chr`.
1026
Georg Brandl116aa622007-08-15 14:28:22 +00001027
1028.. function:: pow(x, y[, z])
1029
1030 Return *x* to the power *y*; if *z* is present, return *x* to the power *y*,
1031 modulo *z* (computed more efficiently than ``pow(x, y) % z``). The two-argument
1032 form ``pow(x, y)`` is equivalent to using the power operator: ``x**y``.
1033
Georg Brandle06de8b2008-05-05 21:42:51 +00001034 The arguments must have numeric types. With mixed operand types, the
1035 coercion rules for binary arithmetic operators apply. For :class:`int`
1036 operands, the result has the same type as the operands (after coercion)
1037 unless the second argument is negative; in that case, all arguments are
1038 converted to float and a float result is delivered. For example, ``10**2``
1039 returns ``100``, but ``10**-2`` returns ``0.01``. If the second argument is
1040 negative, the third argument must be omitted. If *z* is present, *x* and *y*
1041 must be of integer types, and *y* must be non-negative.
Georg Brandl116aa622007-08-15 14:28:22 +00001042
1043
Ezio Melotti8429b672012-09-14 06:35:09 +03001044.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout, flush=False)
Georg Brandlf6945182008-02-01 11:56:49 +00001045
Ezio Melottie0add762012-09-14 06:32:35 +03001046 Print *objects* to the stream *file*, separated by *sep* and followed by
Georg Brandlf6945182008-02-01 11:56:49 +00001047 *end*. *sep*, *end* and *file*, if present, must be given as keyword
1048 arguments.
1049
1050 All non-keyword arguments are converted to strings like :func:`str` does and
1051 written to the stream, separated by *sep* and followed by *end*. Both *sep*
1052 and *end* must be strings; they can also be ``None``, which means to use the
Ezio Melottie0add762012-09-14 06:32:35 +03001053 default values. If no *objects* are given, :func:`print` will just write
Georg Brandlf6945182008-02-01 11:56:49 +00001054 *end*.
1055
1056 The *file* argument must be an object with a ``write(string)`` method; if it
Georg Brandlbc3b6822012-01-13 19:41:25 +01001057 is not present or ``None``, :data:`sys.stdout` will be used. Whether output
1058 is buffered is usually determined by *file*, but if the *flush* keyword
1059 argument is true, the stream is forcibly flushed.
1060
1061 .. versionchanged:: 3.3
1062 Added the *flush* keyword argument.
Georg Brandlf6945182008-02-01 11:56:49 +00001063
1064
Georg Brandl036490d2009-05-17 13:00:36 +00001065.. function:: property(fget=None, fset=None, fdel=None, doc=None)
Georg Brandl116aa622007-08-15 14:28:22 +00001066
Georg Brandl85eb8c12007-08-31 16:33:38 +00001067 Return a property attribute.
Georg Brandl116aa622007-08-15 14:28:22 +00001068
1069 *fget* is a function for getting an attribute value, likewise *fset* is a
1070 function for setting, and *fdel* a function for del'ing, an attribute. Typical
Georg Brandl7528b9b2010-08-02 19:23:34 +00001071 use is to define a managed attribute ``x``::
Georg Brandl116aa622007-08-15 14:28:22 +00001072
Éric Araujo28053fb2010-11-22 03:09:19 +00001073 class C:
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +00001074 def __init__(self):
1075 self._x = None
1076
1077 def getx(self):
1078 return self._x
1079 def setx(self, value):
1080 self._x = value
1081 def delx(self):
1082 del self._x
Georg Brandl116aa622007-08-15 14:28:22 +00001083 x = property(getx, setx, delx, "I'm the 'x' property.")
1084
Georg Brandl7528b9b2010-08-02 19:23:34 +00001085 If then *c* is an instance of *C*, ``c.x`` will invoke the getter,
1086 ``c.x = value`` will invoke the setter and ``del c.x`` the deleter.
1087
Georg Brandl116aa622007-08-15 14:28:22 +00001088 If given, *doc* will be the docstring of the property attribute. Otherwise, the
1089 property will copy *fget*'s docstring (if it exists). This makes it possible to
Christian Heimesd8654cf2007-12-02 15:22:16 +00001090 create read-only properties easily using :func:`property` as a :term:`decorator`::
Georg Brandl116aa622007-08-15 14:28:22 +00001091
Éric Araujo28053fb2010-11-22 03:09:19 +00001092 class Parrot:
Georg Brandl116aa622007-08-15 14:28:22 +00001093 def __init__(self):
1094 self._voltage = 100000
1095
1096 @property
1097 def voltage(self):
1098 """Get the current voltage."""
1099 return self._voltage
1100
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +00001101 turns the :meth:`voltage` method into a "getter" for a read-only attribute
1102 with the same name.
1103
1104 A property object has :attr:`getter`, :attr:`setter`, and :attr:`deleter`
1105 methods usable as decorators that create a copy of the property with the
1106 corresponding accessor function set to the decorated function. This is
1107 best explained with an example::
1108
Éric Araujo28053fb2010-11-22 03:09:19 +00001109 class C:
Benjamin Peterson206e3072008-10-19 14:07:49 +00001110 def __init__(self):
1111 self._x = None
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +00001112
1113 @property
1114 def x(self):
1115 """I'm the 'x' property."""
1116 return self._x
1117
1118 @x.setter
1119 def x(self, value):
1120 self._x = value
1121
1122 @x.deleter
1123 def x(self):
1124 del self._x
1125
1126 This code is exactly equivalent to the first example. Be sure to give the
1127 additional functions the same name as the original property (``x`` in this
1128 case.)
1129
1130 The returned property also has the attributes ``fget``, ``fset``, and
1131 ``fdel`` corresponding to the constructor arguments.
Georg Brandl116aa622007-08-15 14:28:22 +00001132
Georg Brandl116aa622007-08-15 14:28:22 +00001133
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001134.. _func-range:
Ezio Melottie0add762012-09-14 06:32:35 +03001135.. function:: range(stop)
1136 range(start, stop[, step])
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001137 :noindex:
Georg Brandl116aa622007-08-15 14:28:22 +00001138
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001139 Rather than being a function, :class:`range` is actually an immutable
Chris Jerdonek006d9072012-10-12 20:28:26 -07001140 sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`.
Benjamin Peterson878ce382011-11-05 15:17:52 -04001141
Georg Brandl116aa622007-08-15 14:28:22 +00001142
1143.. function:: repr(object)
1144
Georg Brandl68ee3a52008-03-25 07:21:32 +00001145 Return a string containing a printable representation of an object. For many
1146 types, this function makes an attempt to return a string that would yield an
1147 object with the same value when passed to :func:`eval`, otherwise the
1148 representation is a string enclosed in angle brackets that contains the name
1149 of the type of the object together with additional information often
1150 including the name and address of the object. A class can control what this
1151 function returns for its instances by defining a :meth:`__repr__` method.
Georg Brandl116aa622007-08-15 14:28:22 +00001152
1153
1154.. function:: reversed(seq)
1155
Christian Heimes7f044312008-01-06 17:05:40 +00001156 Return a reverse :term:`iterator`. *seq* must be an object which has
1157 a :meth:`__reversed__` method or supports the sequence protocol (the
1158 :meth:`__len__` method and the :meth:`__getitem__` method with integer
1159 arguments starting at ``0``).
Georg Brandl116aa622007-08-15 14:28:22 +00001160
Georg Brandl116aa622007-08-15 14:28:22 +00001161
Mark Dickinson4e12ad12012-09-20 20:51:14 +01001162.. function:: round(number[, ndigits])
Georg Brandl116aa622007-08-15 14:28:22 +00001163
Mark Dickinson4e12ad12012-09-20 20:51:14 +01001164 Return the floating point value *number* rounded to *ndigits* digits after
1165 the decimal point. If *ndigits* is omitted, it defaults to zero. Delegates
1166 to ``number.__round__(ndigits)``.
Georg Brandl809ddaa2008-07-01 20:39:59 +00001167
1168 For the built-in types supporting :func:`round`, values are rounded to the
Mark Dickinson4e12ad12012-09-20 20:51:14 +01001169 closest multiple of 10 to the power minus *ndigits*; if two multiples are
1170 equally close, rounding is done toward the even choice (so, for example,
1171 both ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is
1172 ``2``). The return value is an integer if called with one argument,
1173 otherwise of the same type as *number*.
Christian Heimes072c0f12008-01-03 23:01:04 +00001174
Mark Dickinsonc4fbcdc2010-07-30 13:13:02 +00001175 .. note::
1176
1177 The behavior of :func:`round` for floats can be surprising: for example,
1178 ``round(2.675, 2)`` gives ``2.67`` instead of the expected ``2.68``.
1179 This is not a bug: it's a result of the fact that most decimal fractions
1180 can't be represented exactly as a float. See :ref:`tut-fp-issues` for
1181 more information.
Georg Brandl116aa622007-08-15 14:28:22 +00001182
Éric Araujo9edd9f02011-09-01 23:08:55 +02001183
1184.. _func-set:
Georg Brandl116aa622007-08-15 14:28:22 +00001185.. function:: set([iterable])
1186 :noindex:
1187
Chris Jerdonekdf3abec2012-11-09 18:57:32 -08001188 Return a new :class:`set` object, optionally with elements taken from
1189 *iterable*. ``set`` is a built-in class. See :class:`set` and
1190 :ref:`types-set` for documentation about this class.
1191
1192 For other containers see the built-in :class:`frozenset`, :class:`list`,
1193 :class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections`
1194 module.
Georg Brandl116aa622007-08-15 14:28:22 +00001195
Georg Brandl116aa622007-08-15 14:28:22 +00001196
1197.. function:: setattr(object, name, value)
1198
1199 This is the counterpart of :func:`getattr`. The arguments are an object, a
1200 string and an arbitrary value. The string may name an existing attribute or a
1201 new attribute. The function assigns the value to the attribute, provided the
1202 object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to
1203 ``x.foobar = 123``.
1204
1205
Ezio Melottie0add762012-09-14 06:32:35 +03001206.. function:: slice(stop)
1207 slice(start, stop[, step])
Georg Brandl116aa622007-08-15 14:28:22 +00001208
1209 .. index:: single: Numerical Python
1210
Christian Heimesd8654cf2007-12-02 15:22:16 +00001211 Return a :term:`slice` object representing the set of indices specified by
Georg Brandl116aa622007-08-15 14:28:22 +00001212 ``range(start, stop, step)``. The *start* and *step* arguments default to
1213 ``None``. Slice objects have read-only data attributes :attr:`start`,
1214 :attr:`stop` and :attr:`step` which merely return the argument values (or their
1215 default). They have no other explicit functionality; however they are used by
1216 Numerical Python and other third party extensions. Slice objects are also
1217 generated when extended indexing syntax is used. For example:
Raymond Hettingercdf8ba32009-02-19 04:45:07 +00001218 ``a[start:stop:step]`` or ``a[start:stop, i]``. See :func:`itertools.islice`
1219 for an alternate version that returns an iterator.
Georg Brandl116aa622007-08-15 14:28:22 +00001220
1221
Georg Brandl036490d2009-05-17 13:00:36 +00001222.. function:: sorted(iterable[, key][, reverse])
Georg Brandl116aa622007-08-15 14:28:22 +00001223
1224 Return a new sorted list from the items in *iterable*.
1225
Raymond Hettinger51b9c242008-02-14 13:52:24 +00001226 Has two optional arguments which must be specified as keyword arguments.
Georg Brandl116aa622007-08-15 14:28:22 +00001227
Georg Brandl116aa622007-08-15 14:28:22 +00001228 *key* specifies a function of one argument that is used to extract a comparison
Georg Brandl1f70cdf2010-03-21 09:04:24 +00001229 key from each list element: ``key=str.lower``. The default value is ``None``
1230 (compare the elements directly).
Georg Brandl116aa622007-08-15 14:28:22 +00001231
1232 *reverse* is a boolean value. If set to ``True``, then the list elements are
1233 sorted as if each comparison were reversed.
1234
Benjamin Peterson7ac98ae2010-08-17 17:52:02 +00001235 Use :func:`functools.cmp_to_key` to convert an old-style *cmp* function to a
1236 *key* function.
Georg Brandl116aa622007-08-15 14:28:22 +00001237
Raymond Hettinger46fca072010-04-02 00:25:45 +00001238 For sorting examples and a brief sorting tutorial, see `Sorting HowTo
1239 <http://wiki.python.org/moin/HowTo/Sorting/>`_\.
1240
Georg Brandl116aa622007-08-15 14:28:22 +00001241.. function:: staticmethod(function)
1242
1243 Return a static method for *function*.
1244
1245 A static method does not receive an implicit first argument. To declare a static
1246 method, use this idiom::
1247
1248 class C:
1249 @staticmethod
1250 def f(arg1, arg2, ...): ...
1251
Christian Heimesd8654cf2007-12-02 15:22:16 +00001252 The ``@staticmethod`` form is a function :term:`decorator` -- see the
1253 description of function definitions in :ref:`function` for details.
Georg Brandl116aa622007-08-15 14:28:22 +00001254
1255 It can be called either on the class (such as ``C.f()``) or on an instance (such
1256 as ``C().f()``). The instance is ignored except for its class.
1257
Raymond Hettinger90289282011-06-01 16:17:23 -07001258 Static methods in Python are similar to those found in Java or C++. Also see
1259 :func:`classmethod` for a variant that is useful for creating alternate class
1260 constructors.
Georg Brandl116aa622007-08-15 14:28:22 +00001261
1262 For more information on static methods, consult the documentation on the
1263 standard type hierarchy in :ref:`types`.
1264
Chris Jerdonek5fae0e52012-11-20 17:45:51 -08001265 .. index::
1266 single: string; str() (built-in function)
1267
Georg Brandl116aa622007-08-15 14:28:22 +00001268
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001269.. _func-str:
Chris Jerdonek83fe2e12012-10-07 14:48:36 -07001270.. function:: str(object='')
Chris Jerdonek5fae0e52012-11-20 17:45:51 -08001271 str(object=b'', encoding='utf-8', errors='strict')
Chris Jerdonekbb4e9412012-11-28 01:38:40 -08001272 :noindex:
Georg Brandl116aa622007-08-15 14:28:22 +00001273
Chris Jerdonekbb4e9412012-11-28 01:38:40 -08001274 Return a :class:`str` version of *object*. See :func:`str` for details.
Georg Brandl48310cd2009-01-03 21:18:54 +00001275
Chris Jerdonekbb4e9412012-11-28 01:38:40 -08001276 ``str`` is the built-in string :term:`class`. For general information
1277 about strings, see :ref:`textseq`.
Georg Brandl116aa622007-08-15 14:28:22 +00001278
1279
1280.. function:: sum(iterable[, start])
1281
1282 Sums *start* and the items of an *iterable* from left to right and returns the
1283 total. *start* defaults to ``0``. The *iterable*'s items are normally numbers,
Raymond Hettingerb3737992010-10-31 21:23:24 +00001284 and the start value is not allowed to be a string.
Georg Brandl116aa622007-08-15 14:28:22 +00001285
Éric Araujo8f9626b2010-11-06 06:30:16 +00001286 For some use cases, there are good alternatives to :func:`sum`.
Raymond Hettingerb3737992010-10-31 21:23:24 +00001287 The preferred, fast way to concatenate a sequence of strings is by calling
1288 ``''.join(sequence)``. To add floating point values with extended precision,
1289 see :func:`math.fsum`\. To concatenate a series of iterables, consider using
1290 :func:`itertools.chain`.
Georg Brandl116aa622007-08-15 14:28:22 +00001291
Mark Summerfield1041f742008-02-26 13:27:00 +00001292.. function:: super([type[, object-or-type]])
Georg Brandl116aa622007-08-15 14:28:22 +00001293
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001294 Return a proxy object that delegates method calls to a parent or sibling
1295 class of *type*. This is useful for accessing inherited methods that have
1296 been overridden in a class. The search order is same as that used by
1297 :func:`getattr` except that the *type* itself is skipped.
1298
Raymond Hettinger0a68b012009-02-25 00:58:47 +00001299 The :attr:`__mro__` attribute of the *type* lists the method resolution
1300 search order used by both :func:`getattr` and :func:`super`. The attribute
1301 is dynamic and can change whenever the inheritance hierarchy is updated.
Benjamin Peterson3e4f0552008-09-02 00:31:15 +00001302
Raymond Hettinger79d04342009-02-25 00:32:51 +00001303 If the second argument is omitted, the super object returned is unbound. If
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001304 the second argument is an object, ``isinstance(obj, type)`` must be true. If
Benjamin Petersond75fcb42009-02-19 04:22:03 +00001305 the second argument is a type, ``issubclass(type2, type)`` must be true (this
1306 is useful for classmethods).
Georg Brandl116aa622007-08-15 14:28:22 +00001307
Raymond Hettinger0a68b012009-02-25 00:58:47 +00001308 There are two typical use cases for *super*. In a class hierarchy with
1309 single inheritance, *super* can be used to refer to parent classes without
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001310 naming them explicitly, thus making the code more maintainable. This use
Raymond Hettinger0a68b012009-02-25 00:58:47 +00001311 closely parallels the use of *super* in other programming languages.
Georg Brandl48310cd2009-01-03 21:18:54 +00001312
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001313 The second use case is to support cooperative multiple inheritance in a
Georg Brandl48310cd2009-01-03 21:18:54 +00001314 dynamic execution environment. This use case is unique to Python and is
1315 not found in statically compiled languages or languages that only support
Raymond Hettingerd1258452009-02-26 00:27:18 +00001316 single inheritance. This makes it possible to implement "diamond diagrams"
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001317 where multiple base classes implement the same method. Good design dictates
1318 that this method have the same calling signature in every case (because the
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001319 order of calls is determined at runtime, because that order adapts
1320 to changes in the class hierarchy, and because that order can include
1321 sibling classes that are unknown prior to runtime).
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001322
1323 For both use cases, a typical superclass call looks like this::
Georg Brandl116aa622007-08-15 14:28:22 +00001324
1325 class C(B):
Mark Summerfield1041f742008-02-26 13:27:00 +00001326 def method(self, arg):
Georg Brandl036490d2009-05-17 13:00:36 +00001327 super().method(arg) # This does the same thing as:
1328 # super(C, self).method(arg)
Georg Brandl116aa622007-08-15 14:28:22 +00001329
1330 Note that :func:`super` is implemented as part of the binding process for
Mark Summerfield1041f742008-02-26 13:27:00 +00001331 explicit dotted attribute lookups such as ``super().__getitem__(name)``.
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001332 It does so by implementing its own :meth:`__getattribute__` method for searching
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001333 classes in a predictable order that supports cooperative multiple inheritance.
Georg Brandl116aa622007-08-15 14:28:22 +00001334 Accordingly, :func:`super` is undefined for implicit lookups using statements or
Raymond Hettinger518d8da2008-12-06 11:44:00 +00001335 operators such as ``super()[name]``.
1336
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001337 Also note that, aside from the zero argument form, :func:`super` is not
1338 limited to use inside methods. The two argument form specifies the
1339 arguments exactly and makes the appropriate references. The zero
1340 argument form only works inside a class definition, as the compiler fills
1341 in the necessary details to correctly retrieve the class being defined,
1342 as well as accessing the current instance for ordinary methods.
Georg Brandl116aa622007-08-15 14:28:22 +00001343
Raymond Hettinger90289282011-06-01 16:17:23 -07001344 For practical suggestions on how to design cooperative classes using
1345 :func:`super`, see `guide to using super()
1346 <http://rhettinger.wordpress.com/2011/05/26/super-considered-super/>`_.
1347
Georg Brandl116aa622007-08-15 14:28:22 +00001348
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001349.. _func-tuple:
Georg Brandl116aa622007-08-15 14:28:22 +00001350.. function:: tuple([iterable])
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001351 :noindex:
Georg Brandl116aa622007-08-15 14:28:22 +00001352
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001353 Rather than being a function, :class:`tuple` is actually an immutable
Chris Jerdonek006d9072012-10-12 20:28:26 -07001354 sequence type, as documented in :ref:`typesseq-tuple` and :ref:`typesseq`.
Georg Brandl116aa622007-08-15 14:28:22 +00001355
1356
1357.. function:: type(object)
Ezio Melotti837cd062012-10-24 23:06:25 +03001358 type(name, bases, dict)
Georg Brandl116aa622007-08-15 14:28:22 +00001359
1360 .. index:: object: type
1361
Ezio Melotti837cd062012-10-24 23:06:25 +03001362
1363 With one argument, return the type of an *object*. The return value is a
1364 type object and generally the same object as returned by ``object.__class__``.
Georg Brandl116aa622007-08-15 14:28:22 +00001365
Georg Brandl85eb8c12007-08-31 16:33:38 +00001366 The :func:`isinstance` built-in function is recommended for testing the type
1367 of an object, because it takes subclasses into account.
1368
Georg Brandl116aa622007-08-15 14:28:22 +00001369
Ezio Melotti837cd062012-10-24 23:06:25 +03001370 With three arguments, return a new type object. This is essentially a
1371 dynamic form of the :keyword:`class` statement. The *name* string is the
1372 class name and becomes the :attr:`__name__` attribute; the *bases* tuple
1373 itemizes the base classes and becomes the :attr:`__bases__` attribute;
1374 and the *dict* dictionary is the namespace containing definitions for class
1375 body and becomes the :attr:`__dict__` attribute. For example, the
1376 following two statements create identical :class:`type` objects:
Georg Brandl116aa622007-08-15 14:28:22 +00001377
Éric Araujo28053fb2010-11-22 03:09:19 +00001378 >>> class X:
Georg Brandl116aa622007-08-15 14:28:22 +00001379 ... a = 1
Georg Brandl48310cd2009-01-03 21:18:54 +00001380 ...
Georg Brandl116aa622007-08-15 14:28:22 +00001381 >>> X = type('X', (object,), dict(a=1))
1382
Chris Jerdonek006d9072012-10-12 20:28:26 -07001383 See also :ref:`bltin-type-objects`.
1384
Georg Brandl116aa622007-08-15 14:28:22 +00001385
1386.. function:: vars([object])
1387
Raymond Hettingerd7100172013-06-02 10:03:05 -07001388 Return the :attr:`__dict__` attribute for a module, class, instance,
1389 or any other object with a :attr:`__dict__` attribute.
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +00001390
Raymond Hettingerd7100172013-06-02 10:03:05 -07001391 Objects such as modules and instances have an updateable :attr:`__dict__`
1392 attribute; however, other objects may have write restrictions on their
1393 :attr:`__dict__` attributes (for example, classes use a
1394 dictproxy to prevent direct dictionary updates).
Georg Brandl116aa622007-08-15 14:28:22 +00001395
Raymond Hettingerd7100172013-06-02 10:03:05 -07001396 Without an argument, :func:`vars` acts like :func:`locals`. Note, the
1397 locals dictionary is only useful for reads since updates to the locals
1398 dictionary are ignored.
1399
Georg Brandl116aa622007-08-15 14:28:22 +00001400
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001401.. function:: zip(*iterables)
Georg Brandl116aa622007-08-15 14:28:22 +00001402
Georg Brandl48310cd2009-01-03 21:18:54 +00001403 Make an iterator that aggregates elements from each of the iterables.
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001404
1405 Returns an iterator of tuples, where the *i*-th tuple contains
Georg Brandl952aea22007-09-04 17:50:40 +00001406 the *i*-th element from each of the argument sequences or iterables. The
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001407 iterator stops when the shortest input iterable is exhausted. With a single
Georg Brandl48310cd2009-01-03 21:18:54 +00001408 iterable argument, it returns an iterator of 1-tuples. With no arguments,
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001409 it returns an empty iterator. Equivalent to::
1410
Raymond Hettinger2f08df32010-10-10 05:54:39 +00001411 def zip(*iterables):
1412 # zip('ABCD', 'xy') --> Ax By
1413 sentinel = object()
Raymond Hettinger6f45d182011-10-30 15:06:14 -07001414 iterators = [iter(it) for it in iterables]
1415 while iterators:
Raymond Hettinger2f08df32010-10-10 05:54:39 +00001416 result = []
Raymond Hettinger6f45d182011-10-30 15:06:14 -07001417 for it in iterators:
Raymond Hettinger2f08df32010-10-10 05:54:39 +00001418 elem = next(it, sentinel)
1419 if elem is sentinel:
1420 return
1421 result.append(elem)
1422 yield tuple(result)
Georg Brandl116aa622007-08-15 14:28:22 +00001423
Christian Heimes1af737c2008-01-23 08:24:23 +00001424 The left-to-right evaluation order of the iterables is guaranteed. This
1425 makes possible an idiom for clustering a data series into n-length groups
1426 using ``zip(*[iter(s)]*n)``.
1427
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001428 :func:`zip` should only be used with unequal length inputs when you don't
1429 care about trailing, unmatched values from the longer iterables. If those
1430 values are important, use :func:`itertools.zip_longest` instead.
Georg Brandl116aa622007-08-15 14:28:22 +00001431
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001432 :func:`zip` in conjunction with the ``*`` operator can be used to unzip a
1433 list::
1434
1435 >>> x = [1, 2, 3]
1436 >>> y = [4, 5, 6]
1437 >>> zipped = zip(x, y)
Georg Brandl17fe3642008-12-06 14:28:56 +00001438 >>> list(zipped)
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001439 [(1, 4), (2, 5), (3, 6)]
Georg Brandl17fe3642008-12-06 14:28:56 +00001440 >>> x2, y2 = zip(*zip(x, y))
Benjamin Petersonfa0d7032009-06-01 22:42:33 +00001441 >>> x == list(x2) and y == list(y2)
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001442 True
1443
Georg Brandl2ee470f2008-07-16 12:55:28 +00001444
Brett Cannoncb4996a2012-08-06 16:34:44 -04001445.. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0)
Georg Brandl48367812008-12-05 15:55:41 +00001446
1447 .. index::
1448 statement: import
1449 module: imp
1450
1451 .. note::
1452
1453 This is an advanced function that is not needed in everyday Python
Éric Araujoe801aa22011-07-29 17:50:58 +02001454 programming, unlike :func:`importlib.import_module`.
Georg Brandl48367812008-12-05 15:55:41 +00001455
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001456 This function is invoked by the :keyword:`import` statement. It can be
1457 replaced (by importing the :mod:`builtins` module and assigning to
1458 ``builtins.__import__``) in order to change semantics of the
1459 :keyword:`import` statement, but nowadays it is usually simpler to use import
Brett Cannon2a082ad2012-04-14 21:58:33 -04001460 hooks (see :pep:`302`) to attain the same goals. Direct use of
1461 :func:`__import__` is entirely discouraged in favor of
1462 :func:`importlib.import_module`.
Georg Brandl48367812008-12-05 15:55:41 +00001463
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001464 The function imports the module *name*, potentially using the given *globals*
1465 and *locals* to determine how to interpret the name in a package context.
1466 The *fromlist* gives the names of objects or submodules that should be
1467 imported from the module given by *name*. The standard implementation does
1468 not use its *locals* argument at all, and uses its *globals* only to
1469 determine the package context of the :keyword:`import` statement.
1470
Brett Cannon2b9fd472009-03-15 02:18:41 +00001471 *level* specifies whether to use absolute or relative imports. ``0`` (the
1472 default) means only perform absolute imports. Positive values for
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001473 *level* indicate the number of parent directories to search relative to the
Brett Cannon2a082ad2012-04-14 21:58:33 -04001474 directory of the module calling :func:`__import__` (see :pep:`328` for the
1475 details).
Georg Brandl48367812008-12-05 15:55:41 +00001476
1477 When the *name* variable is of the form ``package.module``, normally, the
1478 top-level package (the name up till the first dot) is returned, *not* the
1479 module named by *name*. However, when a non-empty *fromlist* argument is
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001480 given, the module named by *name* is returned.
Georg Brandl48367812008-12-05 15:55:41 +00001481
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001482 For example, the statement ``import spam`` results in bytecode resembling the
1483 following code::
Georg Brandl48310cd2009-01-03 21:18:54 +00001484
Brett Cannon2b9fd472009-03-15 02:18:41 +00001485 spam = __import__('spam', globals(), locals(), [], 0)
Georg Brandl48367812008-12-05 15:55:41 +00001486
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001487 The statement ``import spam.ham`` results in this call::
Georg Brandl48367812008-12-05 15:55:41 +00001488
Brett Cannon2b9fd472009-03-15 02:18:41 +00001489 spam = __import__('spam.ham', globals(), locals(), [], 0)
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001490
1491 Note how :func:`__import__` returns the toplevel module here because this is
1492 the object that is bound to a name by the :keyword:`import` statement.
1493
1494 On the other hand, the statement ``from spam.ham import eggs, sausage as
1495 saus`` results in ::
1496
Brett Cannon2b9fd472009-03-15 02:18:41 +00001497 _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001498 eggs = _temp.eggs
1499 saus = _temp.sausage
1500
1501 Here, the ``spam.ham`` module is returned from :func:`__import__`. From this
1502 object, the names to import are retrieved and assigned to their respective
1503 names.
1504
1505 If you simply want to import a module (potentially within a package) by name,
Éric Araujoe801aa22011-07-29 17:50:58 +02001506 use :func:`importlib.import_module`.
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001507
Brett Cannon73df3642012-07-30 18:35:17 -04001508 .. versionchanged:: 3.3
Brett Cannon222d4732012-08-05 20:49:53 -04001509 Negative values for *level* are no longer supported (which also changes
1510 the default value to 0).
Brett Cannon73df3642012-07-30 18:35:17 -04001511
Georg Brandl48367812008-12-05 15:55:41 +00001512
Georg Brandl116aa622007-08-15 14:28:22 +00001513.. rubric:: Footnotes
1514
Georg Brandl47f27a32009-03-31 16:57:13 +00001515.. [#] Note that the parser only accepts the Unix-style end of line convention.
1516 If you are reading the code from a file, make sure to use newline conversion
1517 mode to convert Windows or Mac-style newlines.