blob: de29a1ae22c0967dd40fd8b84da0fa29a7e13b72 [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`
17:func:`bin` :func:`eval` :func:`int` :func:`open` :func:`str`
18:func:`bool` :func:`exec` :func:`isinstance` :func:`ord` :func:`sum`
19:func:`bytearray` :func:`filter` :func:`issubclass` :func:`pow` :func:`super`
20:func:`bytes` :func:`float` :func:`iter` :func:`print` :func:`tuple`
21:func:`callable` :func:`format` :func:`len` :func:`property` :func:`type`
Éric Araujo9edd9f02011-09-01 23:08:55 +020022: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()``
36
37
Georg Brandl116aa622007-08-15 14:28:22 +000038.. function:: abs(x)
39
Georg Brandlba956ae2007-11-29 17:24:34 +000040 Return the absolute value of a number. The argument may be an
Georg Brandl116aa622007-08-15 14:28:22 +000041 integer or a floating point number. If the argument is a complex number, its
42 magnitude is returned.
43
44
45.. function:: all(iterable)
46
Georg Brandl0192bff2009-04-27 16:49:41 +000047 Return True if all elements of the *iterable* are true (or if the iterable
48 is empty). Equivalent to::
Georg Brandl116aa622007-08-15 14:28:22 +000049
50 def all(iterable):
51 for element in iterable:
52 if not element:
53 return False
54 return True
55
Georg Brandl116aa622007-08-15 14:28:22 +000056
57.. function:: any(iterable)
58
Georg Brandl0192bff2009-04-27 16:49:41 +000059 Return True if any element of the *iterable* is true. If the iterable
60 is empty, return False. Equivalent to::
Georg Brandl116aa622007-08-15 14:28:22 +000061
62 def any(iterable):
63 for element in iterable:
64 if element:
65 return True
66 return False
67
Georg Brandl116aa622007-08-15 14:28:22 +000068
Georg Brandl559e5d72008-06-11 18:37:52 +000069.. function:: ascii(object)
70
71 As :func:`repr`, return a string containing a printable representation of an
72 object, but escape the non-ASCII characters in the string returned by
73 :func:`repr` using ``\x``, ``\u`` or ``\U`` escapes. This generates a string
74 similar to that returned by :func:`repr` in Python 2.
75
76
Georg Brandl116aa622007-08-15 14:28:22 +000077.. function:: bin(x)
78
79 Convert an integer number to a binary string. The result is a valid Python
80 expression. If *x* is not a Python :class:`int` object, it has to define an
81 :meth:`__index__` method that returns an integer.
82
Georg Brandl116aa622007-08-15 14:28:22 +000083
84.. function:: bool([x])
85
Éric Araujo18ddf822011-09-01 23:10:36 +020086 Convert a value to a Boolean, using the standard :ref:`truth testing
87 procedure <truth>`. If *x* is false or omitted, this returns ``False``;
88 otherwise it returns ``True``. :class:`bool` is also a class, which is a
89 subclass of :class:`int` (see :ref:`typesnumeric`). Class :class:`bool`
90 cannot be subclassed further. Its only instances are ``False`` and
91 ``True`` (see :ref:`bltin-boolean-values`).
Georg Brandl116aa622007-08-15 14:28:22 +000092
93 .. index:: pair: Boolean; type
94
Georg Brandl116aa622007-08-15 14:28:22 +000095
Georg Brandl036490d2009-05-17 13:00:36 +000096.. function:: bytearray([source[, encoding[, errors]]])
Georg Brandl85eb8c12007-08-31 16:33:38 +000097
Georg Brandl24eac032007-11-22 14:16:00 +000098 Return a new array of bytes. The :class:`bytearray` type is a mutable
Georg Brandl95414632007-11-22 11:00:28 +000099 sequence of integers in the range 0 <= x < 256. It has most of the usual
100 methods of mutable sequences, described in :ref:`typesseq-mutable`, as well
Antoine Pitroub85b3af2010-11-20 19:36:05 +0000101 as most methods that the :class:`bytes` type has, see :ref:`bytes-methods`.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000102
Georg Brandl036490d2009-05-17 13:00:36 +0000103 The optional *source* parameter can be used to initialize the array in a few
Georg Brandl85eb8c12007-08-31 16:33:38 +0000104 different ways:
105
106 * If it is a *string*, you must also give the *encoding* (and optionally,
Georg Brandlf6945182008-02-01 11:56:49 +0000107 *errors*) parameters; :func:`bytearray` then converts the string to
Guido van Rossum98297ee2007-11-06 21:34:58 +0000108 bytes using :meth:`str.encode`.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000109
110 * If it is an *integer*, the array will have that size and will be
111 initialized with null bytes.
112
113 * If it is an object conforming to the *buffer* interface, a read-only buffer
114 of the object will be used to initialize the bytes array.
115
Guido van Rossum98297ee2007-11-06 21:34:58 +0000116 * If it is an *iterable*, it must be an iterable of integers in the range
117 ``0 <= x < 256``, which are used as the initial contents of the array.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000118
119 Without an argument, an array of size 0 is created.
120
121
Georg Brandl036490d2009-05-17 13:00:36 +0000122.. function:: bytes([source[, encoding[, errors]]])
Guido van Rossum98297ee2007-11-06 21:34:58 +0000123
124 Return a new "bytes" object, which is an immutable sequence of integers in
125 the range ``0 <= x < 256``. :class:`bytes` is an immutable version of
Georg Brandl95414632007-11-22 11:00:28 +0000126 :class:`bytearray` -- it has the same non-mutating methods and the same
127 indexing and slicing behavior.
Georg Brandl48310cd2009-01-03 21:18:54 +0000128
Georg Brandl476b3552009-04-29 06:37:12 +0000129 Accordingly, constructor arguments are interpreted as for :func:`bytearray`.
Guido van Rossum98297ee2007-11-06 21:34:58 +0000130
131 Bytes objects can also be created with literals, see :ref:`strings`.
132
133
Antoine Pitroue71362d2010-11-27 22:00:11 +0000134.. function:: callable(object)
135
136 Return :const:`True` if the *object* argument appears callable,
137 :const:`False` if not. If this returns true, it is still possible that a
138 call fails, but if it is false, calling *object* will never succeed.
139 Note that classes are callable (calling a class returns a new instance);
140 instances are callable if their class has a :meth:`__call__` method.
141
142 .. versionadded:: 3.2
143 This function was first removed in Python 3.0 and then brought back
144 in Python 3.2.
145
146
Georg Brandl116aa622007-08-15 14:28:22 +0000147.. function:: chr(i)
148
Alexander Belopolsky5d4dd3e2010-11-18 18:50:13 +0000149 Return the string representing a character whose Unicode codepoint is the integer
Georg Brandl85eb8c12007-08-31 16:33:38 +0000150 *i*. For example, ``chr(97)`` returns the string ``'a'``. This is the
Alexander Belopolsky5d4dd3e2010-11-18 18:50:13 +0000151 inverse of :func:`ord`. The valid range for the argument is from 0 through
152 1,114,111 (0x10FFFF in base 16). :exc:`ValueError` will be raised if *i* is
153 outside that range.
154
Georg Brandl116aa622007-08-15 14:28:22 +0000155
156.. function:: classmethod(function)
157
158 Return a class method for *function*.
159
160 A class method receives the class as implicit first argument, just like an
161 instance method receives the instance. To declare a class method, use this
162 idiom::
163
164 class C:
165 @classmethod
166 def f(cls, arg1, arg2, ...): ...
167
Christian Heimesd8654cf2007-12-02 15:22:16 +0000168 The ``@classmethod`` form is a function :term:`decorator` -- see the description
169 of function definitions in :ref:`function` for details.
Georg Brandl116aa622007-08-15 14:28:22 +0000170
171 It can be called either on the class (such as ``C.f()``) or on an instance (such
172 as ``C().f()``). The instance is ignored except for its class. If a class
173 method is called for a derived class, the derived class object is passed as the
174 implied first argument.
175
176 Class methods are different than C++ or Java static methods. If you want those,
177 see :func:`staticmethod` in this section.
178
179 For more information on class methods, consult the documentation on the standard
180 type hierarchy in :ref:`types`.
181
Georg Brandl116aa622007-08-15 14:28:22 +0000182
Georg Brandl8334fd92010-12-04 10:26:46 +0000183.. function:: compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1)
Georg Brandl116aa622007-08-15 14:28:22 +0000184
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000185 Compile the *source* into a code or AST object. Code objects can be executed
Ezio Melotti6e40e272010-01-04 09:29:10 +0000186 by :func:`exec` or :func:`eval`. *source* can either be a string or an AST
Benjamin Peterson45abfbc2009-12-13 00:32:14 +0000187 object. Refer to the :mod:`ast` module documentation for information on how
188 to work with AST objects.
Georg Brandl116aa622007-08-15 14:28:22 +0000189
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000190 The *filename* argument should give the file from which the code was read;
191 pass some recognizable value if it wasn't read from a file (``'<string>'`` is
192 commonly used).
193
194 The *mode* argument specifies what kind of code must be compiled; it can be
195 ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
196 consists of a single expression, or ``'single'`` if it consists of a single
197 interactive statement (in the latter case, expression statements that
R. David Murray66011262009-06-25 17:37:57 +0000198 evaluate to something other than ``None`` will be printed).
Georg Brandl116aa622007-08-15 14:28:22 +0000199
Georg Brandle06de8b2008-05-05 21:42:51 +0000200 The optional arguments *flags* and *dont_inherit* control which future
201 statements (see :pep:`236`) affect the compilation of *source*. If neither
202 is present (or both are zero) the code is compiled with those future
203 statements that are in effect in the code that is calling compile. If the
204 *flags* argument is given and *dont_inherit* is not (or is zero) then the
Georg Brandl116aa622007-08-15 14:28:22 +0000205 future statements specified by the *flags* argument are used in addition to
206 those that would be used anyway. If *dont_inherit* is a non-zero integer then
Georg Brandle06de8b2008-05-05 21:42:51 +0000207 the *flags* argument is it -- the future statements in effect around the call
208 to compile are ignored.
Georg Brandl116aa622007-08-15 14:28:22 +0000209
Christian Heimesfaf2f632008-01-06 16:59:19 +0000210 Future statements are specified by bits which can be bitwise ORed together to
Georg Brandl116aa622007-08-15 14:28:22 +0000211 specify multiple statements. The bitfield required to specify a given feature
212 can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
213 instance in the :mod:`__future__` module.
214
Georg Brandl8334fd92010-12-04 10:26:46 +0000215 The argument *optimize* specifies the optimization level of the compiler; the
216 default value of ``-1`` selects the optimization level of the interpreter as
217 given by :option:`-O` options. Explicit levels are ``0`` (no optimization;
218 ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)
219 or ``2`` (docstrings are removed too).
220
Christian Heimes7f044312008-01-06 17:05:40 +0000221 This function raises :exc:`SyntaxError` if the compiled source is invalid,
222 and :exc:`TypeError` if the source contains null bytes.
223
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000224 .. note::
225
Benjamin Peterson20211002009-11-25 18:34:42 +0000226 When compiling a string with multi-line code in ``'single'`` or
Benjamin Petersonaeaa5922009-11-13 00:17:59 +0000227 ``'eval'`` mode, input must be terminated by at least one newline
228 character. This is to facilitate detection of incomplete and complete
229 statements in the :mod:`code` module.
230
Benjamin Petersonaeaa5922009-11-13 00:17:59 +0000231 .. versionchanged:: 3.2
232 Allowed use of Windows and Mac newlines. Also input in ``'exec'`` mode
Georg Brandl8334fd92010-12-04 10:26:46 +0000233 does not have to end in a newline anymore. Added the *optimize* parameter.
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000234
Georg Brandl116aa622007-08-15 14:28:22 +0000235
236.. function:: complex([real[, imag]])
237
238 Create a complex number with the value *real* + *imag*\*j or convert a string or
239 number to a complex number. If the first parameter is a string, it will be
240 interpreted as a complex number and the function must be called without a second
241 parameter. The second parameter can never be a string. Each argument may be any
242 numeric type (including complex). If *imag* is omitted, it defaults to zero and
Georg Brandl5c106642007-11-29 17:41:05 +0000243 the function serves as a numeric conversion function like :func:`int`
244 and :func:`float`. If both arguments are omitted, returns ``0j``.
Georg Brandl116aa622007-08-15 14:28:22 +0000245
Mark Dickinson328dd0d2012-03-10 16:09:35 +0000246 .. note::
247
248 When converting from a string, the string must not contain whitespace
249 around the central ``+`` or ``-`` operator. For example,
250 ``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` raises
251 :exc:`ValueError`.
252
Georg Brandl116aa622007-08-15 14:28:22 +0000253 The complex type is described in :ref:`typesnumeric`.
254
255
256.. function:: delattr(object, name)
257
258 This is a relative of :func:`setattr`. The arguments are an object and a
259 string. The string must be the name of one of the object's attributes. The
260 function deletes the named attribute, provided the object allows it. For
261 example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
262
263
Éric Araujo9edd9f02011-09-01 23:08:55 +0200264.. _func-dict:
Georg Brandl116aa622007-08-15 14:28:22 +0000265.. function:: dict([arg])
266 :noindex:
267
268 Create a new data dictionary, optionally with items taken from *arg*.
269 The dictionary type is described in :ref:`typesmapping`.
270
271 For other containers see the built in :class:`list`, :class:`set`, and
272 :class:`tuple` classes, and the :mod:`collections` module.
273
274
275.. function:: dir([object])
276
277 Without arguments, return the list of names in the current local scope. With an
278 argument, attempt to return a list of valid attributes for that object.
279
280 If the object has a method named :meth:`__dir__`, this method will be called and
281 must return the list of attributes. This allows objects that implement a custom
282 :func:`__getattr__` or :func:`__getattribute__` function to customize the way
283 :func:`dir` reports their attributes.
284
285 If the object does not provide :meth:`__dir__`, the function tries its best to
286 gather information from the object's :attr:`__dict__` attribute, if defined, and
287 from its type object. The resulting list is not necessarily complete, and may
288 be inaccurate when the object has a custom :func:`__getattr__`.
289
290 The default :func:`dir` mechanism behaves differently with different types of
291 objects, as it attempts to produce the most relevant, rather than complete,
292 information:
293
294 * If the object is a module object, the list contains the names of the module's
295 attributes.
296
297 * If the object is a type or class object, the list contains the names of its
298 attributes, and recursively of the attributes of its bases.
299
300 * Otherwise, the list contains the object's attributes' names, the names of its
301 class's attributes, and recursively of the attributes of its class's base
302 classes.
303
Christian Heimesfe337bf2008-03-23 21:54:12 +0000304 The resulting list is sorted alphabetically. For example:
305
306 >>> import struct
Raymond Hettinger90289282011-06-01 16:17:23 -0700307 >>> dir() # show the names in the module namespace
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300308 ['__builtins__', '__name__', 'struct']
309 >>> dir(struct) # show the names in the struct module # doctest: +SKIP
310 ['Struct', '__all__', '__builtins__', '__cached__', '__doc__', '__file__',
311 '__initializing__', '__loader__', '__name__', '__package__',
312 '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
Christian Heimesfe337bf2008-03-23 21:54:12 +0000313 'unpack', 'unpack_from']
Raymond Hettinger90289282011-06-01 16:17:23 -0700314 >>> class Shape(object):
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300315 ... def __dir__(self):
316 ... return ['area', 'perimeter', 'location']
Raymond Hettinger90289282011-06-01 16:17:23 -0700317 >>> s = Shape()
318 >>> dir(s)
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300319 ['area', 'location', 'perimeter']
Georg Brandl116aa622007-08-15 14:28:22 +0000320
321 .. note::
322
323 Because :func:`dir` is supplied primarily as a convenience for use at an
Georg Brandl036490d2009-05-17 13:00:36 +0000324 interactive prompt, it tries to supply an interesting set of names more
325 than it tries to supply a rigorously or consistently defined set of names,
326 and its detailed behavior may change across releases. For example,
327 metaclass attributes are not in the result list when the argument is a
328 class.
Georg Brandl116aa622007-08-15 14:28:22 +0000329
330
331.. function:: divmod(a, b)
332
333 Take two (non complex) numbers as arguments and return a pair of numbers
Georg Brandl036490d2009-05-17 13:00:36 +0000334 consisting of their quotient and remainder when using integer division. With
335 mixed operand types, the rules for binary arithmetic operators apply. For
336 integers, the result is the same as ``(a // b, a % b)``. For floating point
337 numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a /
338 b)`` but may be 1 less than that. In any case ``q * b + a % b`` is very
339 close to *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0
340 <= abs(a % b) < abs(b)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000341
Georg Brandl116aa622007-08-15 14:28:22 +0000342
Georg Brandl036490d2009-05-17 13:00:36 +0000343.. function:: enumerate(iterable, start=0)
Georg Brandl116aa622007-08-15 14:28:22 +0000344
Georg Brandld11ae5d2008-05-16 13:27:32 +0000345 Return an enumerate object. *iterable* must be a sequence, an
Alexandre Vassalottieca20b62008-05-16 02:54:33 +0000346 :term:`iterator`, or some other object which supports iteration. The
347 :meth:`__next__` method of the iterator returned by :func:`enumerate` returns a
Alexandre Vassalottie9f305f2008-05-16 04:39:54 +0000348 tuple containing a count (from *start* which defaults to 0) and the
Raymond Hettinger9d3df6d2011-06-25 15:00:14 +0200349 values obtained from iterating over *iterable*.
Georg Brandl116aa622007-08-15 14:28:22 +0000350
Raymond Hettinger9d3df6d2011-06-25 15:00:14 +0200351 >>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
352 >>> list(enumerate(seasons))
353 [(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
354 >>> list(enumerate(seasons, start=1))
355 [(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]
Raymond Hettinger90289282011-06-01 16:17:23 -0700356
357 Equivalent to::
358
359 def enumerate(sequence, start=0):
360 n = start
361 for elem in sequence:
362 yield n, elem
363 n += 1
Georg Brandl116aa622007-08-15 14:28:22 +0000364
Georg Brandl116aa622007-08-15 14:28:22 +0000365
Georg Brandl036490d2009-05-17 13:00:36 +0000366.. function:: eval(expression, globals=None, locals=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000367
368 The arguments are a string and optional globals and locals. If provided,
369 *globals* must be a dictionary. If provided, *locals* can be any mapping
370 object.
371
Georg Brandl116aa622007-08-15 14:28:22 +0000372 The *expression* argument is parsed and evaluated as a Python expression
373 (technically speaking, a condition list) using the *globals* and *locals*
Georg Brandl9afde1c2007-11-01 20:32:30 +0000374 dictionaries as global and local namespace. If the *globals* dictionary is
Georg Brandl116aa622007-08-15 14:28:22 +0000375 present and lacks '__builtins__', the current globals are copied into *globals*
376 before *expression* is parsed. This means that *expression* normally has full
Georg Brandl1a3284e2007-12-02 09:40:06 +0000377 access to the standard :mod:`builtins` module and restricted environments are
Georg Brandl116aa622007-08-15 14:28:22 +0000378 propagated. If the *locals* dictionary is omitted it defaults to the *globals*
379 dictionary. If both dictionaries are omitted, the expression is executed in the
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000380 environment where :func:`eval` is called. The return value is the result of
Christian Heimesfe337bf2008-03-23 21:54:12 +0000381 the evaluated expression. Syntax errors are reported as exceptions. Example:
Georg Brandl116aa622007-08-15 14:28:22 +0000382
383 >>> x = 1
Georg Brandl6911e3c2007-09-04 07:15:32 +0000384 >>> eval('x+1')
Georg Brandl116aa622007-08-15 14:28:22 +0000385 2
386
Benjamin Peterson3e4f0552008-09-02 00:31:15 +0000387 This function can also be used to execute arbitrary code objects (such as
388 those created by :func:`compile`). In this case pass a code object instead
389 of a string. If the code object has been compiled with ``'exec'`` as the
Georg Brandl1f70cdf2010-03-21 09:04:24 +0000390 *mode* argument, :func:`eval`\'s return value will be ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000391
392 Hints: dynamic execution of statements is supported by the :func:`exec`
393 function. The :func:`globals` and :func:`locals` functions
394 returns the current global and local dictionary, respectively, which may be
395 useful to pass around for use by :func:`eval` or :func:`exec`.
396
Georg Brandl05bfcc52010-07-11 09:42:10 +0000397 See :func:`ast.literal_eval` for a function that can safely evaluate strings
398 with expressions containing only literals.
399
Georg Brandl116aa622007-08-15 14:28:22 +0000400
401.. function:: exec(object[, globals[, locals]])
402
Benjamin Petersond3013ff2008-11-11 21:43:42 +0000403 This function supports dynamic execution of Python code. *object* must be
404 either a string or a code object. If it is a string, the string is parsed as
405 a suite of Python statements which is then executed (unless a syntax error
Georg Brandl47f27a32009-03-31 16:57:13 +0000406 occurs). [#]_ If it is a code object, it is simply executed. In all cases,
407 the code that's executed is expected to be valid as file input (see the
408 section "File input" in the Reference Manual). Be aware that the
409 :keyword:`return` and :keyword:`yield` statements may not be used outside of
410 function definitions even within the context of code passed to the
411 :func:`exec` function. The return value is ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000412
413 In all cases, if the optional parts are omitted, the code is executed in the
414 current scope. If only *globals* is provided, it must be a dictionary, which
415 will be used for both the global and the local variables. If *globals* and
416 *locals* are given, they are used for the global and local variables,
Terry Jan Reedy83efd6c2012-07-08 17:36:14 -0400417 respectively. If provided, *locals* can be any mapping object. Remember
418 that at module level, globals and locals are the same dictionary. If exec
419 gets two separate objects as *globals* and *locals*, the code will be
420 executed as if it were embedded in a class definition.
Georg Brandl116aa622007-08-15 14:28:22 +0000421
422 If the *globals* dictionary does not contain a value for the key
423 ``__builtins__``, a reference to the dictionary of the built-in module
Georg Brandl1a3284e2007-12-02 09:40:06 +0000424 :mod:`builtins` is inserted under that key. That way you can control what
Georg Brandl116aa622007-08-15 14:28:22 +0000425 builtins are available to the executed code by inserting your own
426 ``__builtins__`` dictionary into *globals* before passing it to :func:`exec`.
427
428 .. note::
429
430 The built-in functions :func:`globals` and :func:`locals` return the current
431 global and local dictionary, respectively, which may be useful to pass around
432 for use as the second and third argument to :func:`exec`.
433
Georg Brandle720c0a2009-04-27 16:20:50 +0000434 .. note::
Georg Brandl116aa622007-08-15 14:28:22 +0000435
436 The default *locals* act as described for function :func:`locals` below:
Georg Brandlf6945182008-02-01 11:56:49 +0000437 modifications to the default *locals* dictionary should not be attempted.
438 Pass an explicit *locals* dictionary if you need to see effects of the
439 code on *locals* after function :func:`exec` returns.
Georg Brandl116aa622007-08-15 14:28:22 +0000440
441
442.. function:: filter(function, iterable)
443
Georg Brandl952aea22007-09-04 17:50:40 +0000444 Construct an iterator from those elements of *iterable* for which *function*
445 returns true. *iterable* may be either a sequence, a container which
Georg Brandl9afde1c2007-11-01 20:32:30 +0000446 supports iteration, or an iterator. If *function* is ``None``, the identity
447 function is assumed, that is, all elements of *iterable* that are false are
448 removed.
Georg Brandl116aa622007-08-15 14:28:22 +0000449
Georg Brandl952aea22007-09-04 17:50:40 +0000450 Note that ``filter(function, iterable)`` is equivalent to the generator
451 expression ``(item for item in iterable if function(item))`` if function is
452 not ``None`` and ``(item for item in iterable if item)`` if function is
453 ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000454
Raymond Hettingercdf8ba32009-02-19 04:45:07 +0000455 See :func:`itertools.filterfalse` for the complementary function that returns
456 elements of *iterable* for which *function* returns false.
457
Georg Brandl116aa622007-08-15 14:28:22 +0000458
459.. function:: float([x])
460
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000461 .. index::
462 single: NaN
463 single: Infinity
Georg Brandl116aa622007-08-15 14:28:22 +0000464
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000465 Convert a string or a number to floating point.
Georg Brandl116aa622007-08-15 14:28:22 +0000466
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000467 If the argument is a string, it should contain a decimal number, optionally
468 preceded by a sign, and optionally embedded in whitespace. The optional
469 sign may be ``'+'`` or ``'-'``; a ``'+'`` sign has no effect on the value
470 produced. The argument may also be a string representing a NaN
471 (not-a-number), or a positive or negative infinity. More precisely, the
472 input must conform to the following grammar after leading and trailing
473 whitespace characters are removed:
Georg Brandl116aa622007-08-15 14:28:22 +0000474
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000475 .. productionlist::
476 sign: "+" | "-"
477 infinity: "Infinity" | "inf"
478 nan: "nan"
Georg Brandl46402372010-12-04 19:06:18 +0000479 numeric_value: `floatnumber` | `infinity` | `nan`
480 numeric_string: [`sign`] `numeric_value`
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000481
482 Here ``floatnumber`` is the form of a Python floating-point literal,
483 described in :ref:`floating`. Case is not significant, so, for example,
484 "inf", "Inf", "INFINITY" and "iNfINity" are all acceptable spellings for
485 positive infinity.
486
487 Otherwise, if the argument is an integer or a floating point number, a
488 floating point number with the same value (within Python's floating point
489 precision) is returned. If the argument is outside the range of a Python
490 float, an :exc:`OverflowError` will be raised.
491
492 For a general Python object ``x``, ``float(x)`` delegates to
493 ``x.__float__()``.
494
495 If no argument is given, ``0.0`` is returned.
496
497 Examples::
498
499 >>> float('+1.23')
500 1.23
501 >>> float(' -12345\n')
502 -12345.0
503 >>> float('1e-003')
504 0.001
505 >>> float('+1E6')
506 1000000.0
507 >>> float('-Infinity')
508 -inf
Georg Brandl116aa622007-08-15 14:28:22 +0000509
510 The float type is described in :ref:`typesnumeric`.
511
Éric Araujo9edd9f02011-09-01 23:08:55 +0200512
Georg Brandl4b491312007-08-31 09:22:56 +0000513.. function:: format(value[, format_spec])
514
515 .. index::
516 pair: str; format
517 single: __format__
Georg Brandl48310cd2009-01-03 21:18:54 +0000518
Georg Brandl5579ba92009-02-23 10:24:05 +0000519 Convert a *value* to a "formatted" representation, as controlled by
520 *format_spec*. The interpretation of *format_spec* will depend on the type
521 of the *value* argument, however there is a standard formatting syntax that
522 is used by most built-in types: :ref:`formatspec`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000523
Raymond Hettinger30439b22011-05-11 10:47:27 -0700524 The default *format_spec* is an empty string which usually gives the same
525 effect as calling ``str(value)``.
Georg Brandl4b491312007-08-31 09:22:56 +0000526
Raymond Hettinger30439b22011-05-11 10:47:27 -0700527 A call to ``format(value, format_spec)`` is translated to
528 ``type(value).__format__(format_spec)`` which bypasses the instance
529 dictionary when searching for the value's :meth:`__format__` method. A
530 :exc:`TypeError` exception is raised if the method is not found or if either
531 the *format_spec* or the return value are not strings.
Georg Brandl4b491312007-08-31 09:22:56 +0000532
Éric Araujo9edd9f02011-09-01 23:08:55 +0200533
534.. _func-frozenset:
Georg Brandl116aa622007-08-15 14:28:22 +0000535.. function:: frozenset([iterable])
536 :noindex:
537
538 Return a frozenset object, optionally with elements taken from *iterable*.
539 The frozenset type is described in :ref:`types-set`.
540
541 For other containers see the built in :class:`dict`, :class:`list`, and
542 :class:`tuple` classes, and the :mod:`collections` module.
543
Georg Brandl116aa622007-08-15 14:28:22 +0000544
545.. function:: getattr(object, name[, default])
546
Georg Brandl8e4ddcf2010-10-16 18:51:05 +0000547 Return the value of the named attribute of *object*. *name* must be a string.
Georg Brandl116aa622007-08-15 14:28:22 +0000548 If the string is the name of one of the object's attributes, the result is the
549 value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
550 ``x.foobar``. If the named attribute does not exist, *default* is returned if
551 provided, otherwise :exc:`AttributeError` is raised.
552
553
554.. function:: globals()
555
556 Return a dictionary representing the current global symbol table. This is always
557 the dictionary of the current module (inside a function or method, this is the
558 module where it is defined, not the module from which it is called).
559
560
561.. function:: hasattr(object, name)
562
Benjamin Peterson17689992010-08-24 03:26:23 +0000563 The arguments are an object and a string. The result is ``True`` if the
564 string is the name of one of the object's attributes, ``False`` if not. (This
565 is implemented by calling ``getattr(object, name)`` and seeing whether it
566 raises an :exc:`AttributeError` or not.)
Georg Brandl116aa622007-08-15 14:28:22 +0000567
568
569.. function:: hash(object)
570
571 Return the hash value of the object (if it has one). Hash values are integers.
572 They are used to quickly compare dictionary keys during a dictionary lookup.
573 Numeric values that compare equal have the same hash value (even if they are of
574 different types, as is the case for 1 and 1.0).
575
576
577.. function:: help([object])
578
579 Invoke the built-in help system. (This function is intended for interactive
580 use.) If no argument is given, the interactive help system starts on the
581 interpreter console. If the argument is a string, then the string is looked up
582 as the name of a module, function, class, method, keyword, or documentation
583 topic, and a help page is printed on the console. If the argument is any other
584 kind of object, a help page on the object is generated.
585
Christian Heimes9bd667a2008-01-20 15:14:11 +0000586 This function is added to the built-in namespace by the :mod:`site` module.
587
Georg Brandl116aa622007-08-15 14:28:22 +0000588
589.. function:: hex(x)
590
591 Convert an integer number to a hexadecimal string. The result is a valid Python
592 expression. If *x* is not a Python :class:`int` object, it has to define an
593 :meth:`__index__` method that returns an integer.
594
Mark Dickinson36cea392009-10-03 10:18:40 +0000595 .. note::
596
597 To obtain a hexadecimal string representation for a float, use the
598 :meth:`float.hex` method.
599
Georg Brandl116aa622007-08-15 14:28:22 +0000600
601.. function:: id(object)
602
Georg Brandlba956ae2007-11-29 17:24:34 +0000603 Return the "identity" of an object. This is an integer which
Georg Brandl116aa622007-08-15 14:28:22 +0000604 is guaranteed to be unique and constant for this object during its lifetime.
Georg Brandl495f7b52009-10-27 15:28:25 +0000605 Two objects with non-overlapping lifetimes may have the same :func:`id`
606 value.
607
Éric Araujof33de712011-05-27 04:42:47 +0200608 .. impl-detail:: This is the address of the object in memory.
Georg Brandl116aa622007-08-15 14:28:22 +0000609
610
Georg Brandlc0902982007-09-12 21:29:27 +0000611.. function:: input([prompt])
612
613 If the *prompt* argument is present, it is written to standard output without
614 a trailing newline. The function then reads a line from input, converts it
615 to a string (stripping a trailing newline), and returns that. When EOF is
616 read, :exc:`EOFError` is raised. Example::
617
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300618 >>> s = input('--> ') # doctest: +SKIP
Georg Brandlc0902982007-09-12 21:29:27 +0000619 --> Monty Python's Flying Circus
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300620 >>> s # doctest: +SKIP
Georg Brandlc0902982007-09-12 21:29:27 +0000621 "Monty Python's Flying Circus"
622
Georg Brandl7b469422007-09-12 21:32:27 +0000623 If the :mod:`readline` module was loaded, then :func:`input` will use it
Georg Brandlc0902982007-09-12 21:29:27 +0000624 to provide elaborate line editing and history features.
625
626
Georg Brandl1b5ab452009-08-13 07:56:35 +0000627.. function:: int([number | string[, base]])
Georg Brandl116aa622007-08-15 14:28:22 +0000628
Georg Brandl225d3c82008-04-09 18:45:14 +0000629 Convert a number or string to an integer. If no arguments are given, return
630 ``0``. If a number is given, return ``number.__int__()``. Conversion of
631 floating point numbers to integers truncates towards zero. A string must be
632 a base-radix integer literal optionally preceded by '+' or '-' (with no space
633 in between) and optionally surrounded by whitespace. A base-n literal
634 consists of the digits 0 to n-1, with 'a' to 'z' (or 'A' to 'Z') having
Georg Brandl1b5ab452009-08-13 07:56:35 +0000635 values 10 to 35. The default *base* is 10. The allowed values are 0 and 2-36.
Georg Brandl225d3c82008-04-09 18:45:14 +0000636 Base-2, -8, and -16 literals can be optionally prefixed with ``0b``/``0B``,
Georg Brandl1b5ab452009-08-13 07:56:35 +0000637 ``0o``/``0O``, or ``0x``/``0X``, as with integer literals in code. Base 0
638 means to interpret exactly as a code literal, so that the actual base is 2,
Georg Brandl225d3c82008-04-09 18:45:14 +0000639 8, 10, or 16, and so that ``int('010', 0)`` is not legal, while
640 ``int('010')`` is, as well as ``int('010', 8)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000641
642 The integer type is described in :ref:`typesnumeric`.
643
644
645.. function:: isinstance(object, classinfo)
646
Georg Brandl85eb8c12007-08-31 16:33:38 +0000647 Return true if the *object* argument is an instance of the *classinfo*
Éric Araujoe8b7eb02011-08-19 02:17:03 +0200648 argument, or of a (direct, indirect or :term:`virtual <abstract base
649 class>`) subclass thereof. If *object* is not
Georg Brandl85eb8c12007-08-31 16:33:38 +0000650 an object of the given type, the function always returns false. If
651 *classinfo* is not a class (type object), it may be a tuple of type objects,
652 or may recursively contain other such tuples (other sequence types are not
653 accepted). If *classinfo* is not a type or tuple of types and such tuples,
654 a :exc:`TypeError` exception is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000655
Georg Brandl116aa622007-08-15 14:28:22 +0000656
657.. function:: issubclass(class, classinfo)
658
Éric Araujoe8b7eb02011-08-19 02:17:03 +0200659 Return true if *class* is a subclass (direct, indirect or :term:`virtual
660 <abstract base class>`) of *classinfo*. A
Georg Brandl116aa622007-08-15 14:28:22 +0000661 class is considered a subclass of itself. *classinfo* may be a tuple of class
662 objects, in which case every entry in *classinfo* will be checked. In any other
663 case, a :exc:`TypeError` exception is raised.
664
Georg Brandl116aa622007-08-15 14:28:22 +0000665
Georg Brandl036490d2009-05-17 13:00:36 +0000666.. function:: iter(object[, sentinel])
Georg Brandl116aa622007-08-15 14:28:22 +0000667
Georg Brandl036490d2009-05-17 13:00:36 +0000668 Return an :term:`iterator` object. The first argument is interpreted very
669 differently depending on the presence of the second argument. Without a
670 second argument, *object* must be a collection object which supports the
671 iteration protocol (the :meth:`__iter__` method), or it must support the
672 sequence protocol (the :meth:`__getitem__` method with integer arguments
673 starting at ``0``). If it does not support either of those protocols,
674 :exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
675 then *object* must be a callable object. The iterator created in this case
676 will call *object* with no arguments for each call to its :meth:`__next__`
677 method; if the value returned is equal to *sentinel*, :exc:`StopIteration`
678 will be raised, otherwise the value will be returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000679
Benjamin Petersonf07d0022009-03-21 17:31:58 +0000680 One useful application of the second form of :func:`iter` is to read lines of
681 a file until a certain line is reached. The following example reads a file
Raymond Hettinger90289282011-06-01 16:17:23 -0700682 until the :meth:`readline` method returns an empty string::
Benjamin Petersonf07d0022009-03-21 17:31:58 +0000683
Raymond Hettinger90289282011-06-01 16:17:23 -0700684 with open('mydata.txt') as fp:
685 for line in iter(fp.readline, ''):
Benjamin Petersonf07d0022009-03-21 17:31:58 +0000686 process_line(line)
687
Georg Brandl116aa622007-08-15 14:28:22 +0000688
689.. function:: len(s)
690
691 Return the length (the number of items) of an object. The argument may be a
692 sequence (string, tuple or list) or a mapping (dictionary).
693
694
695.. function:: list([iterable])
696
697 Return a list whose items are the same and in the same order as *iterable*'s
698 items. *iterable* may be either a sequence, a container that supports
699 iteration, or an iterator object. If *iterable* is already a list, a copy is
700 made and returned, similar to ``iterable[:]``. For instance, ``list('abc')``
Georg Brandl036490d2009-05-17 13:00:36 +0000701 returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``.
702 If no argument is given, returns a new empty list, ``[]``.
Georg Brandl116aa622007-08-15 14:28:22 +0000703
Georg Brandl48310cd2009-01-03 21:18:54 +0000704 :class:`list` is a mutable sequence type, as documented in :ref:`typesseq`.
Georg Brandl116aa622007-08-15 14:28:22 +0000705
Georg Brandl036490d2009-05-17 13:00:36 +0000706
Georg Brandl116aa622007-08-15 14:28:22 +0000707.. function:: locals()
708
709 Update and return a dictionary representing the current local symbol table.
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000710 Free variables are returned by :func:`locals` when it is called in function
711 blocks, but not in class blocks.
Georg Brandl116aa622007-08-15 14:28:22 +0000712
Georg Brandle720c0a2009-04-27 16:20:50 +0000713 .. note::
Georg Brandl036490d2009-05-17 13:00:36 +0000714 The contents of this dictionary should not be modified; changes may not
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000715 affect the values of local and free variables used by the interpreter.
Georg Brandl116aa622007-08-15 14:28:22 +0000716
717.. function:: map(function, iterable, ...)
718
Georg Brandl952aea22007-09-04 17:50:40 +0000719 Return an iterator that applies *function* to every item of *iterable*,
720 yielding the results. If additional *iterable* arguments are passed,
721 *function* must take that many arguments and is applied to the items from all
Georg Brandlde2b00e2008-05-05 21:04:12 +0000722 iterables in parallel. With multiple iterables, the iterator stops when the
Raymond Hettingercdf8ba32009-02-19 04:45:07 +0000723 shortest iterable is exhausted. For cases where the function inputs are
724 already arranged into argument tuples, see :func:`itertools.starmap`\.
Georg Brandlde2b00e2008-05-05 21:04:12 +0000725
Georg Brandl116aa622007-08-15 14:28:22 +0000726
Georg Brandl55ac8f02007-09-01 13:51:09 +0000727.. function:: max(iterable[, args...], *[, key])
Georg Brandl116aa622007-08-15 14:28:22 +0000728
729 With a single argument *iterable*, return the largest item of a non-empty
730 iterable (such as a string, tuple or list). With more than one argument, return
731 the largest of the arguments.
732
Georg Brandl55ac8f02007-09-01 13:51:09 +0000733 The optional keyword-only *key* argument specifies a one-argument ordering
734 function like that used for :meth:`list.sort`.
Georg Brandl116aa622007-08-15 14:28:22 +0000735
Georg Brandl682d7e02010-10-06 10:26:05 +0000736 If multiple items are maximal, the function returns the first one
737 encountered. This is consistent with other sort-stability preserving tools
738 such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and
Raymond Hettinger476a31e2010-09-14 23:13:42 +0000739 ``heapq.nlargest(1, iterable, key=keyfunc)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000740
Éric Araujo9edd9f02011-09-01 23:08:55 +0200741
742.. _func-memoryview:
Georg Brandl85eb8c12007-08-31 16:33:38 +0000743.. function:: memoryview(obj)
Benjamin Peterson6dfcb022008-09-10 21:02:02 +0000744 :noindex:
Georg Brandl85eb8c12007-08-31 16:33:38 +0000745
Benjamin Peterson1b25b922008-09-09 22:15:27 +0000746 Return a "memory view" object created from the given argument. See
747 :ref:`typememoryview` for more information.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000748
749
Georg Brandl55ac8f02007-09-01 13:51:09 +0000750.. function:: min(iterable[, args...], *[, key])
Georg Brandl116aa622007-08-15 14:28:22 +0000751
752 With a single argument *iterable*, return the smallest item of a non-empty
753 iterable (such as a string, tuple or list). With more than one argument, return
754 the smallest of the arguments.
755
Georg Brandl55ac8f02007-09-01 13:51:09 +0000756 The optional keyword-only *key* argument specifies a one-argument ordering
757 function like that used for :meth:`list.sort`.
Georg Brandl116aa622007-08-15 14:28:22 +0000758
Georg Brandl682d7e02010-10-06 10:26:05 +0000759 If multiple items are minimal, the function returns the first one
760 encountered. This is consistent with other sort-stability preserving tools
761 such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1,
762 iterable, key=keyfunc)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000763
764.. function:: next(iterator[, default])
765
Georg Brandlc14bb752008-04-29 21:00:18 +0000766 Retrieve the next item from the *iterator* by calling its :meth:`__next__`
Georg Brandl116aa622007-08-15 14:28:22 +0000767 method. If *default* is given, it is returned if the iterator is exhausted,
768 otherwise :exc:`StopIteration` is raised.
769
770
771.. function:: object()
772
Georg Brandl85eb8c12007-08-31 16:33:38 +0000773 Return a new featureless object. :class:`object` is a base for all classes.
Georg Brandl55ac8f02007-09-01 13:51:09 +0000774 It has the methods that are common to all instances of Python classes. This
775 function does not accept any arguments.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000776
777 .. note::
778
779 :class:`object` does *not* have a :attr:`__dict__`, so you can't assign
780 arbitrary attributes to an instance of the :class:`object` class.
Georg Brandl116aa622007-08-15 14:28:22 +0000781
Georg Brandl116aa622007-08-15 14:28:22 +0000782
783.. function:: oct(x)
784
785 Convert an integer number to an octal string. The result is a valid Python
786 expression. If *x* is not a Python :class:`int` object, it has to define an
787 :meth:`__index__` method that returns an integer.
788
Georg Brandl116aa622007-08-15 14:28:22 +0000789
Ross Lagerwall59142db2011-10-31 20:34:46 +0200790.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000791
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000792 Open *file* and return a corresponding stream. If the file cannot be opened,
Antoine Pitrou62ab10a2011-10-12 20:10:51 +0200793 an :exc:`OSError` is raised.
Georg Brandl48310cd2009-01-03 21:18:54 +0000794
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000795 *file* is either a string or bytes object giving the pathname (absolute or
796 relative to the current working directory) of the file to be opened or
Georg Brandl76e55382008-10-08 16:34:57 +0000797 an integer file descriptor of the file to be wrapped. (If a file descriptor
798 is given, it is closed when the returned I/O object is closed, unless
799 *closefd* is set to ``False``.)
Georg Brandl116aa622007-08-15 14:28:22 +0000800
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000801 *mode* is an optional string that specifies the mode in which the file is
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000802 opened. It defaults to ``'r'`` which means open for reading in text mode.
803 Other common values are ``'w'`` for writing (truncating the file if it
Charles-François Natalib93f9fa2012-05-20 11:41:53 +0200804 already exists), ``'x'`` for exclusive creation and ``'a'`` for appending
805 (which on *some* Unix systems, means that *all* writes append to the end of
806 the file regardless of the current seek position). In text mode, if
Victor Stinnerf86a5e82012-06-05 13:43:22 +0200807 *encoding* is not specified the encoding used is platform dependent:
808 ``locale.getpreferredencoding(False)`` is called to get the current locale
809 encoding. (For reading and writing raw bytes use binary mode and leave
810 *encoding* unspecified.) The available modes are:
Georg Brandl116aa622007-08-15 14:28:22 +0000811
Benjamin Petersondd219122008-04-11 21:17:32 +0000812 ========= ===============================================================
813 Character Meaning
814 --------- ---------------------------------------------------------------
815 ``'r'`` open for reading (default)
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000816 ``'w'`` open for writing, truncating the file first
Charles-François Natalib93f9fa2012-05-20 11:41:53 +0200817 ``'x'`` open for exclusive creation, failing if the file already exists
Benjamin Petersondd219122008-04-11 21:17:32 +0000818 ``'a'`` open for writing, appending to the end of the file if it exists
Georg Brandl7b6ca4a2009-04-27 06:13:55 +0000819 ``'b'`` binary mode
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000820 ``'t'`` text mode (default)
821 ``'+'`` open a disk file for updating (reading and writing)
R David Murray1b00f252012-08-15 10:43:58 -0400822 ``'U'`` universal newlines mode (for backwards compatibility; should
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000823 not be used in new code)
Benjamin Petersondd219122008-04-11 21:17:32 +0000824 ========= ===============================================================
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000825
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000826 The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``).
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000827 For binary read-write access, the mode ``'w+b'`` opens and truncates the file
828 to 0 bytes. ``'r+b'`` opens the file without truncation.
Skip Montanaro1c639602007-09-23 19:49:54 +0000829
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000830 As mentioned in the :ref:`io-overview`, Python distinguishes between binary
831 and text I/O. Files opened in binary mode (including ``'b'`` in the *mode*
832 argument) return contents as :class:`bytes` objects without any decoding. In
833 text mode (the default, or when ``'t'`` is included in the *mode* argument),
834 the contents of the file are returned as :class:`str`, the bytes having been
835 first decoded using a platform-dependent encoding or using the specified
836 *encoding* if given.
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000837
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000838 .. note::
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000839
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000840 Python doesn't depend on the underlying operating system's notion of text
Ezio Melottie130a522011-10-19 10:58:56 +0300841 files; all the processing is done by Python itself, and is therefore
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000842 platform-independent.
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000843
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000844 *buffering* is an optional integer used to set the buffering policy. Pass 0
845 to switch buffering off (only allowed in binary mode), 1 to select line
846 buffering (only usable in text mode), and an integer > 1 to indicate the size
847 of a fixed-size chunk buffer. When no *buffering* argument is given, the
848 default buffering policy works as follows:
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000849
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000850 * Binary files are buffered in fixed-size chunks; the size of the buffer is
851 chosen using a heuristic trying to determine the underlying device's "block
852 size" and falling back on :attr:`io.DEFAULT_BUFFER_SIZE`. On many systems,
853 the buffer will typically be 4096 or 8192 bytes long.
854
855 * "Interactive" text files (files for which :meth:`isatty` returns True) use
856 line buffering. Other text files use the policy described above for binary
857 files.
Georg Brandl48310cd2009-01-03 21:18:54 +0000858
Benjamin Petersondd219122008-04-11 21:17:32 +0000859 *encoding* is the name of the encoding used to decode or encode the file.
860 This should only be used in text mode. The default encoding is platform
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000861 dependent (whatever :func:`locale.getpreferredencoding` returns), but any
862 encoding supported by Python can be used. See the :mod:`codecs` module for
863 the list of supported encodings.
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000864
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000865 *errors* is an optional string that specifies how encoding and decoding
866 errors are to be handled--this cannot be used in binary mode. Pass
867 ``'strict'`` to raise a :exc:`ValueError` exception if there is an encoding
868 error (the default of ``None`` has the same effect), or pass ``'ignore'`` to
869 ignore errors. (Note that ignoring encoding errors can lead to data loss.)
870 ``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted
871 where there is malformed data. When writing, ``'xmlcharrefreplace'``
872 (replace with the appropriate XML character reference) or
873 ``'backslashreplace'`` (replace with backslashed escape sequences) can be
874 used. Any other error handling name that has been registered with
875 :func:`codecs.register_error` is also valid.
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000876
R David Murray1b00f252012-08-15 10:43:58 -0400877 .. index::
878 single: universal newlines; open() built-in function
879
880 *newline* controls how :term:`universal newlines` mode works (it only
R David Murrayee0a9452012-08-15 11:05:36 -0400881 applies to text mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and
882 ``'\r\n'``. It works as follows:
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000883
Georg Brandl296d1be2012-08-14 09:39:07 +0200884 * When reading input from the stream, if *newline* is ``None``, universal
885 newlines mode is enabled. Lines in the input can end in ``'\n'``,
886 ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` before
R David Murray1b00f252012-08-15 10:43:58 -0400887 being returned to the caller. If it is ``''``, universal newlines mode is
Georg Brandl296d1be2012-08-14 09:39:07 +0200888 enabled, but line endings are returned to the caller untranslated. If it
889 has any of the other legal values, input lines are only terminated by the
890 given string, and the line ending is returned to the caller untranslated.
Benjamin Petersondd219122008-04-11 21:17:32 +0000891
Georg Brandl296d1be2012-08-14 09:39:07 +0200892 * When writing output to the stream, if *newline* is ``None``, any ``'\n'``
893 characters written are translated to the system default line separator,
894 :data:`os.linesep`. If *newline* is ``''`` or ``'\n'``, no translation
895 takes place. If *newline* is any of the other legal values, any ``'\n'``
896 characters written are translated to the given string.
Benjamin Petersondd219122008-04-11 21:17:32 +0000897
Benjamin Peterson8cad9c72009-03-23 02:38:01 +0000898 If *closefd* is ``False`` and a file descriptor rather than a filename was
899 given, the underlying file descriptor will be kept open when the file is
900 closed. If a filename is given *closefd* has no effect and must be ``True``
901 (the default).
902
Ross Lagerwall59142db2011-10-31 20:34:46 +0200903 A custom opener can be used by passing a callable as *opener*. The underlying
904 file descriptor for the file object is then obtained by calling *opener* with
905 (*file*, *flags*). *opener* must return an open file descriptor (passing
906 :mod:`os.open` as *opener* results in functionality similar to passing
907 ``None``).
908
909 .. versionchanged:: 3.3
910 The *opener* parameter was added.
Charles-François Natalib93f9fa2012-05-20 11:41:53 +0200911 The ``'x'`` mode was added.
Ross Lagerwall59142db2011-10-31 20:34:46 +0200912
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000913 The type of file object returned by the :func:`open` function depends on the
914 mode. When :func:`open` is used to open a file in a text mode (``'w'``,
Benjamin Peterson8cad9c72009-03-23 02:38:01 +0000915 ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
Benjamin Peterson6b4fa772010-08-30 13:19:53 +0000916 :class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used
917 to open a file in a binary mode with buffering, the returned class is a
918 subclass of :class:`io.BufferedIOBase`. The exact class varies: in read
919 binary mode, it returns a :class:`io.BufferedReader`; in write binary and
920 append binary modes, it returns a :class:`io.BufferedWriter`, and in
921 read/write mode, it returns a :class:`io.BufferedRandom`. When buffering is
922 disabled, the raw stream, a subclass of :class:`io.RawIOBase`,
923 :class:`io.FileIO`, is returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000924
925 .. index::
926 single: line-buffered I/O
927 single: unbuffered I/O
928 single: buffer size, I/O
929 single: I/O control; buffering
Skip Montanaro4d8c1932007-09-23 21:13:45 +0000930 single: binary mode
931 single: text mode
932 module: sys
Georg Brandl116aa622007-08-15 14:28:22 +0000933
Benjamin Petersondd219122008-04-11 21:17:32 +0000934 See also the file handling modules, such as, :mod:`fileinput`, :mod:`io`
Benjamin Peterson8cad9c72009-03-23 02:38:01 +0000935 (where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:`tempfile`,
936 and :mod:`shutil`.
Georg Brandl116aa622007-08-15 14:28:22 +0000937
Antoine Pitrou62ab10a2011-10-12 20:10:51 +0200938 .. versionchanged:: 3.3
939 :exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`.
Charles-François Natalib93f9fa2012-05-20 11:41:53 +0200940 :exc:`FileExistsError` is now raised if the file opened in exclusive
941 creation mode (``'x'``) already exists.
Antoine Pitrou62ab10a2011-10-12 20:10:51 +0200942
Georg Brandlf6945182008-02-01 11:56:49 +0000943
944.. XXX works for bytes too, but should it?
Georg Brandl116aa622007-08-15 14:28:22 +0000945.. function:: ord(c)
946
Ezio Melottic99c8582011-10-25 09:32:34 +0300947 Given a string representing one Unicode character, return an integer
Alexander Belopolsky5d4dd3e2010-11-18 18:50:13 +0000948 representing the Unicode code
949 point of that character. For example, ``ord('a')`` returns the integer ``97``
Georg Brandlf6945182008-02-01 11:56:49 +0000950 and ``ord('\u2020')`` returns ``8224``. This is the inverse of :func:`chr`.
951
Georg Brandl116aa622007-08-15 14:28:22 +0000952
953.. function:: pow(x, y[, z])
954
955 Return *x* to the power *y*; if *z* is present, return *x* to the power *y*,
956 modulo *z* (computed more efficiently than ``pow(x, y) % z``). The two-argument
957 form ``pow(x, y)`` is equivalent to using the power operator: ``x**y``.
958
Georg Brandle06de8b2008-05-05 21:42:51 +0000959 The arguments must have numeric types. With mixed operand types, the
960 coercion rules for binary arithmetic operators apply. For :class:`int`
961 operands, the result has the same type as the operands (after coercion)
962 unless the second argument is negative; in that case, all arguments are
963 converted to float and a float result is delivered. For example, ``10**2``
964 returns ``100``, but ``10**-2`` returns ``0.01``. If the second argument is
965 negative, the third argument must be omitted. If *z* is present, *x* and *y*
966 must be of integer types, and *y* must be non-negative.
Georg Brandl116aa622007-08-15 14:28:22 +0000967
968
Georg Brandlbc3b6822012-01-13 19:41:25 +0100969.. function:: print([object, ...], *, sep=' ', end='\\n', file=sys.stdout, flush=False)
Georg Brandlf6945182008-02-01 11:56:49 +0000970
971 Print *object*\(s) to the stream *file*, separated by *sep* and followed by
972 *end*. *sep*, *end* and *file*, if present, must be given as keyword
973 arguments.
974
975 All non-keyword arguments are converted to strings like :func:`str` does and
976 written to the stream, separated by *sep* and followed by *end*. Both *sep*
977 and *end* must be strings; they can also be ``None``, which means to use the
978 default values. If no *object* is given, :func:`print` will just write
979 *end*.
980
981 The *file* argument must be an object with a ``write(string)`` method; if it
Georg Brandlbc3b6822012-01-13 19:41:25 +0100982 is not present or ``None``, :data:`sys.stdout` will be used. Whether output
983 is buffered is usually determined by *file*, but if the *flush* keyword
984 argument is true, the stream is forcibly flushed.
985
986 .. versionchanged:: 3.3
987 Added the *flush* keyword argument.
Georg Brandlf6945182008-02-01 11:56:49 +0000988
989
Georg Brandl036490d2009-05-17 13:00:36 +0000990.. function:: property(fget=None, fset=None, fdel=None, doc=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000991
Georg Brandl85eb8c12007-08-31 16:33:38 +0000992 Return a property attribute.
Georg Brandl116aa622007-08-15 14:28:22 +0000993
994 *fget* is a function for getting an attribute value, likewise *fset* is a
995 function for setting, and *fdel* a function for del'ing, an attribute. Typical
Georg Brandl7528b9b2010-08-02 19:23:34 +0000996 use is to define a managed attribute ``x``::
Georg Brandl116aa622007-08-15 14:28:22 +0000997
Éric Araujo28053fb2010-11-22 03:09:19 +0000998 class C:
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +0000999 def __init__(self):
1000 self._x = None
1001
1002 def getx(self):
1003 return self._x
1004 def setx(self, value):
1005 self._x = value
1006 def delx(self):
1007 del self._x
Georg Brandl116aa622007-08-15 14:28:22 +00001008 x = property(getx, setx, delx, "I'm the 'x' property.")
1009
Georg Brandl7528b9b2010-08-02 19:23:34 +00001010 If then *c* is an instance of *C*, ``c.x`` will invoke the getter,
1011 ``c.x = value`` will invoke the setter and ``del c.x`` the deleter.
1012
Georg Brandl116aa622007-08-15 14:28:22 +00001013 If given, *doc* will be the docstring of the property attribute. Otherwise, the
1014 property will copy *fget*'s docstring (if it exists). This makes it possible to
Christian Heimesd8654cf2007-12-02 15:22:16 +00001015 create read-only properties easily using :func:`property` as a :term:`decorator`::
Georg Brandl116aa622007-08-15 14:28:22 +00001016
Éric Araujo28053fb2010-11-22 03:09:19 +00001017 class Parrot:
Georg Brandl116aa622007-08-15 14:28:22 +00001018 def __init__(self):
1019 self._voltage = 100000
1020
1021 @property
1022 def voltage(self):
1023 """Get the current voltage."""
1024 return self._voltage
1025
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +00001026 turns the :meth:`voltage` method into a "getter" for a read-only attribute
1027 with the same name.
1028
1029 A property object has :attr:`getter`, :attr:`setter`, and :attr:`deleter`
1030 methods usable as decorators that create a copy of the property with the
1031 corresponding accessor function set to the decorated function. This is
1032 best explained with an example::
1033
Éric Araujo28053fb2010-11-22 03:09:19 +00001034 class C:
Benjamin Peterson206e3072008-10-19 14:07:49 +00001035 def __init__(self):
1036 self._x = None
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +00001037
1038 @property
1039 def x(self):
1040 """I'm the 'x' property."""
1041 return self._x
1042
1043 @x.setter
1044 def x(self, value):
1045 self._x = value
1046
1047 @x.deleter
1048 def x(self):
1049 del self._x
1050
1051 This code is exactly equivalent to the first example. Be sure to give the
1052 additional functions the same name as the original property (``x`` in this
1053 case.)
1054
1055 The returned property also has the attributes ``fget``, ``fset``, and
1056 ``fdel`` corresponding to the constructor arguments.
Georg Brandl116aa622007-08-15 14:28:22 +00001057
Georg Brandl116aa622007-08-15 14:28:22 +00001058
Georg Brandl952aea22007-09-04 17:50:40 +00001059.. XXX does accept objects with __index__ too
Georg Brandl116aa622007-08-15 14:28:22 +00001060.. function:: range([start,] stop[, step])
1061
Georg Brandlbf086a12008-05-12 16:53:56 +00001062 This is a versatile function to create iterables yielding arithmetic
Georg Brandl95817b32008-05-11 14:30:18 +00001063 progressions. It is most often used in :keyword:`for` loops. The arguments
1064 must be integers. If the *step* argument is omitted, it defaults to ``1``.
1065 If the *start* argument is omitted, it defaults to ``0``. The full form
Georg Brandlbf086a12008-05-12 16:53:56 +00001066 returns an iterable of integers ``[start, start + step, start + 2 * step,
Georg Brandl95817b32008-05-11 14:30:18 +00001067 ...]``. If *step* is positive, the last element is the largest ``start + i *
1068 step`` less than *stop*; if *step* is negative, the last element is the
1069 smallest ``start + i * step`` greater than *stop*. *step* must not be zero
Benjamin Peterson878ce382011-11-05 15:17:52 -04001070 (or else :exc:`ValueError` is raised). Range objects have read-only data
1071 attributes :attr:`start`, :attr:`stop` and :attr:`step` which return the
1072 argument values (or their default). Example:
Georg Brandl116aa622007-08-15 14:28:22 +00001073
1074 >>> list(range(10))
1075 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1076 >>> list(range(1, 11))
1077 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
1078 >>> list(range(0, 30, 5))
1079 [0, 5, 10, 15, 20, 25]
1080 >>> list(range(0, 10, 3))
1081 [0, 3, 6, 9]
1082 >>> list(range(0, -10, -1))
1083 [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
1084 >>> list(range(0))
1085 []
1086 >>> list(range(1, 0))
1087 []
1088
Nick Coghlan37ee8502010-12-03 14:26:13 +00001089 Range objects implement the :class:`collections.Sequence` ABC, and provide
1090 features such as containment tests, element index lookup, slicing and
Éric Araujo18ddf822011-09-01 23:10:36 +02001091 support for negative indices (see :ref:`typesseq`):
Nick Coghlan37ee8502010-12-03 14:26:13 +00001092
1093 >>> r = range(0, 20, 2)
1094 >>> r
1095 range(0, 20, 2)
1096 >>> 11 in r
1097 False
1098 >>> 10 in r
1099 True
1100 >>> r.index(10)
1101 5
1102 >>> r[5]
1103 10
1104 >>> r[:5]
1105 range(0, 10, 2)
1106 >>> r[-1]
1107 18
1108
Mark Dickinson36645682011-10-23 19:53:01 +01001109 Testing range objects for equality with ``==`` and ``!=`` compares
1110 them as sequences. That is, two range objects are considered equal if
1111 they represent the same sequence of values. (Note that two range
1112 objects that compare equal might have different :attr:`start`,
1113 :attr:`stop` and :attr:`step` attributes, for example ``range(0) ==
1114 range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.)
1115
Georg Brandl2a39b712010-12-28 09:16:12 +00001116 Ranges containing absolute values larger than :data:`sys.maxsize` are permitted
Nick Coghlan37ee8502010-12-03 14:26:13 +00001117 but some features (such as :func:`len`) will raise :exc:`OverflowError`.
1118
Mark Dickinson3e124ae2009-09-22 21:47:24 +00001119 .. versionchanged:: 3.2
Georg Brandl38e117d2010-12-03 17:19:27 +00001120 Implement the Sequence ABC.
1121 Support slicing and negative indices.
Nick Coghlan37ee8502010-12-03 14:26:13 +00001122 Test integers for membership in constant time instead of iterating
Georg Brandl67b21b72010-08-17 15:07:14 +00001123 through all items.
Mark Dickinson3e124ae2009-09-22 21:47:24 +00001124
Mark Dickinson36645682011-10-23 19:53:01 +01001125 .. versionchanged:: 3.3
1126 Define '==' and '!=' to compare range objects based on the
1127 sequence of values they define (instead of comparing based on
1128 object identity).
1129
Benjamin Peterson878ce382011-11-05 15:17:52 -04001130 .. versionadded:: 3.3
1131 The :attr:`start`, :attr:`stop` and :attr:`step` attributes.
1132
Georg Brandl116aa622007-08-15 14:28:22 +00001133
1134.. function:: repr(object)
1135
Georg Brandl68ee3a52008-03-25 07:21:32 +00001136 Return a string containing a printable representation of an object. For many
1137 types, this function makes an attempt to return a string that would yield an
1138 object with the same value when passed to :func:`eval`, otherwise the
1139 representation is a string enclosed in angle brackets that contains the name
1140 of the type of the object together with additional information often
1141 including the name and address of the object. A class can control what this
1142 function returns for its instances by defining a :meth:`__repr__` method.
Georg Brandl116aa622007-08-15 14:28:22 +00001143
1144
1145.. function:: reversed(seq)
1146
Christian Heimes7f044312008-01-06 17:05:40 +00001147 Return a reverse :term:`iterator`. *seq* must be an object which has
1148 a :meth:`__reversed__` method or supports the sequence protocol (the
1149 :meth:`__len__` method and the :meth:`__getitem__` method with integer
1150 arguments starting at ``0``).
Georg Brandl116aa622007-08-15 14:28:22 +00001151
Georg Brandl116aa622007-08-15 14:28:22 +00001152
1153.. function:: round(x[, n])
1154
1155 Return the floating point value *x* rounded to *n* digits after the decimal
Georg Brandl809ddaa2008-07-01 20:39:59 +00001156 point. If *n* is omitted, it defaults to zero. Delegates to
1157 ``x.__round__(n)``.
1158
1159 For the built-in types supporting :func:`round`, values are rounded to the
Christian Heimes072c0f12008-01-03 23:01:04 +00001160 closest multiple of 10 to the power minus *n*; if two multiples are equally
1161 close, rounding is done toward the even choice (so, for example, both
Georg Brandl809ddaa2008-07-01 20:39:59 +00001162 ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is ``2``).
1163 The return value is an integer if called with one argument, otherwise of the
1164 same type as *x*.
Christian Heimes072c0f12008-01-03 23:01:04 +00001165
Mark Dickinsonc4fbcdc2010-07-30 13:13:02 +00001166 .. note::
1167
1168 The behavior of :func:`round` for floats can be surprising: for example,
1169 ``round(2.675, 2)`` gives ``2.67`` instead of the expected ``2.68``.
1170 This is not a bug: it's a result of the fact that most decimal fractions
1171 can't be represented exactly as a float. See :ref:`tut-fp-issues` for
1172 more information.
Georg Brandl116aa622007-08-15 14:28:22 +00001173
Éric Araujo9edd9f02011-09-01 23:08:55 +02001174
1175.. _func-set:
Georg Brandl116aa622007-08-15 14:28:22 +00001176.. function:: set([iterable])
1177 :noindex:
1178
Benjamin Peterson97dd9872009-12-13 01:23:39 +00001179 Return a new set, optionally with elements taken from *iterable*.
Georg Brandl116aa622007-08-15 14:28:22 +00001180 The set type is described in :ref:`types-set`.
1181
Georg Brandl116aa622007-08-15 14:28:22 +00001182
1183.. function:: setattr(object, name, value)
1184
1185 This is the counterpart of :func:`getattr`. The arguments are an object, a
1186 string and an arbitrary value. The string may name an existing attribute or a
1187 new attribute. The function assigns the value to the attribute, provided the
1188 object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to
1189 ``x.foobar = 123``.
1190
1191
1192.. function:: slice([start,] stop[, step])
1193
1194 .. index:: single: Numerical Python
1195
Christian Heimesd8654cf2007-12-02 15:22:16 +00001196 Return a :term:`slice` object representing the set of indices specified by
Georg Brandl116aa622007-08-15 14:28:22 +00001197 ``range(start, stop, step)``. The *start* and *step* arguments default to
1198 ``None``. Slice objects have read-only data attributes :attr:`start`,
1199 :attr:`stop` and :attr:`step` which merely return the argument values (or their
1200 default). They have no other explicit functionality; however they are used by
1201 Numerical Python and other third party extensions. Slice objects are also
1202 generated when extended indexing syntax is used. For example:
Raymond Hettingercdf8ba32009-02-19 04:45:07 +00001203 ``a[start:stop:step]`` or ``a[start:stop, i]``. See :func:`itertools.islice`
1204 for an alternate version that returns an iterator.
Georg Brandl116aa622007-08-15 14:28:22 +00001205
1206
Georg Brandl036490d2009-05-17 13:00:36 +00001207.. function:: sorted(iterable[, key][, reverse])
Georg Brandl116aa622007-08-15 14:28:22 +00001208
1209 Return a new sorted list from the items in *iterable*.
1210
Raymond Hettinger51b9c242008-02-14 13:52:24 +00001211 Has two optional arguments which must be specified as keyword arguments.
Georg Brandl116aa622007-08-15 14:28:22 +00001212
Georg Brandl116aa622007-08-15 14:28:22 +00001213 *key* specifies a function of one argument that is used to extract a comparison
Georg Brandl1f70cdf2010-03-21 09:04:24 +00001214 key from each list element: ``key=str.lower``. The default value is ``None``
1215 (compare the elements directly).
Georg Brandl116aa622007-08-15 14:28:22 +00001216
1217 *reverse* is a boolean value. If set to ``True``, then the list elements are
1218 sorted as if each comparison were reversed.
1219
Benjamin Peterson7ac98ae2010-08-17 17:52:02 +00001220 Use :func:`functools.cmp_to_key` to convert an old-style *cmp* function to a
1221 *key* function.
Georg Brandl116aa622007-08-15 14:28:22 +00001222
Raymond Hettinger46fca072010-04-02 00:25:45 +00001223 For sorting examples and a brief sorting tutorial, see `Sorting HowTo
1224 <http://wiki.python.org/moin/HowTo/Sorting/>`_\.
1225
Georg Brandl116aa622007-08-15 14:28:22 +00001226.. function:: staticmethod(function)
1227
1228 Return a static method for *function*.
1229
1230 A static method does not receive an implicit first argument. To declare a static
1231 method, use this idiom::
1232
1233 class C:
1234 @staticmethod
1235 def f(arg1, arg2, ...): ...
1236
Christian Heimesd8654cf2007-12-02 15:22:16 +00001237 The ``@staticmethod`` form is a function :term:`decorator` -- see the
1238 description of function definitions in :ref:`function` for details.
Georg Brandl116aa622007-08-15 14:28:22 +00001239
1240 It can be called either on the class (such as ``C.f()``) or on an instance (such
1241 as ``C().f()``). The instance is ignored except for its class.
1242
Raymond Hettinger90289282011-06-01 16:17:23 -07001243 Static methods in Python are similar to those found in Java or C++. Also see
1244 :func:`classmethod` for a variant that is useful for creating alternate class
1245 constructors.
Georg Brandl116aa622007-08-15 14:28:22 +00001246
1247 For more information on static methods, consult the documentation on the
1248 standard type hierarchy in :ref:`types`.
1249
Georg Brandl116aa622007-08-15 14:28:22 +00001250
1251.. function:: str([object[, encoding[, errors]]])
1252
1253 Return a string version of an object, using one of the following modes:
Georg Brandl48310cd2009-01-03 21:18:54 +00001254
Georg Brandl116aa622007-08-15 14:28:22 +00001255 If *encoding* and/or *errors* are given, :func:`str` will decode the
1256 *object* which can either be a byte string or a character buffer using
1257 the codec for *encoding*. The *encoding* parameter is a string giving
1258 the name of an encoding; if the encoding is not known, :exc:`LookupError`
1259 is raised. Error handling is done according to *errors*; this specifies the
1260 treatment of characters which are invalid in the input encoding. If
1261 *errors* is ``'strict'`` (the default), a :exc:`ValueError` is raised on
1262 errors, while a value of ``'ignore'`` causes errors to be silently ignored,
1263 and a value of ``'replace'`` causes the official Unicode replacement character,
1264 U+FFFD, to be used to replace input characters which cannot be decoded.
Georg Brandl48310cd2009-01-03 21:18:54 +00001265 See also the :mod:`codecs` module.
Georg Brandl116aa622007-08-15 14:28:22 +00001266
1267 When only *object* is given, this returns its nicely printable representation.
1268 For strings, this is the string itself. The difference with ``repr(object)``
1269 is that ``str(object)`` does not always attempt to return a string that is
1270 acceptable to :func:`eval`; its goal is to return a printable string.
1271 With no arguments, this returns the empty string.
1272
1273 Objects can specify what ``str(object)`` returns by defining a :meth:`__str__`
1274 special method.
1275
1276 For more information on strings see :ref:`typesseq` which describes sequence
1277 functionality (strings are sequences), and also the string-specific methods
Georg Brandl4b491312007-08-31 09:22:56 +00001278 described in the :ref:`string-methods` section. To output formatted strings,
1279 see the :ref:`string-formatting` section. In addition see the
1280 :ref:`stringservices` section.
Georg Brandl116aa622007-08-15 14:28:22 +00001281
1282
1283.. function:: sum(iterable[, start])
1284
1285 Sums *start* and the items of an *iterable* from left to right and returns the
1286 total. *start* defaults to ``0``. The *iterable*'s items are normally numbers,
Raymond Hettingerb3737992010-10-31 21:23:24 +00001287 and the start value is not allowed to be a string.
Georg Brandl116aa622007-08-15 14:28:22 +00001288
Éric Araujo8f9626b2010-11-06 06:30:16 +00001289 For some use cases, there are good alternatives to :func:`sum`.
Raymond Hettingerb3737992010-10-31 21:23:24 +00001290 The preferred, fast way to concatenate a sequence of strings is by calling
1291 ``''.join(sequence)``. To add floating point values with extended precision,
1292 see :func:`math.fsum`\. To concatenate a series of iterables, consider using
1293 :func:`itertools.chain`.
Georg Brandl116aa622007-08-15 14:28:22 +00001294
Mark Summerfield1041f742008-02-26 13:27:00 +00001295.. function:: super([type[, object-or-type]])
Georg Brandl116aa622007-08-15 14:28:22 +00001296
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001297 Return a proxy object that delegates method calls to a parent or sibling
1298 class of *type*. This is useful for accessing inherited methods that have
1299 been overridden in a class. The search order is same as that used by
1300 :func:`getattr` except that the *type* itself is skipped.
1301
Raymond Hettinger0a68b012009-02-25 00:58:47 +00001302 The :attr:`__mro__` attribute of the *type* lists the method resolution
1303 search order used by both :func:`getattr` and :func:`super`. The attribute
1304 is dynamic and can change whenever the inheritance hierarchy is updated.
Benjamin Peterson3e4f0552008-09-02 00:31:15 +00001305
Raymond Hettinger79d04342009-02-25 00:32:51 +00001306 If the second argument is omitted, the super object returned is unbound. If
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001307 the second argument is an object, ``isinstance(obj, type)`` must be true. If
Benjamin Petersond75fcb42009-02-19 04:22:03 +00001308 the second argument is a type, ``issubclass(type2, type)`` must be true (this
1309 is useful for classmethods).
Georg Brandl116aa622007-08-15 14:28:22 +00001310
Raymond Hettinger0a68b012009-02-25 00:58:47 +00001311 There are two typical use cases for *super*. In a class hierarchy with
1312 single inheritance, *super* can be used to refer to parent classes without
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001313 naming them explicitly, thus making the code more maintainable. This use
Raymond Hettinger0a68b012009-02-25 00:58:47 +00001314 closely parallels the use of *super* in other programming languages.
Georg Brandl48310cd2009-01-03 21:18:54 +00001315
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001316 The second use case is to support cooperative multiple inheritance in a
Georg Brandl48310cd2009-01-03 21:18:54 +00001317 dynamic execution environment. This use case is unique to Python and is
1318 not found in statically compiled languages or languages that only support
Raymond Hettingerd1258452009-02-26 00:27:18 +00001319 single inheritance. This makes it possible to implement "diamond diagrams"
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001320 where multiple base classes implement the same method. Good design dictates
1321 that this method have the same calling signature in every case (because the
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001322 order of calls is determined at runtime, because that order adapts
1323 to changes in the class hierarchy, and because that order can include
1324 sibling classes that are unknown prior to runtime).
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001325
1326 For both use cases, a typical superclass call looks like this::
Georg Brandl116aa622007-08-15 14:28:22 +00001327
1328 class C(B):
Mark Summerfield1041f742008-02-26 13:27:00 +00001329 def method(self, arg):
Georg Brandl036490d2009-05-17 13:00:36 +00001330 super().method(arg) # This does the same thing as:
1331 # super(C, self).method(arg)
Georg Brandl116aa622007-08-15 14:28:22 +00001332
1333 Note that :func:`super` is implemented as part of the binding process for
Mark Summerfield1041f742008-02-26 13:27:00 +00001334 explicit dotted attribute lookups such as ``super().__getitem__(name)``.
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001335 It does so by implementing its own :meth:`__getattribute__` method for searching
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001336 classes in a predictable order that supports cooperative multiple inheritance.
Georg Brandl116aa622007-08-15 14:28:22 +00001337 Accordingly, :func:`super` is undefined for implicit lookups using statements or
Raymond Hettinger518d8da2008-12-06 11:44:00 +00001338 operators such as ``super()[name]``.
1339
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001340 Also note that, aside from the zero argument form, :func:`super` is not
1341 limited to use inside methods. The two argument form specifies the
1342 arguments exactly and makes the appropriate references. The zero
1343 argument form only works inside a class definition, as the compiler fills
1344 in the necessary details to correctly retrieve the class being defined,
1345 as well as accessing the current instance for ordinary methods.
Georg Brandl116aa622007-08-15 14:28:22 +00001346
Raymond Hettinger90289282011-06-01 16:17:23 -07001347 For practical suggestions on how to design cooperative classes using
1348 :func:`super`, see `guide to using super()
1349 <http://rhettinger.wordpress.com/2011/05/26/super-considered-super/>`_.
1350
Georg Brandl116aa622007-08-15 14:28:22 +00001351
1352.. function:: tuple([iterable])
1353
1354 Return a tuple whose items are the same and in the same order as *iterable*'s
1355 items. *iterable* may be a sequence, a container that supports iteration, or an
1356 iterator object. If *iterable* is already a tuple, it is returned unchanged.
1357 For instance, ``tuple('abc')`` returns ``('a', 'b', 'c')`` and ``tuple([1, 2,
1358 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty
1359 tuple, ``()``.
1360
Georg Brandl48310cd2009-01-03 21:18:54 +00001361 :class:`tuple` is an immutable sequence type, as documented in :ref:`typesseq`.
Georg Brandl116aa622007-08-15 14:28:22 +00001362
1363
1364.. function:: type(object)
1365
1366 .. index:: object: type
1367
Georg Brandl85eb8c12007-08-31 16:33:38 +00001368 Return the type of an *object*. The return value is a type object and
1369 generally the same object as returned by ``object.__class__``.
Georg Brandl116aa622007-08-15 14:28:22 +00001370
Georg Brandl85eb8c12007-08-31 16:33:38 +00001371 The :func:`isinstance` built-in function is recommended for testing the type
1372 of an object, because it takes subclasses into account.
1373
1374 With three arguments, :func:`type` functions as a constructor as detailed
1375 below.
Georg Brandl116aa622007-08-15 14:28:22 +00001376
1377
1378.. function:: type(name, bases, dict)
1379 :noindex:
1380
1381 Return a new type object. This is essentially a dynamic form of the
Christian Heimesfe337bf2008-03-23 21:54:12 +00001382 :keyword:`class` statement. The *name* string is the class name and becomes the
1383 :attr:`__name__` attribute; the *bases* tuple itemizes the base classes and
1384 becomes the :attr:`__bases__` attribute; and the *dict* dictionary is the
1385 namespace containing definitions for class body and becomes the :attr:`__dict__`
1386 attribute. For example, the following two statements create identical
1387 :class:`type` objects:
Georg Brandl116aa622007-08-15 14:28:22 +00001388
Éric Araujo28053fb2010-11-22 03:09:19 +00001389 >>> class X:
Georg Brandl116aa622007-08-15 14:28:22 +00001390 ... a = 1
Georg Brandl48310cd2009-01-03 21:18:54 +00001391 ...
Georg Brandl116aa622007-08-15 14:28:22 +00001392 >>> X = type('X', (object,), dict(a=1))
1393
Georg Brandl116aa622007-08-15 14:28:22 +00001394
1395.. function:: vars([object])
1396
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +00001397 Without an argument, act like :func:`locals`.
1398
1399 With a module, class or class instance object as argument (or anything else that
1400 has a :attr:`__dict__` attribute), return that attribute.
Georg Brandl116aa622007-08-15 14:28:22 +00001401
Georg Brandle720c0a2009-04-27 16:20:50 +00001402 .. note::
Benjamin Petersond23f8222009-04-05 19:13:16 +00001403 The returned dictionary should not be modified:
1404 the effects on the corresponding symbol table are undefined. [#]_
Georg Brandl116aa622007-08-15 14:28:22 +00001405
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001406.. function:: zip(*iterables)
Georg Brandl116aa622007-08-15 14:28:22 +00001407
Georg Brandl48310cd2009-01-03 21:18:54 +00001408 Make an iterator that aggregates elements from each of the iterables.
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001409
1410 Returns an iterator of tuples, where the *i*-th tuple contains
Georg Brandl952aea22007-09-04 17:50:40 +00001411 the *i*-th element from each of the argument sequences or iterables. The
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001412 iterator stops when the shortest input iterable is exhausted. With a single
Georg Brandl48310cd2009-01-03 21:18:54 +00001413 iterable argument, it returns an iterator of 1-tuples. With no arguments,
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001414 it returns an empty iterator. Equivalent to::
1415
Raymond Hettinger2f08df32010-10-10 05:54:39 +00001416 def zip(*iterables):
1417 # zip('ABCD', 'xy') --> Ax By
1418 sentinel = object()
Raymond Hettinger6f45d182011-10-30 15:06:14 -07001419 iterators = [iter(it) for it in iterables]
1420 while iterators:
Raymond Hettinger2f08df32010-10-10 05:54:39 +00001421 result = []
Raymond Hettinger6f45d182011-10-30 15:06:14 -07001422 for it in iterators:
Raymond Hettinger2f08df32010-10-10 05:54:39 +00001423 elem = next(it, sentinel)
1424 if elem is sentinel:
1425 return
1426 result.append(elem)
1427 yield tuple(result)
Georg Brandl116aa622007-08-15 14:28:22 +00001428
Christian Heimes1af737c2008-01-23 08:24:23 +00001429 The left-to-right evaluation order of the iterables is guaranteed. This
1430 makes possible an idiom for clustering a data series into n-length groups
1431 using ``zip(*[iter(s)]*n)``.
1432
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001433 :func:`zip` should only be used with unequal length inputs when you don't
1434 care about trailing, unmatched values from the longer iterables. If those
1435 values are important, use :func:`itertools.zip_longest` instead.
Georg Brandl116aa622007-08-15 14:28:22 +00001436
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001437 :func:`zip` in conjunction with the ``*`` operator can be used to unzip a
1438 list::
1439
1440 >>> x = [1, 2, 3]
1441 >>> y = [4, 5, 6]
1442 >>> zipped = zip(x, y)
Georg Brandl17fe3642008-12-06 14:28:56 +00001443 >>> list(zipped)
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001444 [(1, 4), (2, 5), (3, 6)]
Georg Brandl17fe3642008-12-06 14:28:56 +00001445 >>> x2, y2 = zip(*zip(x, y))
Benjamin Petersonfa0d7032009-06-01 22:42:33 +00001446 >>> x == list(x2) and y == list(y2)
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001447 True
1448
Georg Brandl2ee470f2008-07-16 12:55:28 +00001449
Brett Cannoncb4996a2012-08-06 16:34:44 -04001450.. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0)
Georg Brandl48367812008-12-05 15:55:41 +00001451
1452 .. index::
1453 statement: import
1454 module: imp
1455
1456 .. note::
1457
1458 This is an advanced function that is not needed in everyday Python
Éric Araujoe801aa22011-07-29 17:50:58 +02001459 programming, unlike :func:`importlib.import_module`.
Georg Brandl48367812008-12-05 15:55:41 +00001460
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001461 This function is invoked by the :keyword:`import` statement. It can be
1462 replaced (by importing the :mod:`builtins` module and assigning to
1463 ``builtins.__import__``) in order to change semantics of the
1464 :keyword:`import` statement, but nowadays it is usually simpler to use import
Brett Cannon2a082ad2012-04-14 21:58:33 -04001465 hooks (see :pep:`302`) to attain the same goals. Direct use of
1466 :func:`__import__` is entirely discouraged in favor of
1467 :func:`importlib.import_module`.
Georg Brandl48367812008-12-05 15:55:41 +00001468
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001469 The function imports the module *name*, potentially using the given *globals*
1470 and *locals* to determine how to interpret the name in a package context.
1471 The *fromlist* gives the names of objects or submodules that should be
1472 imported from the module given by *name*. The standard implementation does
1473 not use its *locals* argument at all, and uses its *globals* only to
1474 determine the package context of the :keyword:`import` statement.
1475
Brett Cannon2b9fd472009-03-15 02:18:41 +00001476 *level* specifies whether to use absolute or relative imports. ``0`` (the
1477 default) means only perform absolute imports. Positive values for
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001478 *level* indicate the number of parent directories to search relative to the
Brett Cannon2a082ad2012-04-14 21:58:33 -04001479 directory of the module calling :func:`__import__` (see :pep:`328` for the
1480 details).
Georg Brandl48367812008-12-05 15:55:41 +00001481
1482 When the *name* variable is of the form ``package.module``, normally, the
1483 top-level package (the name up till the first dot) is returned, *not* the
1484 module named by *name*. However, when a non-empty *fromlist* argument is
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001485 given, the module named by *name* is returned.
Georg Brandl48367812008-12-05 15:55:41 +00001486
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001487 For example, the statement ``import spam`` results in bytecode resembling the
1488 following code::
Georg Brandl48310cd2009-01-03 21:18:54 +00001489
Brett Cannon2b9fd472009-03-15 02:18:41 +00001490 spam = __import__('spam', globals(), locals(), [], 0)
Georg Brandl48367812008-12-05 15:55:41 +00001491
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001492 The statement ``import spam.ham`` results in this call::
Georg Brandl48367812008-12-05 15:55:41 +00001493
Brett Cannon2b9fd472009-03-15 02:18:41 +00001494 spam = __import__('spam.ham', globals(), locals(), [], 0)
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001495
1496 Note how :func:`__import__` returns the toplevel module here because this is
1497 the object that is bound to a name by the :keyword:`import` statement.
1498
1499 On the other hand, the statement ``from spam.ham import eggs, sausage as
1500 saus`` results in ::
1501
Brett Cannon2b9fd472009-03-15 02:18:41 +00001502 _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001503 eggs = _temp.eggs
1504 saus = _temp.sausage
1505
1506 Here, the ``spam.ham`` module is returned from :func:`__import__`. From this
1507 object, the names to import are retrieved and assigned to their respective
1508 names.
1509
1510 If you simply want to import a module (potentially within a package) by name,
Éric Araujoe801aa22011-07-29 17:50:58 +02001511 use :func:`importlib.import_module`.
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001512
Brett Cannon73df3642012-07-30 18:35:17 -04001513 .. versionchanged:: 3.3
Brett Cannon222d4732012-08-05 20:49:53 -04001514 Negative values for *level* are no longer supported (which also changes
1515 the default value to 0).
Brett Cannon73df3642012-07-30 18:35:17 -04001516
Georg Brandl48367812008-12-05 15:55:41 +00001517
Georg Brandl116aa622007-08-15 14:28:22 +00001518.. rubric:: Footnotes
1519
Georg Brandl47f27a32009-03-31 16:57:13 +00001520.. [#] Note that the parser only accepts the Unix-style end of line convention.
1521 If you are reading the code from a file, make sure to use newline conversion
1522 mode to convert Windows or Mac-style newlines.
Georg Brandl116aa622007-08-15 14:28:22 +00001523
1524.. [#] In the current implementation, local variable bindings cannot normally be
1525 affected this way, but variables retrieved from other scopes (such as modules)
1526 can be. This may change.