blob: eb41e72ddd37559b7542d0ab1ca8808ff1dfcb46 [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
Barry Warsaw36c1d1f2017-10-05 12:11:18 -040010=================== ================= ================== ================== ====================
11.. .. Built-in Functions .. ..
12=================== ================= ================== ================== ====================
13:func:`abs` :func:`delattr` :func:`hash` |func-memoryview|_ |func-set|_
14:func:`all` |func-dict|_ :func:`help` :func:`min` :func:`setattr`
15:func:`any` :func:`dir` :func:`hex` :func:`next` :func:`slice`
16:func:`ascii` :func:`divmod` :func:`id` :func:`object` :func:`sorted`
17:func:`bin` :func:`enumerate` :func:`input` :func:`oct` :func:`staticmethod`
18:func:`bool` :func:`eval` :func:`int` :func:`open` |func-str|_
19:func:`breakpoint` :func:`exec` :func:`isinstance` :func:`ord` :func:`sum`
20|func-bytearray|_ :func:`filter` :func:`issubclass` :func:`pow` :func:`super`
21|func-bytes|_ :func:`float` :func:`iter` :func:`print` |func-tuple|_
22:func:`callable` :func:`format` :func:`len` :func:`property` :func:`type`
23:func:`chr` |func-frozenset|_ |func-list|_ |func-range|_ :func:`vars`
24:func:`classmethod` :func:`getattr` :func:`locals` :func:`repr` :func:`zip`
25:func:`compile` :func:`globals` :func:`map` :func:`reversed` :func:`__import__`
Ezio Melotti17f9b3d2010-11-24 22:02:18 +000026:func:`complex` :func:`hasattr` :func:`max` :func:`round`
Barry Warsaw36c1d1f2017-10-05 12:11:18 -040027=================== ================= ================== ================== ====================
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()``
csabellac6db4812017-04-26 01:47:01 -040040.. |func-bytearray| replace:: ``bytearray()``
41.. |func-bytes| replace:: ``bytes()``
Éric Araujo9edd9f02011-09-01 23:08:55 +020042
Georg Brandl116aa622007-08-15 14:28:22 +000043.. function:: abs(x)
44
Georg Brandlba956ae2007-11-29 17:24:34 +000045 Return the absolute value of a number. The argument may be an
Georg Brandl116aa622007-08-15 14:28:22 +000046 integer or a floating point number. If the argument is a complex number, its
Windson yang3ae2e332018-07-06 07:09:53 +080047 magnitude is returned. If *x* defines :meth:`__abs__`,
48 ``abs(x)`` returns ``x.__abs__()``.
Georg Brandl116aa622007-08-15 14:28:22 +000049
50
51.. function:: all(iterable)
52
Serhiy Storchakafbc1c262013-11-29 12:17:13 +020053 Return ``True`` if all elements of the *iterable* are true (or if the iterable
Georg Brandl0192bff2009-04-27 16:49:41 +000054 is empty). Equivalent to::
Georg Brandl116aa622007-08-15 14:28:22 +000055
56 def all(iterable):
57 for element in iterable:
58 if not element:
59 return False
60 return True
61
Georg Brandl116aa622007-08-15 14:28:22 +000062
63.. function:: any(iterable)
64
Serhiy Storchakafbc1c262013-11-29 12:17:13 +020065 Return ``True`` if any element of the *iterable* is true. If the iterable
66 is empty, return ``False``. Equivalent to::
Georg Brandl116aa622007-08-15 14:28:22 +000067
68 def any(iterable):
69 for element in iterable:
70 if element:
71 return True
72 return False
73
Georg Brandl116aa622007-08-15 14:28:22 +000074
Georg Brandl559e5d72008-06-11 18:37:52 +000075.. function:: ascii(object)
76
77 As :func:`repr`, return a string containing a printable representation of an
78 object, but escape the non-ASCII characters in the string returned by
79 :func:`repr` using ``\x``, ``\u`` or ``\U`` escapes. This generates a string
80 similar to that returned by :func:`repr` in Python 2.
81
82
Georg Brandl116aa622007-08-15 14:28:22 +000083.. function:: bin(x)
84
Manvisha Kodali67ba4fa2017-07-06 22:30:58 +030085 Convert an integer number to a binary string prefixed with "0b". The result
86 is a valid Python expression. If *x* is not a Python :class:`int` object, it
87 has to define an :meth:`__index__` method that returns an integer. Some
88 examples:
89
90 >>> bin(3)
91 '0b11'
92 >>> bin(-10)
93 '-0b1010'
94
95 If prefix "0b" is desired or not, you can use either of the following ways.
96
97 >>> format(14, '#b'), format(14, 'b')
98 ('0b1110', '1110')
99 >>> f'{14:#b}', f'{14:b}'
100 ('0b1110', '1110')
101
Andrés Delfinobda9c3e2018-06-29 06:57:10 -0300102 See also :func:`format` for more information.
Georg Brandl116aa622007-08-15 14:28:22 +0000103
Georg Brandl116aa622007-08-15 14:28:22 +0000104
Georg Brandleb7e8f62014-10-06 13:54:36 +0200105.. class:: bool([x])
Georg Brandl116aa622007-08-15 14:28:22 +0000106
Georg Brandleb7e8f62014-10-06 13:54:36 +0200107 Return a Boolean value, i.e. one of ``True`` or ``False``. *x* is converted
108 using the standard :ref:`truth testing procedure <truth>`. If *x* is false
109 or omitted, this returns ``False``; otherwise it returns ``True``. The
110 :class:`bool` class is a subclass of :class:`int` (see :ref:`typesnumeric`).
111 It cannot be subclassed further. Its only instances are ``False`` and
Éric Araujo18ddf822011-09-01 23:10:36 +0200112 ``True`` (see :ref:`bltin-boolean-values`).
Georg Brandl116aa622007-08-15 14:28:22 +0000113
114 .. index:: pair: Boolean; type
115
Georg Brandl116aa622007-08-15 14:28:22 +0000116
Barry Warsaw36c1d1f2017-10-05 12:11:18 -0400117.. function:: breakpoint(*args, **kws)
118
119 This function drops you into the debugger at the call site. Specifically,
120 it calls :func:`sys.breakpointhook`, passing ``args`` and ``kws`` straight
121 through. By default, ``sys.breakpointhook()`` calls
122 :func:`pdb.set_trace()` expecting no arguments. In this case, it is
123 purely a convenience function so you don't have to explicitly import
124 :mod:`pdb` or type as much code to enter the debugger. However,
125 :func:`sys.breakpointhook` can be set to some other function and
126 :func:`breakpoint` will automatically call that, allowing you to drop into
127 the debugger of choice.
128
129 .. versionadded:: 3.7
130
Nick Coghlan83c0ae52012-08-21 17:42:52 +1000131.. _func-bytearray:
Georg Brandleb7e8f62014-10-06 13:54:36 +0200132.. class:: bytearray([source[, encoding[, errors]]])
csabellac6db4812017-04-26 01:47:01 -0400133 :noindex:
Georg Brandl85eb8c12007-08-31 16:33:38 +0000134
Georg Brandleb7e8f62014-10-06 13:54:36 +0200135 Return a new array of bytes. The :class:`bytearray` class is a mutable
Georg Brandl95414632007-11-22 11:00:28 +0000136 sequence of integers in the range 0 <= x < 256. It has most of the usual
137 methods of mutable sequences, described in :ref:`typesseq-mutable`, as well
Antoine Pitroub85b3af2010-11-20 19:36:05 +0000138 as most methods that the :class:`bytes` type has, see :ref:`bytes-methods`.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000139
Georg Brandl036490d2009-05-17 13:00:36 +0000140 The optional *source* parameter can be used to initialize the array in a few
Georg Brandl85eb8c12007-08-31 16:33:38 +0000141 different ways:
142
143 * If it is a *string*, you must also give the *encoding* (and optionally,
Georg Brandlf6945182008-02-01 11:56:49 +0000144 *errors*) parameters; :func:`bytearray` then converts the string to
Guido van Rossum98297ee2007-11-06 21:34:58 +0000145 bytes using :meth:`str.encode`.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000146
147 * If it is an *integer*, the array will have that size and will be
148 initialized with null bytes.
149
150 * If it is an object conforming to the *buffer* interface, a read-only buffer
151 of the object will be used to initialize the bytes array.
152
Guido van Rossum98297ee2007-11-06 21:34:58 +0000153 * If it is an *iterable*, it must be an iterable of integers in the range
154 ``0 <= x < 256``, which are used as the initial contents of the array.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000155
156 Without an argument, an array of size 0 is created.
157
Chris Jerdonek006d9072012-10-12 20:28:26 -0700158 See also :ref:`binaryseq` and :ref:`typebytearray`.
159
Georg Brandl85eb8c12007-08-31 16:33:38 +0000160
Nick Coghlan83c0ae52012-08-21 17:42:52 +1000161.. _func-bytes:
Georg Brandleb7e8f62014-10-06 13:54:36 +0200162.. class:: bytes([source[, encoding[, errors]]])
csabellac6db4812017-04-26 01:47:01 -0400163 :noindex:
Guido van Rossum98297ee2007-11-06 21:34:58 +0000164
165 Return a new "bytes" object, which is an immutable sequence of integers in
166 the range ``0 <= x < 256``. :class:`bytes` is an immutable version of
Georg Brandl95414632007-11-22 11:00:28 +0000167 :class:`bytearray` -- it has the same non-mutating methods and the same
168 indexing and slicing behavior.
Georg Brandl48310cd2009-01-03 21:18:54 +0000169
Georg Brandl476b3552009-04-29 06:37:12 +0000170 Accordingly, constructor arguments are interpreted as for :func:`bytearray`.
Guido van Rossum98297ee2007-11-06 21:34:58 +0000171
172 Bytes objects can also be created with literals, see :ref:`strings`.
173
Chris Jerdonek006d9072012-10-12 20:28:26 -0700174 See also :ref:`binaryseq`, :ref:`typebytes`, and :ref:`bytes-methods`.
175
Guido van Rossum98297ee2007-11-06 21:34:58 +0000176
Antoine Pitroue71362d2010-11-27 22:00:11 +0000177.. function:: callable(object)
178
179 Return :const:`True` if the *object* argument appears callable,
180 :const:`False` if not. If this returns true, it is still possible that a
181 call fails, but if it is false, calling *object* will never succeed.
182 Note that classes are callable (calling a class returns a new instance);
183 instances are callable if their class has a :meth:`__call__` method.
184
185 .. versionadded:: 3.2
186 This function was first removed in Python 3.0 and then brought back
187 in Python 3.2.
188
189
Georg Brandl116aa622007-08-15 14:28:22 +0000190.. function:: chr(i)
191
Georg Brandl3be472b2015-01-14 08:26:30 +0100192 Return the string representing a character whose Unicode code point is the
Nick Coghlaneed67192014-08-17 14:07:53 +1000193 integer *i*. For example, ``chr(97)`` returns the string ``'a'``, while
Terry Jan Reedy01a9a952016-03-23 13:36:52 -0400194 ``chr(8364)`` returns the string ``'€'``. This is the inverse of :func:`ord`.
Nick Coghlaneed67192014-08-17 14:07:53 +1000195
196 The valid range for the argument is from 0 through 1,114,111 (0x10FFFF in
197 base 16). :exc:`ValueError` will be raised if *i* is outside that range.
Alexander Belopolsky5d4dd3e2010-11-18 18:50:13 +0000198
Georg Brandl116aa622007-08-15 14:28:22 +0000199
Daisuke Miyakawa0e61e672017-10-12 23:39:43 +0900200.. decorator:: classmethod
Georg Brandl116aa622007-08-15 14:28:22 +0000201
Daisuke Miyakawa0e61e672017-10-12 23:39:43 +0900202 Transform a method into a class method.
Georg Brandl116aa622007-08-15 14:28:22 +0000203
204 A class method receives the class as implicit first argument, just like an
205 instance method receives the instance. To declare a class method, use this
206 idiom::
207
208 class C:
209 @classmethod
210 def f(cls, arg1, arg2, ...): ...
211
Christian Heimesd8654cf2007-12-02 15:22:16 +0000212 The ``@classmethod`` form is a function :term:`decorator` -- see the description
213 of function definitions in :ref:`function` for details.
Georg Brandl116aa622007-08-15 14:28:22 +0000214
215 It can be called either on the class (such as ``C.f()``) or on an instance (such
216 as ``C().f()``). The instance is ignored except for its class. If a class
217 method is called for a derived class, the derived class object is passed as the
218 implied first argument.
219
220 Class methods are different than C++ or Java static methods. If you want those,
221 see :func:`staticmethod` in this section.
222
223 For more information on class methods, consult the documentation on the standard
224 type hierarchy in :ref:`types`.
225
Georg Brandl116aa622007-08-15 14:28:22 +0000226
Georg Brandl8334fd92010-12-04 10:26:46 +0000227.. function:: compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1)
Georg Brandl116aa622007-08-15 14:28:22 +0000228
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000229 Compile the *source* into a code or AST object. Code objects can be executed
Benjamin Peterson933142a2013-12-06 20:12:39 -0500230 by :func:`exec` or :func:`eval`. *source* can either be a normal string, a
231 byte string, or an AST object. Refer to the :mod:`ast` module documentation
232 for information on how to work with AST objects.
Georg Brandl116aa622007-08-15 14:28:22 +0000233
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000234 The *filename* argument should give the file from which the code was read;
235 pass some recognizable value if it wasn't read from a file (``'<string>'`` is
236 commonly used).
237
238 The *mode* argument specifies what kind of code must be compiled; it can be
239 ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
240 consists of a single expression, or ``'single'`` if it consists of a single
241 interactive statement (in the latter case, expression statements that
R. David Murray66011262009-06-25 17:37:57 +0000242 evaluate to something other than ``None`` will be printed).
Georg Brandl116aa622007-08-15 14:28:22 +0000243
Andrés Delfino33aefad2018-07-11 06:44:06 -0300244 The optional arguments *flags* and *dont_inherit* control which :ref:`future
245 statements <future>` affect the compilation of *source*. If neither
Georg Brandle06de8b2008-05-05 21:42:51 +0000246 is present (or both are zero) the code is compiled with those future
Georg Brandle4196d32014-10-31 09:41:46 +0100247 statements that are in effect in the code that is calling :func:`compile`. If the
Georg Brandle06de8b2008-05-05 21:42:51 +0000248 *flags* argument is given and *dont_inherit* is not (or is zero) then the
Georg Brandl116aa622007-08-15 14:28:22 +0000249 future statements specified by the *flags* argument are used in addition to
250 those that would be used anyway. If *dont_inherit* is a non-zero integer then
Georg Brandle06de8b2008-05-05 21:42:51 +0000251 the *flags* argument is it -- the future statements in effect around the call
252 to compile are ignored.
Georg Brandl116aa622007-08-15 14:28:22 +0000253
Christian Heimesfaf2f632008-01-06 16:59:19 +0000254 Future statements are specified by bits which can be bitwise ORed together to
Georg Brandl116aa622007-08-15 14:28:22 +0000255 specify multiple statements. The bitfield required to specify a given feature
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +0300256 can be found as the :attr:`~__future__._Feature.compiler_flag` attribute on
257 the :class:`~__future__._Feature` instance in the :mod:`__future__` module.
Georg Brandl116aa622007-08-15 14:28:22 +0000258
Georg Brandl8334fd92010-12-04 10:26:46 +0000259 The argument *optimize* specifies the optimization level of the compiler; the
260 default value of ``-1`` selects the optimization level of the interpreter as
261 given by :option:`-O` options. Explicit levels are ``0`` (no optimization;
262 ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)
263 or ``2`` (docstrings are removed too).
264
Christian Heimes7f044312008-01-06 17:05:40 +0000265 This function raises :exc:`SyntaxError` if the compiled source is invalid,
Berker Peksag0334c3c2016-02-21 22:00:12 +0200266 and :exc:`ValueError` if the source contains null bytes.
Christian Heimes7f044312008-01-06 17:05:40 +0000267
Georg Brandle4196d32014-10-31 09:41:46 +0100268 If you want to parse Python code into its AST representation, see
269 :func:`ast.parse`.
270
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000271 .. note::
272
Benjamin Peterson20211002009-11-25 18:34:42 +0000273 When compiling a string with multi-line code in ``'single'`` or
Benjamin Petersonaeaa5922009-11-13 00:17:59 +0000274 ``'eval'`` mode, input must be terminated by at least one newline
275 character. This is to facilitate detection of incomplete and complete
276 statements in the :mod:`code` module.
277
Brett Cannonf7a6ff62018-03-09 13:13:32 -0800278 .. warning::
279
280 It is possible to crash the Python interpreter with a
281 sufficiently large/complex string when compiling to an AST
282 object due to stack depth limitations in Python's AST compiler.
283
Benjamin Petersonaeaa5922009-11-13 00:17:59 +0000284 .. versionchanged:: 3.2
285 Allowed use of Windows and Mac newlines. Also input in ``'exec'`` mode
Georg Brandl8334fd92010-12-04 10:26:46 +0000286 does not have to end in a newline anymore. Added the *optimize* parameter.
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000287
Berker Peksag0334c3c2016-02-21 22:00:12 +0200288 .. versionchanged:: 3.5
289 Previously, :exc:`TypeError` was raised when null bytes were encountered
290 in *source*.
291
Georg Brandl116aa622007-08-15 14:28:22 +0000292
Georg Brandleb7e8f62014-10-06 13:54:36 +0200293.. class:: complex([real[, imag]])
Georg Brandl116aa622007-08-15 14:28:22 +0000294
Terry Jan Reedy43cba212015-05-23 16:16:28 -0400295 Return a complex number with the value *real* + *imag*\*1j or convert a string
Georg Brandleb7e8f62014-10-06 13:54:36 +0200296 or number to a complex number. If the first parameter is a string, it will
297 be interpreted as a complex number and the function must be called without a
298 second parameter. The second parameter can never be a string. Each argument
299 may be any numeric type (including complex). If *imag* is omitted, it
300 defaults to zero and the constructor serves as a numeric conversion like
301 :class:`int` and :class:`float`. If both arguments are omitted, returns
302 ``0j``.
Georg Brandl116aa622007-08-15 14:28:22 +0000303
Mark Dickinson328dd0d2012-03-10 16:09:35 +0000304 .. note::
305
306 When converting from a string, the string must not contain whitespace
307 around the central ``+`` or ``-`` operator. For example,
308 ``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` raises
309 :exc:`ValueError`.
310
Georg Brandl116aa622007-08-15 14:28:22 +0000311 The complex type is described in :ref:`typesnumeric`.
312
Brett Cannona721aba2016-09-09 14:57:09 -0700313 .. versionchanged:: 3.6
314 Grouping digits with underscores as in code literals is allowed.
315
Georg Brandl116aa622007-08-15 14:28:22 +0000316
317.. function:: delattr(object, name)
318
319 This is a relative of :func:`setattr`. The arguments are an object and a
320 string. The string must be the name of one of the object's attributes. The
321 function deletes the named attribute, provided the object allows it. For
322 example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
323
324
Éric Araujo9edd9f02011-09-01 23:08:55 +0200325.. _func-dict:
Georg Brandleb7e8f62014-10-06 13:54:36 +0200326.. class:: dict(**kwarg)
327 dict(mapping, **kwarg)
328 dict(iterable, **kwarg)
Georg Brandl116aa622007-08-15 14:28:22 +0000329 :noindex:
330
Chris Jerdonekf3413172012-10-13 03:22:33 -0700331 Create a new dictionary. The :class:`dict` object is the dictionary class.
Georg Brandleb7e8f62014-10-06 13:54:36 +0200332 See :class:`dict` and :ref:`typesmapping` for documentation about this class.
Georg Brandl116aa622007-08-15 14:28:22 +0000333
Chris Jerdonekf3413172012-10-13 03:22:33 -0700334 For other containers see the built-in :class:`list`, :class:`set`, and
335 :class:`tuple` classes, as well as the :mod:`collections` module.
Georg Brandl116aa622007-08-15 14:28:22 +0000336
337
338.. function:: dir([object])
339
340 Without arguments, return the list of names in the current local scope. With an
341 argument, attempt to return a list of valid attributes for that object.
342
343 If the object has a method named :meth:`__dir__`, this method will be called and
344 must return the list of attributes. This allows objects that implement a custom
345 :func:`__getattr__` or :func:`__getattribute__` function to customize the way
346 :func:`dir` reports their attributes.
347
348 If the object does not provide :meth:`__dir__`, the function tries its best to
Martin Panterbae5d812016-06-18 03:57:31 +0000349 gather information from the object's :attr:`~object.__dict__` attribute, if defined, and
Georg Brandl116aa622007-08-15 14:28:22 +0000350 from its type object. The resulting list is not necessarily complete, and may
351 be inaccurate when the object has a custom :func:`__getattr__`.
352
353 The default :func:`dir` mechanism behaves differently with different types of
354 objects, as it attempts to produce the most relevant, rather than complete,
355 information:
356
357 * If the object is a module object, the list contains the names of the module's
358 attributes.
359
360 * If the object is a type or class object, the list contains the names of its
361 attributes, and recursively of the attributes of its bases.
362
363 * Otherwise, the list contains the object's attributes' names, the names of its
364 class's attributes, and recursively of the attributes of its class's base
365 classes.
366
Christian Heimesfe337bf2008-03-23 21:54:12 +0000367 The resulting list is sorted alphabetically. For example:
368
369 >>> import struct
Marco Buttue65fcde2017-04-27 14:23:34 +0200370 >>> dir() # show the names in the module namespace # doctest: +SKIP
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300371 ['__builtins__', '__name__', 'struct']
372 >>> dir(struct) # show the names in the struct module # doctest: +SKIP
373 ['Struct', '__all__', '__builtins__', '__cached__', '__doc__', '__file__',
374 '__initializing__', '__loader__', '__name__', '__package__',
375 '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
Christian Heimesfe337bf2008-03-23 21:54:12 +0000376 'unpack', 'unpack_from']
Ezio Melottiaf8838f2013-03-11 09:30:21 +0200377 >>> class Shape:
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300378 ... def __dir__(self):
379 ... return ['area', 'perimeter', 'location']
Raymond Hettinger90289282011-06-01 16:17:23 -0700380 >>> s = Shape()
381 >>> dir(s)
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300382 ['area', 'location', 'perimeter']
Georg Brandl116aa622007-08-15 14:28:22 +0000383
384 .. note::
385
386 Because :func:`dir` is supplied primarily as a convenience for use at an
Georg Brandl036490d2009-05-17 13:00:36 +0000387 interactive prompt, it tries to supply an interesting set of names more
388 than it tries to supply a rigorously or consistently defined set of names,
389 and its detailed behavior may change across releases. For example,
390 metaclass attributes are not in the result list when the argument is a
391 class.
Georg Brandl116aa622007-08-15 14:28:22 +0000392
393
394.. function:: divmod(a, b)
395
396 Take two (non complex) numbers as arguments and return a pair of numbers
Georg Brandl036490d2009-05-17 13:00:36 +0000397 consisting of their quotient and remainder when using integer division. With
398 mixed operand types, the rules for binary arithmetic operators apply. For
399 integers, the result is the same as ``(a // b, a % b)``. For floating point
400 numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a /
401 b)`` but may be 1 less than that. In any case ``q * b + a % b`` is very
402 close to *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0
403 <= abs(a % b) < abs(b)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000404
Georg Brandl116aa622007-08-15 14:28:22 +0000405
Georg Brandl036490d2009-05-17 13:00:36 +0000406.. function:: enumerate(iterable, start=0)
Georg Brandl116aa622007-08-15 14:28:22 +0000407
Georg Brandld11ae5d2008-05-16 13:27:32 +0000408 Return an enumerate object. *iterable* must be a sequence, an
Ezio Melotti7fa82222012-10-12 13:42:08 +0300409 :term:`iterator`, or some other object which supports iteration.
410 The :meth:`~iterator.__next__` method of the iterator returned by
411 :func:`enumerate` returns a tuple containing a count (from *start* which
412 defaults to 0) and the values obtained from iterating over *iterable*.
Georg Brandl116aa622007-08-15 14:28:22 +0000413
Raymond Hettinger9d3df6d2011-06-25 15:00:14 +0200414 >>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
415 >>> list(enumerate(seasons))
416 [(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
417 >>> list(enumerate(seasons, start=1))
418 [(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]
Raymond Hettinger90289282011-06-01 16:17:23 -0700419
420 Equivalent to::
421
422 def enumerate(sequence, start=0):
423 n = start
424 for elem in sequence:
425 yield n, elem
426 n += 1
Georg Brandl116aa622007-08-15 14:28:22 +0000427
Georg Brandl116aa622007-08-15 14:28:22 +0000428
Georg Brandl036490d2009-05-17 13:00:36 +0000429.. function:: eval(expression, globals=None, locals=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000430
431 The arguments are a string and optional globals and locals. If provided,
432 *globals* must be a dictionary. If provided, *locals* can be any mapping
433 object.
434
Georg Brandl116aa622007-08-15 14:28:22 +0000435 The *expression* argument is parsed and evaluated as a Python expression
436 (technically speaking, a condition list) using the *globals* and *locals*
Georg Brandl9afde1c2007-11-01 20:32:30 +0000437 dictionaries as global and local namespace. If the *globals* dictionary is
Berker Peksag225b0552018-08-19 13:25:33 +0300438 present and does not contain a value for the key ``__builtins__``, a
439 reference to the dictionary of the built-in module :mod:`builtins` is
440 inserted under that key before *expression* is parsed.
441 This means that *expression* normally has full
Georg Brandl1a3284e2007-12-02 09:40:06 +0000442 access to the standard :mod:`builtins` module and restricted environments are
Georg Brandl116aa622007-08-15 14:28:22 +0000443 propagated. If the *locals* dictionary is omitted it defaults to the *globals*
444 dictionary. If both dictionaries are omitted, the expression is executed in the
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000445 environment where :func:`eval` is called. The return value is the result of
Christian Heimesfe337bf2008-03-23 21:54:12 +0000446 the evaluated expression. Syntax errors are reported as exceptions. Example:
Georg Brandl116aa622007-08-15 14:28:22 +0000447
448 >>> x = 1
Georg Brandl6911e3c2007-09-04 07:15:32 +0000449 >>> eval('x+1')
Georg Brandl116aa622007-08-15 14:28:22 +0000450 2
451
Benjamin Peterson3e4f0552008-09-02 00:31:15 +0000452 This function can also be used to execute arbitrary code objects (such as
453 those created by :func:`compile`). In this case pass a code object instead
454 of a string. If the code object has been compiled with ``'exec'`` as the
Georg Brandl1f70cdf2010-03-21 09:04:24 +0000455 *mode* argument, :func:`eval`\'s return value will be ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000456
457 Hints: dynamic execution of statements is supported by the :func:`exec`
458 function. The :func:`globals` and :func:`locals` functions
459 returns the current global and local dictionary, respectively, which may be
460 useful to pass around for use by :func:`eval` or :func:`exec`.
461
Georg Brandl05bfcc52010-07-11 09:42:10 +0000462 See :func:`ast.literal_eval` for a function that can safely evaluate strings
463 with expressions containing only literals.
464
Berker Peksag3410af42014-07-04 15:06:45 +0300465.. index:: builtin: exec
Georg Brandl116aa622007-08-15 14:28:22 +0000466
467.. function:: exec(object[, globals[, locals]])
468
Benjamin Petersond3013ff2008-11-11 21:43:42 +0000469 This function supports dynamic execution of Python code. *object* must be
470 either a string or a code object. If it is a string, the string is parsed as
471 a suite of Python statements which is then executed (unless a syntax error
Georg Brandl47f27a32009-03-31 16:57:13 +0000472 occurs). [#]_ If it is a code object, it is simply executed. In all cases,
473 the code that's executed is expected to be valid as file input (see the
474 section "File input" in the Reference Manual). Be aware that the
475 :keyword:`return` and :keyword:`yield` statements may not be used outside of
476 function definitions even within the context of code passed to the
477 :func:`exec` function. The return value is ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000478
479 In all cases, if the optional parts are omitted, the code is executed in the
480 current scope. If only *globals* is provided, it must be a dictionary, which
481 will be used for both the global and the local variables. If *globals* and
482 *locals* are given, they are used for the global and local variables,
Terry Jan Reedy83efd6c2012-07-08 17:36:14 -0400483 respectively. If provided, *locals* can be any mapping object. Remember
484 that at module level, globals and locals are the same dictionary. If exec
485 gets two separate objects as *globals* and *locals*, the code will be
486 executed as if it were embedded in a class definition.
Georg Brandl116aa622007-08-15 14:28:22 +0000487
488 If the *globals* dictionary does not contain a value for the key
489 ``__builtins__``, a reference to the dictionary of the built-in module
Georg Brandl1a3284e2007-12-02 09:40:06 +0000490 :mod:`builtins` is inserted under that key. That way you can control what
Georg Brandl116aa622007-08-15 14:28:22 +0000491 builtins are available to the executed code by inserting your own
492 ``__builtins__`` dictionary into *globals* before passing it to :func:`exec`.
493
494 .. note::
495
496 The built-in functions :func:`globals` and :func:`locals` return the current
497 global and local dictionary, respectively, which may be useful to pass around
498 for use as the second and third argument to :func:`exec`.
499
Georg Brandle720c0a2009-04-27 16:20:50 +0000500 .. note::
Georg Brandl116aa622007-08-15 14:28:22 +0000501
502 The default *locals* act as described for function :func:`locals` below:
Georg Brandlf6945182008-02-01 11:56:49 +0000503 modifications to the default *locals* dictionary should not be attempted.
504 Pass an explicit *locals* dictionary if you need to see effects of the
505 code on *locals* after function :func:`exec` returns.
Georg Brandl116aa622007-08-15 14:28:22 +0000506
507
508.. function:: filter(function, iterable)
509
Georg Brandl952aea22007-09-04 17:50:40 +0000510 Construct an iterator from those elements of *iterable* for which *function*
511 returns true. *iterable* may be either a sequence, a container which
Georg Brandl9afde1c2007-11-01 20:32:30 +0000512 supports iteration, or an iterator. If *function* is ``None``, the identity
513 function is assumed, that is, all elements of *iterable* that are false are
514 removed.
Georg Brandl116aa622007-08-15 14:28:22 +0000515
Georg Brandl952aea22007-09-04 17:50:40 +0000516 Note that ``filter(function, iterable)`` is equivalent to the generator
517 expression ``(item for item in iterable if function(item))`` if function is
518 not ``None`` and ``(item for item in iterable if item)`` if function is
519 ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000520
Raymond Hettingercdf8ba32009-02-19 04:45:07 +0000521 See :func:`itertools.filterfalse` for the complementary function that returns
522 elements of *iterable* for which *function* returns false.
523
Georg Brandl116aa622007-08-15 14:28:22 +0000524
Georg Brandleb7e8f62014-10-06 13:54:36 +0200525.. class:: float([x])
Georg Brandl116aa622007-08-15 14:28:22 +0000526
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000527 .. index::
528 single: NaN
529 single: Infinity
Georg Brandl116aa622007-08-15 14:28:22 +0000530
Georg Brandleb7e8f62014-10-06 13:54:36 +0200531 Return a floating point number constructed from a number or string *x*.
Georg Brandl116aa622007-08-15 14:28:22 +0000532
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000533 If the argument is a string, it should contain a decimal number, optionally
534 preceded by a sign, and optionally embedded in whitespace. The optional
535 sign may be ``'+'`` or ``'-'``; a ``'+'`` sign has no effect on the value
536 produced. The argument may also be a string representing a NaN
537 (not-a-number), or a positive or negative infinity. More precisely, the
538 input must conform to the following grammar after leading and trailing
539 whitespace characters are removed:
Georg Brandl116aa622007-08-15 14:28:22 +0000540
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000541 .. productionlist::
542 sign: "+" | "-"
543 infinity: "Infinity" | "inf"
544 nan: "nan"
Georg Brandl46402372010-12-04 19:06:18 +0000545 numeric_value: `floatnumber` | `infinity` | `nan`
546 numeric_string: [`sign`] `numeric_value`
Mark Dickinson47c74ac2010-11-21 21:09:58 +0000547
548 Here ``floatnumber`` is the form of a Python floating-point literal,
549 described in :ref:`floating`. Case is not significant, so, for example,
550 "inf", "Inf", "INFINITY" and "iNfINity" are all acceptable spellings for
551 positive infinity.
552
553 Otherwise, if the argument is an integer or a floating point number, a
554 floating point number with the same value (within Python's floating point
555 precision) is returned. If the argument is outside the range of a Python
556 float, an :exc:`OverflowError` will be raised.
557
558 For a general Python object ``x``, ``float(x)`` delegates to
559 ``x.__float__()``.
560
561 If no argument is given, ``0.0`` is returned.
562
563 Examples::
564
565 >>> float('+1.23')
566 1.23
567 >>> float(' -12345\n')
568 -12345.0
569 >>> float('1e-003')
570 0.001
571 >>> float('+1E6')
572 1000000.0
573 >>> float('-Infinity')
574 -inf
Georg Brandl116aa622007-08-15 14:28:22 +0000575
576 The float type is described in :ref:`typesnumeric`.
577
Brett Cannona721aba2016-09-09 14:57:09 -0700578 .. versionchanged:: 3.6
579 Grouping digits with underscores as in code literals is allowed.
Chris Jerdonekbb4e9412012-11-28 01:38:40 -0800580
Éric Araujo9edd9f02011-09-01 23:08:55 +0200581
Brett Cannona721aba2016-09-09 14:57:09 -0700582.. index::
583 single: __format__
584 single: string; format() (built-in function)
585
Georg Brandl4b491312007-08-31 09:22:56 +0000586.. function:: format(value[, format_spec])
587
Georg Brandl5579ba92009-02-23 10:24:05 +0000588 Convert a *value* to a "formatted" representation, as controlled by
589 *format_spec*. The interpretation of *format_spec* will depend on the type
590 of the *value* argument, however there is a standard formatting syntax that
591 is used by most built-in types: :ref:`formatspec`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000592
Raymond Hettinger30439b22011-05-11 10:47:27 -0700593 The default *format_spec* is an empty string which usually gives the same
Chris Jerdonek5fae0e52012-11-20 17:45:51 -0800594 effect as calling :func:`str(value) <str>`.
Georg Brandl4b491312007-08-31 09:22:56 +0000595
Raymond Hettinger30439b22011-05-11 10:47:27 -0700596 A call to ``format(value, format_spec)`` is translated to
Georg Brandle4196d32014-10-31 09:41:46 +0100597 ``type(value).__format__(value, format_spec)`` which bypasses the instance
Raymond Hettinger30439b22011-05-11 10:47:27 -0700598 dictionary when searching for the value's :meth:`__format__` method. A
Larry Hastings3732ed22014-03-15 21:13:56 -0700599 :exc:`TypeError` exception is raised if the method search reaches
600 :mod:`object` and the *format_spec* is non-empty, or if either the
601 *format_spec* or the return value are not strings.
Georg Brandl4b491312007-08-31 09:22:56 +0000602
Larry Hastings3732ed22014-03-15 21:13:56 -0700603 .. versionchanged:: 3.4
Andrew Svetlov0794fe02012-12-23 15:12:19 +0200604 ``object().__format__(format_spec)`` raises :exc:`TypeError`
Larry Hastings3732ed22014-03-15 21:13:56 -0700605 if *format_spec* is not an empty string.
Andrew Svetlov0794fe02012-12-23 15:12:19 +0200606
Éric Araujo9edd9f02011-09-01 23:08:55 +0200607
608.. _func-frozenset:
Georg Brandleb7e8f62014-10-06 13:54:36 +0200609.. class:: frozenset([iterable])
Georg Brandl116aa622007-08-15 14:28:22 +0000610 :noindex:
611
Chris Jerdonekdf3abec2012-11-09 18:57:32 -0800612 Return a new :class:`frozenset` object, optionally with elements taken from
613 *iterable*. ``frozenset`` is a built-in class. See :class:`frozenset` and
614 :ref:`types-set` for documentation about this class.
Georg Brandl116aa622007-08-15 14:28:22 +0000615
Chris Jerdonekdf3abec2012-11-09 18:57:32 -0800616 For other containers see the built-in :class:`set`, :class:`list`,
617 :class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections`
618 module.
Georg Brandl116aa622007-08-15 14:28:22 +0000619
Georg Brandl116aa622007-08-15 14:28:22 +0000620
621.. function:: getattr(object, name[, default])
622
Georg Brandl8e4ddcf2010-10-16 18:51:05 +0000623 Return the value of the named attribute of *object*. *name* must be a string.
Georg Brandl116aa622007-08-15 14:28:22 +0000624 If the string is the name of one of the object's attributes, the result is the
625 value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
626 ``x.foobar``. If the named attribute does not exist, *default* is returned if
627 provided, otherwise :exc:`AttributeError` is raised.
628
629
630.. function:: globals()
631
632 Return a dictionary representing the current global symbol table. This is always
633 the dictionary of the current module (inside a function or method, this is the
634 module where it is defined, not the module from which it is called).
635
636
637.. function:: hasattr(object, name)
638
Benjamin Peterson17689992010-08-24 03:26:23 +0000639 The arguments are an object and a string. The result is ``True`` if the
640 string is the name of one of the object's attributes, ``False`` if not. (This
641 is implemented by calling ``getattr(object, name)`` and seeing whether it
642 raises an :exc:`AttributeError` or not.)
Georg Brandl116aa622007-08-15 14:28:22 +0000643
644
645.. function:: hash(object)
646
Barry Warsaw224a5992013-07-15 14:47:29 -0400647 Return the hash value of the object (if it has one). Hash values are
648 integers. They are used to quickly compare dictionary keys during a
649 dictionary lookup. Numeric values that compare equal have the same hash
650 value (even if they are of different types, as is the case for 1 and 1.0).
Georg Brandl116aa622007-08-15 14:28:22 +0000651
Andrés Delfinobda9c3e2018-06-29 06:57:10 -0300652 .. note::
Barry Warsaw224a5992013-07-15 14:47:29 -0400653
Andrés Delfinobda9c3e2018-06-29 06:57:10 -0300654 For objects with custom :meth:`__hash__` methods, note that :func:`hash`
655 truncates the return value based on the bit width of the host machine.
656 See :meth:`__hash__` for details.
Georg Brandl116aa622007-08-15 14:28:22 +0000657
658.. function:: help([object])
659
660 Invoke the built-in help system. (This function is intended for interactive
661 use.) If no argument is given, the interactive help system starts on the
662 interpreter console. If the argument is a string, then the string is looked up
663 as the name of a module, function, class, method, keyword, or documentation
664 topic, and a help page is printed on the console. If the argument is any other
665 kind of object, a help page on the object is generated.
666
Christian Heimes9bd667a2008-01-20 15:14:11 +0000667 This function is added to the built-in namespace by the :mod:`site` module.
668
Larry Hastings3732ed22014-03-15 21:13:56 -0700669 .. versionchanged:: 3.4
670 Changes to :mod:`pydoc` and :mod:`inspect` mean that the reported
671 signatures for callables are now more comprehensive and consistent.
672
Georg Brandl116aa622007-08-15 14:28:22 +0000673
674.. function:: hex(x)
675
Manvisha Kodali67ba4fa2017-07-06 22:30:58 +0300676 Convert an integer number to a lowercase hexadecimal string prefixed with
Serhiy Storchakadf00f042018-05-10 16:38:44 +0300677 "0x". If *x* is not a Python :class:`int` object, it has to define an
678 :meth:`__index__` method that returns an integer. Some examples:
Larry Hastings3732ed22014-03-15 21:13:56 -0700679
680 >>> hex(255)
681 '0xff'
682 >>> hex(-42)
683 '-0x2a'
684
Manvisha Kodali67ba4fa2017-07-06 22:30:58 +0300685 If you want to convert an integer number to an uppercase or lower hexadecimal
686 string with prefix or not, you can use either of the following ways:
687
688 >>> '%#x' % 255, '%x' % 255, '%X' % 255
689 ('0xff', 'ff', 'FF')
690 >>> format(255, '#x'), format(255, 'x'), format(255, 'X')
691 ('0xff', 'ff', 'FF')
692 >>> f'{255:#x}', f'{255:x}', f'{255:X}'
693 ('0xff', 'ff', 'FF')
694
695 See also :func:`format` for more information.
Larry Hastings3732ed22014-03-15 21:13:56 -0700696
697 See also :func:`int` for converting a hexadecimal string to an
698 integer using a base of 16.
Georg Brandl116aa622007-08-15 14:28:22 +0000699
Mark Dickinson36cea392009-10-03 10:18:40 +0000700 .. note::
701
702 To obtain a hexadecimal string representation for a float, use the
703 :meth:`float.hex` method.
704
Georg Brandl116aa622007-08-15 14:28:22 +0000705
706.. function:: id(object)
707
Georg Brandlba956ae2007-11-29 17:24:34 +0000708 Return the "identity" of an object. This is an integer which
Georg Brandl116aa622007-08-15 14:28:22 +0000709 is guaranteed to be unique and constant for this object during its lifetime.
Georg Brandl495f7b52009-10-27 15:28:25 +0000710 Two objects with non-overlapping lifetimes may have the same :func:`id`
711 value.
712
Éric Araujof33de712011-05-27 04:42:47 +0200713 .. impl-detail:: This is the address of the object in memory.
Georg Brandl116aa622007-08-15 14:28:22 +0000714
715
Georg Brandlc0902982007-09-12 21:29:27 +0000716.. function:: input([prompt])
717
718 If the *prompt* argument is present, it is written to standard output without
719 a trailing newline. The function then reads a line from input, converts it
720 to a string (stripping a trailing newline), and returns that. When EOF is
721 read, :exc:`EOFError` is raised. Example::
722
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300723 >>> s = input('--> ') # doctest: +SKIP
Georg Brandlc0902982007-09-12 21:29:27 +0000724 --> Monty Python's Flying Circus
Andrew Svetlov439e17f2012-08-12 15:16:42 +0300725 >>> s # doctest: +SKIP
Georg Brandlc0902982007-09-12 21:29:27 +0000726 "Monty Python's Flying Circus"
727
Georg Brandl7b469422007-09-12 21:32:27 +0000728 If the :mod:`readline` module was loaded, then :func:`input` will use it
Georg Brandlc0902982007-09-12 21:29:27 +0000729 to provide elaborate line editing and history features.
730
731
Georg Brandleb7e8f62014-10-06 13:54:36 +0200732.. class:: int(x=0)
733 int(x, base=10)
Georg Brandl116aa622007-08-15 14:28:22 +0000734
Georg Brandleb7e8f62014-10-06 13:54:36 +0200735 Return an integer object constructed from a number or string *x*, or return
Serhiy Storchakadf00f042018-05-10 16:38:44 +0300736 ``0`` if no arguments are given. If *x* defines :meth:`__int__`,
737 ``int(x)`` returns ``x.__int__()``. If *x* defines :meth:`__trunc__`,
738 it returns ``x.__trunc__()``.
739 For floating point numbers, this truncates towards zero.
Chris Jerdonek57491e02012-09-28 00:10:44 -0700740
741 If *x* is not a number or if *base* is given, then *x* must be a string,
742 :class:`bytes`, or :class:`bytearray` instance representing an :ref:`integer
743 literal <integers>` in radix *base*. Optionally, the literal can be
744 preceded by ``+`` or ``-`` (with no space in between) and surrounded by
745 whitespace. A base-n literal consists of the digits 0 to n-1, with ``a``
746 to ``z`` (or ``A`` to ``Z``) having
Serhiy Storchakac7b1a0b2016-11-26 13:43:28 +0200747 values 10 to 35. The default *base* is 10. The allowed values are 0 and 2--36.
Georg Brandl225d3c82008-04-09 18:45:14 +0000748 Base-2, -8, and -16 literals can be optionally prefixed with ``0b``/``0B``,
Georg Brandl1b5ab452009-08-13 07:56:35 +0000749 ``0o``/``0O``, or ``0x``/``0X``, as with integer literals in code. Base 0
750 means to interpret exactly as a code literal, so that the actual base is 2,
Georg Brandl225d3c82008-04-09 18:45:14 +0000751 8, 10, or 16, and so that ``int('010', 0)`` is not legal, while
752 ``int('010')`` is, as well as ``int('010', 8)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000753
754 The integer type is described in :ref:`typesnumeric`.
755
Mark Dickinson07c71362013-01-27 10:17:52 +0000756 .. versionchanged:: 3.4
757 If *base* is not an instance of :class:`int` and the *base* object has a
758 :meth:`base.__index__ <object.__index__>` method, that method is called
759 to obtain an integer for the base. Previous versions used
760 :meth:`base.__int__ <object.__int__>` instead of :meth:`base.__index__
761 <object.__index__>`.
Georg Brandl116aa622007-08-15 14:28:22 +0000762
Brett Cannona721aba2016-09-09 14:57:09 -0700763 .. versionchanged:: 3.6
764 Grouping digits with underscores as in code literals is allowed.
765
766
Georg Brandl116aa622007-08-15 14:28:22 +0000767.. function:: isinstance(object, classinfo)
768
Georg Brandl85eb8c12007-08-31 16:33:38 +0000769 Return true if the *object* argument is an instance of the *classinfo*
Éric Araujoe8b7eb02011-08-19 02:17:03 +0200770 argument, or of a (direct, indirect or :term:`virtual <abstract base
771 class>`) subclass thereof. If *object* is not
Terry Jan Reedy68b68742015-10-28 03:14:56 -0400772 an object of the given type, the function always returns false.
773 If *classinfo* is a tuple of type objects (or recursively, other such
774 tuples), return true if *object* is an instance of any of the types.
775 If *classinfo* is not a type or tuple of types and such tuples,
Georg Brandl85eb8c12007-08-31 16:33:38 +0000776 a :exc:`TypeError` exception is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000777
Georg Brandl116aa622007-08-15 14:28:22 +0000778
779.. function:: issubclass(class, classinfo)
780
Éric Araujoe8b7eb02011-08-19 02:17:03 +0200781 Return true if *class* is a subclass (direct, indirect or :term:`virtual
782 <abstract base class>`) of *classinfo*. A
Georg Brandl116aa622007-08-15 14:28:22 +0000783 class is considered a subclass of itself. *classinfo* may be a tuple of class
784 objects, in which case every entry in *classinfo* will be checked. In any other
785 case, a :exc:`TypeError` exception is raised.
786
Georg Brandl116aa622007-08-15 14:28:22 +0000787
Georg Brandl036490d2009-05-17 13:00:36 +0000788.. function:: iter(object[, sentinel])
Georg Brandl116aa622007-08-15 14:28:22 +0000789
Georg Brandl036490d2009-05-17 13:00:36 +0000790 Return an :term:`iterator` object. The first argument is interpreted very
791 differently depending on the presence of the second argument. Without a
792 second argument, *object* must be a collection object which supports the
793 iteration protocol (the :meth:`__iter__` method), or it must support the
794 sequence protocol (the :meth:`__getitem__` method with integer arguments
795 starting at ``0``). If it does not support either of those protocols,
796 :exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
797 then *object* must be a callable object. The iterator created in this case
Ezio Melotti7fa82222012-10-12 13:42:08 +0300798 will call *object* with no arguments for each call to its
799 :meth:`~iterator.__next__` method; if the value returned is equal to
800 *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will
801 be returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000802
Chris Jerdonek006d9072012-10-12 20:28:26 -0700803 See also :ref:`typeiter`.
804
Benjamin Petersonf07d0022009-03-21 17:31:58 +0000805 One useful application of the second form of :func:`iter` is to read lines of
806 a file until a certain line is reached. The following example reads a file
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +0300807 until the :meth:`~io.TextIOBase.readline` method returns an empty string::
Benjamin Petersonf07d0022009-03-21 17:31:58 +0000808
Raymond Hettinger90289282011-06-01 16:17:23 -0700809 with open('mydata.txt') as fp:
810 for line in iter(fp.readline, ''):
Benjamin Petersonf07d0022009-03-21 17:31:58 +0000811 process_line(line)
812
Georg Brandl116aa622007-08-15 14:28:22 +0000813
814.. function:: len(s)
815
816 Return the length (the number of items) of an object. The argument may be a
Terry Jan Reedyf2fb73f2014-06-16 03:05:37 -0400817 sequence (such as a string, bytes, tuple, list, or range) or a collection
818 (such as a dictionary, set, or frozen set).
Georg Brandl116aa622007-08-15 14:28:22 +0000819
820
Nick Coghlan83c0ae52012-08-21 17:42:52 +1000821.. _func-list:
Georg Brandleb7e8f62014-10-06 13:54:36 +0200822.. class:: list([iterable])
Nick Coghlan83c0ae52012-08-21 17:42:52 +1000823 :noindex:
Georg Brandl116aa622007-08-15 14:28:22 +0000824
Nick Coghlan83c0ae52012-08-21 17:42:52 +1000825 Rather than being a function, :class:`list` is actually a mutable
Chris Jerdonek006d9072012-10-12 20:28:26 -0700826 sequence type, as documented in :ref:`typesseq-list` and :ref:`typesseq`.
Georg Brandl116aa622007-08-15 14:28:22 +0000827
Georg Brandl036490d2009-05-17 13:00:36 +0000828
Georg Brandl116aa622007-08-15 14:28:22 +0000829.. function:: locals()
830
831 Update and return a dictionary representing the current local symbol table.
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000832 Free variables are returned by :func:`locals` when it is called in function
833 blocks, but not in class blocks.
Georg Brandl116aa622007-08-15 14:28:22 +0000834
Georg Brandle720c0a2009-04-27 16:20:50 +0000835 .. note::
Georg Brandl036490d2009-05-17 13:00:36 +0000836 The contents of this dictionary should not be modified; changes may not
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000837 affect the values of local and free variables used by the interpreter.
Georg Brandl116aa622007-08-15 14:28:22 +0000838
839.. function:: map(function, iterable, ...)
840
Georg Brandl952aea22007-09-04 17:50:40 +0000841 Return an iterator that applies *function* to every item of *iterable*,
842 yielding the results. If additional *iterable* arguments are passed,
843 *function* must take that many arguments and is applied to the items from all
Georg Brandlde2b00e2008-05-05 21:04:12 +0000844 iterables in parallel. With multiple iterables, the iterator stops when the
Raymond Hettingercdf8ba32009-02-19 04:45:07 +0000845 shortest iterable is exhausted. For cases where the function inputs are
846 already arranged into argument tuples, see :func:`itertools.starmap`\.
Georg Brandlde2b00e2008-05-05 21:04:12 +0000847
Georg Brandl116aa622007-08-15 14:28:22 +0000848
Raymond Hettingerf4284e42014-04-02 00:58:47 -0700849.. function:: max(iterable, *[, key, default])
Ezio Melottie0add762012-09-14 06:32:35 +0300850 max(arg1, arg2, *args[, key])
Georg Brandl116aa622007-08-15 14:28:22 +0000851
Ezio Melottie0add762012-09-14 06:32:35 +0300852 Return the largest item in an iterable or the largest of two or more
853 arguments.
854
Raymond Hettinger4d6018f2013-06-24 22:43:02 -0700855 If one positional argument is provided, it should be an :term:`iterable`.
856 The largest item in the iterable is returned. If two or more positional
Raymond Hettingerb30b34c2014-04-03 08:01:22 -0700857 arguments are provided, the largest of the positional arguments is
Raymond Hettinger4d6018f2013-06-24 22:43:02 -0700858 returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000859
Raymond Hettinger4d6018f2013-06-24 22:43:02 -0700860 There are two optional keyword-only arguments. The *key* argument specifies
861 a one-argument ordering function like that used for :meth:`list.sort`. The
862 *default* argument specifies an object to return if the provided iterable is
863 empty. If the iterable is empty and *default* is not provided, a
864 :exc:`ValueError` is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000865
Georg Brandl682d7e02010-10-06 10:26:05 +0000866 If multiple items are maximal, the function returns the first one
867 encountered. This is consistent with other sort-stability preserving tools
868 such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and
Raymond Hettinger476a31e2010-09-14 23:13:42 +0000869 ``heapq.nlargest(1, iterable, key=keyfunc)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000870
Larry Hastings3732ed22014-03-15 21:13:56 -0700871 .. versionadded:: 3.4
872 The *default* keyword-only argument.
873
Alexander Marshalove22072f2018-07-24 10:58:21 +0700874 .. versionchanged:: 3.8
875 The *key* can be ``None``.
876
Éric Araujo9edd9f02011-09-01 23:08:55 +0200877
878.. _func-memoryview:
Georg Brandl85eb8c12007-08-31 16:33:38 +0000879.. function:: memoryview(obj)
Benjamin Peterson6dfcb022008-09-10 21:02:02 +0000880 :noindex:
Georg Brandl85eb8c12007-08-31 16:33:38 +0000881
Benjamin Peterson1b25b922008-09-09 22:15:27 +0000882 Return a "memory view" object created from the given argument. See
883 :ref:`typememoryview` for more information.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000884
885
Raymond Hettingerf4284e42014-04-02 00:58:47 -0700886.. function:: min(iterable, *[, key, default])
Ezio Melottie0add762012-09-14 06:32:35 +0300887 min(arg1, arg2, *args[, key])
Georg Brandl116aa622007-08-15 14:28:22 +0000888
Ezio Melottie0add762012-09-14 06:32:35 +0300889 Return the smallest item in an iterable or the smallest of two or more
890 arguments.
891
Raymond Hettinger4d6018f2013-06-24 22:43:02 -0700892 If one positional argument is provided, it should be an :term:`iterable`.
893 The smallest item in the iterable is returned. If two or more positional
894 arguments are provided, the smallest of the positional arguments is
895 returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000896
Raymond Hettinger4d6018f2013-06-24 22:43:02 -0700897 There are two optional keyword-only arguments. The *key* argument specifies
898 a one-argument ordering function like that used for :meth:`list.sort`. The
899 *default* argument specifies an object to return if the provided iterable is
900 empty. If the iterable is empty and *default* is not provided, a
901 :exc:`ValueError` is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000902
Georg Brandl682d7e02010-10-06 10:26:05 +0000903 If multiple items are minimal, the function returns the first one
904 encountered. This is consistent with other sort-stability preserving tools
905 such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1,
906 iterable, key=keyfunc)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000907
Larry Hastings3732ed22014-03-15 21:13:56 -0700908 .. versionadded:: 3.4
909 The *default* keyword-only argument.
910
Alexander Marshalove22072f2018-07-24 10:58:21 +0700911 .. versionchanged:: 3.8
912 The *key* can be ``None``.
913
Georg Brandldf48b972014-03-24 09:06:18 +0100914
Georg Brandl116aa622007-08-15 14:28:22 +0000915.. function:: next(iterator[, default])
916
Ezio Melotti7fa82222012-10-12 13:42:08 +0300917 Retrieve the next item from the *iterator* by calling its
918 :meth:`~iterator.__next__` method. If *default* is given, it is returned
919 if the iterator is exhausted, otherwise :exc:`StopIteration` is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000920
921
Georg Brandleb7e8f62014-10-06 13:54:36 +0200922.. class:: object()
Georg Brandl116aa622007-08-15 14:28:22 +0000923
Georg Brandl85eb8c12007-08-31 16:33:38 +0000924 Return a new featureless object. :class:`object` is a base for all classes.
Georg Brandl55ac8f02007-09-01 13:51:09 +0000925 It has the methods that are common to all instances of Python classes. This
926 function does not accept any arguments.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000927
928 .. note::
929
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +0300930 :class:`object` does *not* have a :attr:`~object.__dict__`, so you can't
931 assign arbitrary attributes to an instance of the :class:`object` class.
Georg Brandl116aa622007-08-15 14:28:22 +0000932
Georg Brandl116aa622007-08-15 14:28:22 +0000933
934.. function:: oct(x)
935
Manvisha Kodali67ba4fa2017-07-06 22:30:58 +0300936 Convert an integer number to an octal string prefixed with "0o". The result
937 is a valid Python expression. If *x* is not a Python :class:`int` object, it
938 has to define an :meth:`__index__` method that returns an integer. For
939 example:
Georg Brandl116aa622007-08-15 14:28:22 +0000940
Manvisha Kodali67ba4fa2017-07-06 22:30:58 +0300941 >>> oct(8)
942 '0o10'
943 >>> oct(-56)
944 '-0o70'
945
946 If you want to convert an integer number to octal string either with prefix
947 "0o" or not, you can use either of the following ways.
948
949 >>> '%#o' % 10, '%o' % 10
950 ('0o12', '12')
951 >>> format(10, '#o'), format(10, 'o')
952 ('0o12', '12')
953 >>> f'{10:#o}', f'{10:o}'
954 ('0o12', '12')
955
956 See also :func:`format` for more information.
Georg Brandl116aa622007-08-15 14:28:22 +0000957
R David Murray9f0c9402012-08-17 20:33:54 -0400958 .. index::
959 single: file object; open() built-in function
960
Ross Lagerwall59142db2011-10-31 20:34:46 +0200961.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000962
R David Murray9f0c9402012-08-17 20:33:54 -0400963 Open *file* and return a corresponding :term:`file object`. If the file
R David Murray8eac5752012-08-17 20:38:19 -0400964 cannot be opened, an :exc:`OSError` is raised.
Georg Brandl48310cd2009-01-03 21:18:54 +0000965
Brett Cannon6fa7aad2016-09-06 15:55:02 -0700966 *file* is a :term:`path-like object` giving the pathname (absolute or
967 relative to the current working directory) of the file to be opened or an
968 integer file descriptor of the file to be wrapped. (If a file descriptor is
969 given, it is closed when the returned I/O object is closed, unless *closefd*
970 is set to ``False``.)
Georg Brandl116aa622007-08-15 14:28:22 +0000971
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000972 *mode* is an optional string that specifies the mode in which the file is
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000973 opened. It defaults to ``'r'`` which means open for reading in text mode.
974 Other common values are ``'w'`` for writing (truncating the file if it
Charles-François Natalib93f9fa2012-05-20 11:41:53 +0200975 already exists), ``'x'`` for exclusive creation and ``'a'`` for appending
976 (which on *some* Unix systems, means that *all* writes append to the end of
977 the file regardless of the current seek position). In text mode, if
Victor Stinnerf86a5e82012-06-05 13:43:22 +0200978 *encoding* is not specified the encoding used is platform dependent:
979 ``locale.getpreferredencoding(False)`` is called to get the current locale
980 encoding. (For reading and writing raw bytes use binary mode and leave
981 *encoding* unspecified.) The available modes are:
Georg Brandl116aa622007-08-15 14:28:22 +0000982
Andrés Delfinoa8ddf852018-06-25 03:06:10 -0300983 .. _filemodes:
984
985 .. index::
986 pair: file; modes
987
Benjamin Petersondd219122008-04-11 21:17:32 +0000988 ========= ===============================================================
989 Character Meaning
Georg Brandl44ea77b2013-03-28 13:28:44 +0100990 ========= ===============================================================
Benjamin Petersondd219122008-04-11 21:17:32 +0000991 ``'r'`` open for reading (default)
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000992 ``'w'`` open for writing, truncating the file first
Charles-François Natalib93f9fa2012-05-20 11:41:53 +0200993 ``'x'`` open for exclusive creation, failing if the file already exists
Benjamin Petersondd219122008-04-11 21:17:32 +0000994 ``'a'`` open for writing, appending to the end of the file if it exists
Georg Brandl7b6ca4a2009-04-27 06:13:55 +0000995 ``'b'`` binary mode
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +0000996 ``'t'`` text mode (default)
997 ``'+'`` open a disk file for updating (reading and writing)
Serhiy Storchaka6787a382013-11-23 22:12:06 +0200998 ``'U'`` :term:`universal newlines` mode (deprecated)
Benjamin Petersondd219122008-04-11 21:17:32 +0000999 ========= ===============================================================
Mark Summerfieldecff60e2007-12-14 10:07:44 +00001000
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +00001001 The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``).
Benjamin Peterson6b4fa772010-08-30 13:19:53 +00001002 For binary read-write access, the mode ``'w+b'`` opens and truncates the file
1003 to 0 bytes. ``'r+b'`` opens the file without truncation.
Skip Montanaro1c639602007-09-23 19:49:54 +00001004
Benjamin Peterson6b4fa772010-08-30 13:19:53 +00001005 As mentioned in the :ref:`io-overview`, Python distinguishes between binary
1006 and text I/O. Files opened in binary mode (including ``'b'`` in the *mode*
1007 argument) return contents as :class:`bytes` objects without any decoding. In
1008 text mode (the default, or when ``'t'`` is included in the *mode* argument),
1009 the contents of the file are returned as :class:`str`, the bytes having been
1010 first decoded using a platform-dependent encoding or using the specified
1011 *encoding* if given.
Mark Summerfieldecff60e2007-12-14 10:07:44 +00001012
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +00001013 .. note::
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +00001014
Benjamin Peterson6b4fa772010-08-30 13:19:53 +00001015 Python doesn't depend on the underlying operating system's notion of text
Ezio Melottie130a522011-10-19 10:58:56 +03001016 files; all the processing is done by Python itself, and is therefore
Benjamin Peterson6b4fa772010-08-30 13:19:53 +00001017 platform-independent.
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +00001018
Benjamin Peterson6b4fa772010-08-30 13:19:53 +00001019 *buffering* is an optional integer used to set the buffering policy. Pass 0
1020 to switch buffering off (only allowed in binary mode), 1 to select line
1021 buffering (only usable in text mode), and an integer > 1 to indicate the size
Terry Jan Reedydff04f42013-03-16 15:56:27 -04001022 in bytes of a fixed-size chunk buffer. When no *buffering* argument is
1023 given, the default buffering policy works as follows:
Benjamin Peterson4e4ffb12010-08-30 12:46:09 +00001024
Benjamin Peterson6b4fa772010-08-30 13:19:53 +00001025 * Binary files are buffered in fixed-size chunks; the size of the buffer is
1026 chosen using a heuristic trying to determine the underlying device's "block
1027 size" and falling back on :attr:`io.DEFAULT_BUFFER_SIZE`. On many systems,
1028 the buffer will typically be 4096 or 8192 bytes long.
1029
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001030 * "Interactive" text files (files for which :meth:`~io.IOBase.isatty`
Serhiy Storchakafbc1c262013-11-29 12:17:13 +02001031 returns ``True``) use line buffering. Other text files use the policy
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001032 described above for binary files.
Georg Brandl48310cd2009-01-03 21:18:54 +00001033
Benjamin Petersondd219122008-04-11 21:17:32 +00001034 *encoding* is the name of the encoding used to decode or encode the file.
1035 This should only be used in text mode. The default encoding is platform
Benjamin Peterson52c3bf12009-03-23 02:44:58 +00001036 dependent (whatever :func:`locale.getpreferredencoding` returns), but any
Nick Coghlanb9fdb7a2015-01-07 00:22:00 +10001037 :term:`text encoding` supported by Python
1038 can be used. See the :mod:`codecs` module for
Benjamin Peterson52c3bf12009-03-23 02:44:58 +00001039 the list of supported encodings.
Mark Summerfieldecff60e2007-12-14 10:07:44 +00001040
Benjamin Peterson52c3bf12009-03-23 02:44:58 +00001041 *errors* is an optional string that specifies how encoding and decoding
Martin Panter357ed2e2016-11-21 00:15:20 +00001042 errors are to be handled—this cannot be used in binary mode.
Nick Coghlanb9fdb7a2015-01-07 00:22:00 +10001043 A variety of standard error handlers are available
1044 (listed under :ref:`error-handlers`), though any
Andrew Kuchlingc7b6c502013-06-16 12:58:48 -04001045 error handling name that has been registered with
1046 :func:`codecs.register_error` is also valid. The standard names
Nick Coghlanb9fdb7a2015-01-07 00:22:00 +10001047 include:
Andrew Kuchlingc7b6c502013-06-16 12:58:48 -04001048
1049 * ``'strict'`` to raise a :exc:`ValueError` exception if there is
1050 an encoding error. The default value of ``None`` has the same
1051 effect.
1052
1053 * ``'ignore'`` ignores errors. Note that ignoring encoding errors
1054 can lead to data loss.
1055
1056 * ``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted
1057 where there is malformed data.
1058
1059 * ``'surrogateescape'`` will represent any incorrect bytes as code
1060 points in the Unicode Private Use Area ranging from U+DC80 to
1061 U+DCFF. These private code points will then be turned back into
1062 the same bytes when the ``surrogateescape`` error handler is used
1063 when writing data. This is useful for processing files in an
1064 unknown encoding.
1065
1066 * ``'xmlcharrefreplace'`` is only supported when writing to a file.
1067 Characters not supported by the encoding are replaced with the
1068 appropriate XML character reference ``&#nnn;``.
1069
Serhiy Storchaka07985ef2015-01-25 22:56:57 +02001070 * ``'backslashreplace'`` replaces malformed data by Python's backslashed
1071 escape sequences.
Mark Summerfieldecff60e2007-12-14 10:07:44 +00001072
Serhiy Storchaka166ebc42014-11-25 13:57:17 +02001073 * ``'namereplace'`` (also only supported when writing)
1074 replaces unsupported characters with ``\N{...}`` escape sequences.
1075
R David Murray1b00f252012-08-15 10:43:58 -04001076 .. index::
1077 single: universal newlines; open() built-in function
1078
1079 *newline* controls how :term:`universal newlines` mode works (it only
R David Murrayee0a9452012-08-15 11:05:36 -04001080 applies to text mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and
1081 ``'\r\n'``. It works as follows:
Mark Summerfieldecff60e2007-12-14 10:07:44 +00001082
Georg Brandl296d1be2012-08-14 09:39:07 +02001083 * When reading input from the stream, if *newline* is ``None``, universal
1084 newlines mode is enabled. Lines in the input can end in ``'\n'``,
1085 ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` before
R David Murray1b00f252012-08-15 10:43:58 -04001086 being returned to the caller. If it is ``''``, universal newlines mode is
Georg Brandl296d1be2012-08-14 09:39:07 +02001087 enabled, but line endings are returned to the caller untranslated. If it
1088 has any of the other legal values, input lines are only terminated by the
1089 given string, and the line ending is returned to the caller untranslated.
Benjamin Petersondd219122008-04-11 21:17:32 +00001090
Georg Brandl296d1be2012-08-14 09:39:07 +02001091 * When writing output to the stream, if *newline* is ``None``, any ``'\n'``
1092 characters written are translated to the system default line separator,
1093 :data:`os.linesep`. If *newline* is ``''`` or ``'\n'``, no translation
1094 takes place. If *newline* is any of the other legal values, any ``'\n'``
1095 characters written are translated to the given string.
Benjamin Petersondd219122008-04-11 21:17:32 +00001096
Benjamin Peterson8cad9c72009-03-23 02:38:01 +00001097 If *closefd* is ``False`` and a file descriptor rather than a filename was
1098 given, the underlying file descriptor will be kept open when the file is
Robert Collins933430a2014-10-18 13:32:43 +13001099 closed. If a filename is given *closefd* must be ``True`` (the default)
1100 otherwise an error will be raised.
Benjamin Peterson8cad9c72009-03-23 02:38:01 +00001101
Ross Lagerwall59142db2011-10-31 20:34:46 +02001102 A custom opener can be used by passing a callable as *opener*. The underlying
1103 file descriptor for the file object is then obtained by calling *opener* with
1104 (*file*, *flags*). *opener* must return an open file descriptor (passing
1105 :mod:`os.open` as *opener* results in functionality similar to passing
1106 ``None``).
1107
Victor Stinnerdaf45552013-08-28 00:53:59 +02001108 The newly created file is :ref:`non-inheritable <fd_inheritance>`.
1109
Éric Araujo5bd92702012-11-22 00:13:49 -05001110 The following example uses the :ref:`dir_fd <dir_fd>` parameter of the
Éric Araujo8f423c92012-11-03 17:06:52 -04001111 :func:`os.open` function to open a file relative to a given directory::
1112
1113 >>> import os
Éric Araujo5bd92702012-11-22 00:13:49 -05001114 >>> dir_fd = os.open('somedir', os.O_RDONLY)
1115 >>> def opener(path, flags):
1116 ... return os.open(path, flags, dir_fd=dir_fd)
Éric Araujo8f423c92012-11-03 17:06:52 -04001117 ...
Éric Araujo8f423c92012-11-03 17:06:52 -04001118 >>> with open('spamspam.txt', 'w', opener=opener) as f:
1119 ... print('This will be written to somedir/spamspam.txt', file=f)
1120 ...
Éric Araujo309b0432012-11-03 17:39:45 -04001121 >>> os.close(dir_fd) # don't leak a file descriptor
Éric Araujo8f423c92012-11-03 17:06:52 -04001122
R David Murray9f0c9402012-08-17 20:33:54 -04001123 The type of :term:`file object` returned by the :func:`open` function
R David Murray433ef3b2012-08-17 20:39:21 -04001124 depends on the mode. When :func:`open` is used to open a file in a text
1125 mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
Benjamin Peterson6b4fa772010-08-30 13:19:53 +00001126 :class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used
1127 to open a file in a binary mode with buffering, the returned class is a
1128 subclass of :class:`io.BufferedIOBase`. The exact class varies: in read
Martin Panter7462b6492015-11-02 03:37:02 +00001129 binary mode, it returns an :class:`io.BufferedReader`; in write binary and
1130 append binary modes, it returns an :class:`io.BufferedWriter`, and in
1131 read/write mode, it returns an :class:`io.BufferedRandom`. When buffering is
Benjamin Peterson6b4fa772010-08-30 13:19:53 +00001132 disabled, the raw stream, a subclass of :class:`io.RawIOBase`,
1133 :class:`io.FileIO`, is returned.
Georg Brandl116aa622007-08-15 14:28:22 +00001134
1135 .. index::
1136 single: line-buffered I/O
1137 single: unbuffered I/O
1138 single: buffer size, I/O
1139 single: I/O control; buffering
Skip Montanaro4d8c1932007-09-23 21:13:45 +00001140 single: binary mode
1141 single: text mode
1142 module: sys
Georg Brandl116aa622007-08-15 14:28:22 +00001143
Benjamin Petersondd219122008-04-11 21:17:32 +00001144 See also the file handling modules, such as, :mod:`fileinput`, :mod:`io`
Benjamin Peterson8cad9c72009-03-23 02:38:01 +00001145 (where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:`tempfile`,
1146 and :mod:`shutil`.
Georg Brandl116aa622007-08-15 14:28:22 +00001147
Steve Dower39294992016-08-30 21:22:36 -07001148 .. versionchanged::
1149 3.3
Antoine Pitrou62ab10a02011-10-12 20:10:51 +02001150
Steve Dower39294992016-08-30 21:22:36 -07001151 * The *opener* parameter was added.
1152 * The ``'x'`` mode was added.
1153 * :exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`.
1154 * :exc:`FileExistsError` is now raised if the file opened in exclusive
NAKAMURA Osamu29540cd2017-03-25 11:55:08 +09001155 creation mode (``'x'``) already exists.
Steve Dower39294992016-08-30 21:22:36 -07001156
1157 .. versionchanged::
1158 3.4
1159
1160 * The file is now non-inheritable.
Victor Stinnerdaf45552013-08-28 00:53:59 +02001161
Serhiy Storchaka6787a382013-11-23 22:12:06 +02001162 .. deprecated-removed:: 3.4 4.0
Victor Stinnerc803bd82014-10-22 09:55:44 +02001163
Serhiy Storchaka6787a382013-11-23 22:12:06 +02001164 The ``'U'`` mode.
1165
Steve Dower39294992016-08-30 21:22:36 -07001166 .. versionchanged::
1167 3.5
Victor Stinnera766ddf2015-03-26 23:50:57 +01001168
Steve Dower39294992016-08-30 21:22:36 -07001169 * If the system call is interrupted and the signal handler does not raise an
1170 exception, the function now retries the system call instead of raising an
1171 :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
1172 * The ``'namereplace'`` error handler was added.
Georg Brandlf6945182008-02-01 11:56:49 +00001173
Steve Dower39294992016-08-30 21:22:36 -07001174 .. versionchanged::
1175 3.6
1176
1177 * Support added to accept objects implementing :class:`os.PathLike`.
1178 * On Windows, opening a console buffer may return a subclass of
1179 :class:`io.RawIOBase` other than :class:`io.FileIO`.
Brett Cannonb08388d2016-06-09 15:58:06 -07001180
Georg Brandl116aa622007-08-15 14:28:22 +00001181.. function:: ord(c)
1182
Ezio Melottic99c8582011-10-25 09:32:34 +03001183 Given a string representing one Unicode character, return an integer
Nick Coghlaneed67192014-08-17 14:07:53 +10001184 representing the Unicode code point of that character. For example,
Terry Jan Reedy063d48d2016-03-20 21:18:40 -04001185 ``ord('a')`` returns the integer ``97`` and ``ord('€')`` (Euro sign)
1186 returns ``8364``. This is the inverse of :func:`chr`.
Georg Brandlf6945182008-02-01 11:56:49 +00001187
Georg Brandl116aa622007-08-15 14:28:22 +00001188
1189.. function:: pow(x, y[, z])
1190
1191 Return *x* to the power *y*; if *z* is present, return *x* to the power *y*,
1192 modulo *z* (computed more efficiently than ``pow(x, y) % z``). The two-argument
1193 form ``pow(x, y)`` is equivalent to using the power operator: ``x**y``.
1194
Georg Brandle06de8b2008-05-05 21:42:51 +00001195 The arguments must have numeric types. With mixed operand types, the
1196 coercion rules for binary arithmetic operators apply. For :class:`int`
1197 operands, the result has the same type as the operands (after coercion)
1198 unless the second argument is negative; in that case, all arguments are
1199 converted to float and a float result is delivered. For example, ``10**2``
1200 returns ``100``, but ``10**-2`` returns ``0.01``. If the second argument is
1201 negative, the third argument must be omitted. If *z* is present, *x* and *y*
1202 must be of integer types, and *y* must be non-negative.
Georg Brandl116aa622007-08-15 14:28:22 +00001203
1204
Ezio Melotti8429b672012-09-14 06:35:09 +03001205.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout, flush=False)
Georg Brandlf6945182008-02-01 11:56:49 +00001206
Terry Jan Reedy1895f2b2014-10-01 15:37:42 -04001207 Print *objects* to the text stream *file*, separated by *sep* and followed
Berker Peksag61b9ac92017-04-13 15:48:18 +03001208 by *end*. *sep*, *end*, *file* and *flush*, if present, must be given as keyword
Georg Brandlf6945182008-02-01 11:56:49 +00001209 arguments.
1210
1211 All non-keyword arguments are converted to strings like :func:`str` does and
1212 written to the stream, separated by *sep* and followed by *end*. Both *sep*
1213 and *end* must be strings; they can also be ``None``, which means to use the
Ezio Melottie0add762012-09-14 06:32:35 +03001214 default values. If no *objects* are given, :func:`print` will just write
Georg Brandlf6945182008-02-01 11:56:49 +00001215 *end*.
1216
1217 The *file* argument must be an object with a ``write(string)`` method; if it
Terry Jan Reedy1895f2b2014-10-01 15:37:42 -04001218 is not present or ``None``, :data:`sys.stdout` will be used. Since printed
1219 arguments are converted to text strings, :func:`print` cannot be used with
1220 binary mode file objects. For these, use ``file.write(...)`` instead.
1221
1222 Whether output is buffered is usually determined by *file*, but if the
1223 *flush* keyword argument is true, the stream is forcibly flushed.
Georg Brandlbc3b6822012-01-13 19:41:25 +01001224
1225 .. versionchanged:: 3.3
1226 Added the *flush* keyword argument.
Georg Brandlf6945182008-02-01 11:56:49 +00001227
1228
Georg Brandleb7e8f62014-10-06 13:54:36 +02001229.. class:: property(fget=None, fset=None, fdel=None, doc=None)
Georg Brandl116aa622007-08-15 14:28:22 +00001230
Georg Brandl85eb8c12007-08-31 16:33:38 +00001231 Return a property attribute.
Georg Brandl116aa622007-08-15 14:28:22 +00001232
Raymond Hettingerac191ce2014-08-10 10:41:25 -07001233 *fget* is a function for getting an attribute value. *fset* is a function
1234 for setting an attribute value. *fdel* is a function for deleting an attribute
1235 value. And *doc* creates a docstring for the attribute.
1236
1237 A typical use is to define a managed attribute ``x``::
Georg Brandl116aa622007-08-15 14:28:22 +00001238
Éric Araujo28053fb2010-11-22 03:09:19 +00001239 class C:
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +00001240 def __init__(self):
1241 self._x = None
1242
1243 def getx(self):
1244 return self._x
Raymond Hettingerac191ce2014-08-10 10:41:25 -07001245
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +00001246 def setx(self, value):
1247 self._x = value
Raymond Hettingerac191ce2014-08-10 10:41:25 -07001248
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +00001249 def delx(self):
1250 del self._x
Raymond Hettingerac191ce2014-08-10 10:41:25 -07001251
Georg Brandl116aa622007-08-15 14:28:22 +00001252 x = property(getx, setx, delx, "I'm the 'x' property.")
1253
Raymond Hettingerac191ce2014-08-10 10:41:25 -07001254 If *c* is an instance of *C*, ``c.x`` will invoke the getter,
Georg Brandl7528b9b2010-08-02 19:23:34 +00001255 ``c.x = value`` will invoke the setter and ``del c.x`` the deleter.
1256
Georg Brandl116aa622007-08-15 14:28:22 +00001257 If given, *doc* will be the docstring of the property attribute. Otherwise, the
1258 property will copy *fget*'s docstring (if it exists). This makes it possible to
Christian Heimesd8654cf2007-12-02 15:22:16 +00001259 create read-only properties easily using :func:`property` as a :term:`decorator`::
Georg Brandl116aa622007-08-15 14:28:22 +00001260
Éric Araujo28053fb2010-11-22 03:09:19 +00001261 class Parrot:
Georg Brandl116aa622007-08-15 14:28:22 +00001262 def __init__(self):
1263 self._voltage = 100000
1264
1265 @property
1266 def voltage(self):
1267 """Get the current voltage."""
1268 return self._voltage
1269
Raymond Hettingerac191ce2014-08-10 10:41:25 -07001270 The ``@property`` decorator turns the :meth:`voltage` method into a "getter"
1271 for a read-only attribute with the same name, and it sets the docstring for
1272 *voltage* to "Get the current voltage."
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +00001273
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001274 A property object has :attr:`~property.getter`, :attr:`~property.setter`,
1275 and :attr:`~property.deleter` methods usable as decorators that create a
1276 copy of the property with the corresponding accessor function set to the
1277 decorated function. This is best explained with an example::
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +00001278
Éric Araujo28053fb2010-11-22 03:09:19 +00001279 class C:
Benjamin Peterson206e3072008-10-19 14:07:49 +00001280 def __init__(self):
1281 self._x = None
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +00001282
1283 @property
1284 def x(self):
1285 """I'm the 'x' property."""
1286 return self._x
1287
1288 @x.setter
1289 def x(self, value):
1290 self._x = value
1291
1292 @x.deleter
1293 def x(self):
1294 del self._x
1295
1296 This code is exactly equivalent to the first example. Be sure to give the
1297 additional functions the same name as the original property (``x`` in this
1298 case.)
1299
Raymond Hettingerac191ce2014-08-10 10:41:25 -07001300 The returned property object also has the attributes ``fget``, ``fset``, and
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +00001301 ``fdel`` corresponding to the constructor arguments.
Georg Brandl116aa622007-08-15 14:28:22 +00001302
Raymond Hettinger29655df2015-05-15 16:17:05 -07001303 .. versionchanged:: 3.5
1304 The docstrings of property objects are now writeable.
1305
Georg Brandl116aa622007-08-15 14:28:22 +00001306
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001307.. _func-range:
Ezio Melottie0add762012-09-14 06:32:35 +03001308.. function:: range(stop)
1309 range(start, stop[, step])
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001310 :noindex:
Georg Brandl116aa622007-08-15 14:28:22 +00001311
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001312 Rather than being a function, :class:`range` is actually an immutable
Chris Jerdonek006d9072012-10-12 20:28:26 -07001313 sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`.
Benjamin Peterson878ce382011-11-05 15:17:52 -04001314
Georg Brandl116aa622007-08-15 14:28:22 +00001315
1316.. function:: repr(object)
1317
Georg Brandl68ee3a52008-03-25 07:21:32 +00001318 Return a string containing a printable representation of an object. For many
1319 types, this function makes an attempt to return a string that would yield an
1320 object with the same value when passed to :func:`eval`, otherwise the
1321 representation is a string enclosed in angle brackets that contains the name
1322 of the type of the object together with additional information often
1323 including the name and address of the object. A class can control what this
1324 function returns for its instances by defining a :meth:`__repr__` method.
Georg Brandl116aa622007-08-15 14:28:22 +00001325
1326
1327.. function:: reversed(seq)
1328
Christian Heimes7f044312008-01-06 17:05:40 +00001329 Return a reverse :term:`iterator`. *seq* must be an object which has
1330 a :meth:`__reversed__` method or supports the sequence protocol (the
1331 :meth:`__len__` method and the :meth:`__getitem__` method with integer
1332 arguments starting at ``0``).
Georg Brandl116aa622007-08-15 14:28:22 +00001333
Georg Brandl116aa622007-08-15 14:28:22 +00001334
Mark Dickinson4e12ad12012-09-20 20:51:14 +01001335.. function:: round(number[, ndigits])
Georg Brandl116aa622007-08-15 14:28:22 +00001336
csabella85deefc2017-03-29 17:14:06 -04001337 Return *number* rounded to *ndigits* precision after the decimal
1338 point. If *ndigits* is omitted or is ``None``, it returns the
1339 nearest integer to its input.
Georg Brandl809ddaa2008-07-01 20:39:59 +00001340
1341 For the built-in types supporting :func:`round`, values are rounded to the
Mark Dickinson4e12ad12012-09-20 20:51:14 +01001342 closest multiple of 10 to the power minus *ndigits*; if two multiples are
1343 equally close, rounding is done toward the even choice (so, for example,
1344 both ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is
Gerrit Holl6003db72017-03-27 23:15:20 +01001345 ``2``). Any integer value is valid for *ndigits* (positive, zero, or
Lisa Roach900c48d2018-05-20 11:00:18 -04001346 negative). The return value is an integer if *ndigits* is omitted or
1347 ``None``.
1348 Otherwise the return value has the same type as *number*.
Christian Heimes072c0f12008-01-03 23:01:04 +00001349
Lisa Roach900c48d2018-05-20 11:00:18 -04001350 For a general Python object ``number``, ``round`` delegates to
1351 ``number.__round__``.
csabella85deefc2017-03-29 17:14:06 -04001352
Mark Dickinsonc4fbcdc2010-07-30 13:13:02 +00001353 .. note::
1354
1355 The behavior of :func:`round` for floats can be surprising: for example,
1356 ``round(2.675, 2)`` gives ``2.67`` instead of the expected ``2.68``.
1357 This is not a bug: it's a result of the fact that most decimal fractions
1358 can't be represented exactly as a float. See :ref:`tut-fp-issues` for
1359 more information.
Georg Brandl116aa622007-08-15 14:28:22 +00001360
Éric Araujo9edd9f02011-09-01 23:08:55 +02001361
1362.. _func-set:
Georg Brandleb7e8f62014-10-06 13:54:36 +02001363.. class:: set([iterable])
Georg Brandl116aa622007-08-15 14:28:22 +00001364 :noindex:
1365
Chris Jerdonekdf3abec2012-11-09 18:57:32 -08001366 Return a new :class:`set` object, optionally with elements taken from
1367 *iterable*. ``set`` is a built-in class. See :class:`set` and
1368 :ref:`types-set` for documentation about this class.
1369
1370 For other containers see the built-in :class:`frozenset`, :class:`list`,
1371 :class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections`
1372 module.
Georg Brandl116aa622007-08-15 14:28:22 +00001373
Georg Brandl116aa622007-08-15 14:28:22 +00001374
1375.. function:: setattr(object, name, value)
1376
1377 This is the counterpart of :func:`getattr`. The arguments are an object, a
1378 string and an arbitrary value. The string may name an existing attribute or a
1379 new attribute. The function assigns the value to the attribute, provided the
1380 object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to
1381 ``x.foobar = 123``.
1382
1383
Georg Brandleb7e8f62014-10-06 13:54:36 +02001384.. class:: slice(stop)
1385 slice(start, stop[, step])
Georg Brandl116aa622007-08-15 14:28:22 +00001386
1387 .. index:: single: Numerical Python
1388
Christian Heimesd8654cf2007-12-02 15:22:16 +00001389 Return a :term:`slice` object representing the set of indices specified by
Georg Brandl116aa622007-08-15 14:28:22 +00001390 ``range(start, stop, step)``. The *start* and *step* arguments default to
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001391 ``None``. Slice objects have read-only data attributes :attr:`~slice.start`,
1392 :attr:`~slice.stop` and :attr:`~slice.step` which merely return the argument
1393 values (or their default). They have no other explicit functionality;
1394 however they are used by Numerical Python and other third party extensions.
1395 Slice objects are also generated when extended indexing syntax is used. For
1396 example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See
1397 :func:`itertools.islice` for an alternate version that returns an iterator.
Georg Brandl116aa622007-08-15 14:28:22 +00001398
1399
Łukasz Rogalskibe37beb2017-07-14 21:23:39 +02001400.. function:: sorted(iterable, *, key=None, reverse=False)
Georg Brandl116aa622007-08-15 14:28:22 +00001401
1402 Return a new sorted list from the items in *iterable*.
1403
Raymond Hettinger51b9c242008-02-14 13:52:24 +00001404 Has two optional arguments which must be specified as keyword arguments.
Georg Brandl116aa622007-08-15 14:28:22 +00001405
Georg Brandl116aa622007-08-15 14:28:22 +00001406 *key* specifies a function of one argument that is used to extract a comparison
Georg Brandl1f70cdf2010-03-21 09:04:24 +00001407 key from each list element: ``key=str.lower``. The default value is ``None``
1408 (compare the elements directly).
Georg Brandl116aa622007-08-15 14:28:22 +00001409
1410 *reverse* is a boolean value. If set to ``True``, then the list elements are
1411 sorted as if each comparison were reversed.
1412
Benjamin Peterson7ac98ae2010-08-17 17:52:02 +00001413 Use :func:`functools.cmp_to_key` to convert an old-style *cmp* function to a
1414 *key* function.
Georg Brandl116aa622007-08-15 14:28:22 +00001415
Ezio Melotti9b1e92f2014-10-28 12:57:11 +01001416 The built-in :func:`sorted` function is guaranteed to be stable. A sort is
1417 stable if it guarantees not to change the relative order of elements that
1418 compare equal --- this is helpful for sorting in multiple passes (for
1419 example, sort by department, then by salary grade).
1420
Senthil Kumarand03d1d42016-01-01 23:25:58 -08001421 For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`.
Raymond Hettinger46fca072010-04-02 00:25:45 +00001422
Daisuke Miyakawa0e61e672017-10-12 23:39:43 +09001423.. decorator:: staticmethod
Georg Brandl116aa622007-08-15 14:28:22 +00001424
Daisuke Miyakawa0e61e672017-10-12 23:39:43 +09001425 Transform a method into a static method.
Georg Brandl116aa622007-08-15 14:28:22 +00001426
1427 A static method does not receive an implicit first argument. To declare a static
1428 method, use this idiom::
1429
1430 class C:
1431 @staticmethod
1432 def f(arg1, arg2, ...): ...
1433
Christian Heimesd8654cf2007-12-02 15:22:16 +00001434 The ``@staticmethod`` form is a function :term:`decorator` -- see the
1435 description of function definitions in :ref:`function` for details.
Georg Brandl116aa622007-08-15 14:28:22 +00001436
1437 It can be called either on the class (such as ``C.f()``) or on an instance (such
1438 as ``C().f()``). The instance is ignored except for its class.
1439
Raymond Hettinger90289282011-06-01 16:17:23 -07001440 Static methods in Python are similar to those found in Java or C++. Also see
1441 :func:`classmethod` for a variant that is useful for creating alternate class
1442 constructors.
Georg Brandl116aa622007-08-15 14:28:22 +00001443
Éric Araujo03b95372017-10-12 12:28:55 -04001444 Like all decorators, it is also possible to call ``staticmethod`` as
1445 a regular function and do something with its result. This is needed
1446 in some cases where you need a reference to a function from a class
1447 body and you want to avoid the automatic transformation to instance
cocoatomo2a3260b2018-01-29 17:30:48 +09001448 method. For these cases, use this idiom::
Éric Araujo03b95372017-10-12 12:28:55 -04001449
1450 class C:
1451 builtin_open = staticmethod(open)
1452
Georg Brandl116aa622007-08-15 14:28:22 +00001453 For more information on static methods, consult the documentation on the
1454 standard type hierarchy in :ref:`types`.
1455
Chris Jerdonek5fae0e52012-11-20 17:45:51 -08001456
Éric Araujo03b95372017-10-12 12:28:55 -04001457.. index::
1458 single: string; str() (built-in function)
Georg Brandl116aa622007-08-15 14:28:22 +00001459
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001460.. _func-str:
Georg Brandleb7e8f62014-10-06 13:54:36 +02001461.. class:: str(object='')
1462 str(object=b'', encoding='utf-8', errors='strict')
Chris Jerdonekbb4e9412012-11-28 01:38:40 -08001463 :noindex:
Georg Brandl116aa622007-08-15 14:28:22 +00001464
Chris Jerdonekbb4e9412012-11-28 01:38:40 -08001465 Return a :class:`str` version of *object*. See :func:`str` for details.
Georg Brandl48310cd2009-01-03 21:18:54 +00001466
Chris Jerdonekbb4e9412012-11-28 01:38:40 -08001467 ``str`` is the built-in string :term:`class`. For general information
1468 about strings, see :ref:`textseq`.
Georg Brandl116aa622007-08-15 14:28:22 +00001469
1470
1471.. function:: sum(iterable[, start])
1472
1473 Sums *start* and the items of an *iterable* from left to right and returns the
1474 total. *start* defaults to ``0``. The *iterable*'s items are normally numbers,
Raymond Hettingerb3737992010-10-31 21:23:24 +00001475 and the start value is not allowed to be a string.
Georg Brandl116aa622007-08-15 14:28:22 +00001476
Éric Araujo8f9626b2010-11-06 06:30:16 +00001477 For some use cases, there are good alternatives to :func:`sum`.
Raymond Hettingerb3737992010-10-31 21:23:24 +00001478 The preferred, fast way to concatenate a sequence of strings is by calling
1479 ``''.join(sequence)``. To add floating point values with extended precision,
1480 see :func:`math.fsum`\. To concatenate a series of iterables, consider using
1481 :func:`itertools.chain`.
Georg Brandl116aa622007-08-15 14:28:22 +00001482
Mark Summerfield1041f742008-02-26 13:27:00 +00001483.. function:: super([type[, object-or-type]])
Georg Brandl116aa622007-08-15 14:28:22 +00001484
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001485 Return a proxy object that delegates method calls to a parent or sibling
1486 class of *type*. This is useful for accessing inherited methods that have
1487 been overridden in a class. The search order is same as that used by
1488 :func:`getattr` except that the *type* itself is skipped.
1489
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001490 The :attr:`~class.__mro__` attribute of the *type* lists the method
1491 resolution search order used by both :func:`getattr` and :func:`super`. The
1492 attribute is dynamic and can change whenever the inheritance hierarchy is
1493 updated.
Benjamin Peterson3e4f0552008-09-02 00:31:15 +00001494
Raymond Hettinger79d04342009-02-25 00:32:51 +00001495 If the second argument is omitted, the super object returned is unbound. If
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001496 the second argument is an object, ``isinstance(obj, type)`` must be true. If
Benjamin Petersond75fcb42009-02-19 04:22:03 +00001497 the second argument is a type, ``issubclass(type2, type)`` must be true (this
1498 is useful for classmethods).
Georg Brandl116aa622007-08-15 14:28:22 +00001499
Raymond Hettinger0a68b012009-02-25 00:58:47 +00001500 There are two typical use cases for *super*. In a class hierarchy with
1501 single inheritance, *super* can be used to refer to parent classes without
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001502 naming them explicitly, thus making the code more maintainable. This use
Raymond Hettinger0a68b012009-02-25 00:58:47 +00001503 closely parallels the use of *super* in other programming languages.
Georg Brandl48310cd2009-01-03 21:18:54 +00001504
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001505 The second use case is to support cooperative multiple inheritance in a
Georg Brandl48310cd2009-01-03 21:18:54 +00001506 dynamic execution environment. This use case is unique to Python and is
1507 not found in statically compiled languages or languages that only support
Raymond Hettingerd1258452009-02-26 00:27:18 +00001508 single inheritance. This makes it possible to implement "diamond diagrams"
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001509 where multiple base classes implement the same method. Good design dictates
1510 that this method have the same calling signature in every case (because the
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001511 order of calls is determined at runtime, because that order adapts
1512 to changes in the class hierarchy, and because that order can include
1513 sibling classes that are unknown prior to runtime).
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001514
1515 For both use cases, a typical superclass call looks like this::
Georg Brandl116aa622007-08-15 14:28:22 +00001516
1517 class C(B):
Mark Summerfield1041f742008-02-26 13:27:00 +00001518 def method(self, arg):
Georg Brandl036490d2009-05-17 13:00:36 +00001519 super().method(arg) # This does the same thing as:
1520 # super(C, self).method(arg)
Georg Brandl116aa622007-08-15 14:28:22 +00001521
1522 Note that :func:`super` is implemented as part of the binding process for
Mark Summerfield1041f742008-02-26 13:27:00 +00001523 explicit dotted attribute lookups such as ``super().__getitem__(name)``.
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001524 It does so by implementing its own :meth:`__getattribute__` method for searching
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001525 classes in a predictable order that supports cooperative multiple inheritance.
Georg Brandl116aa622007-08-15 14:28:22 +00001526 Accordingly, :func:`super` is undefined for implicit lookups using statements or
Raymond Hettinger518d8da2008-12-06 11:44:00 +00001527 operators such as ``super()[name]``.
1528
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001529 Also note that, aside from the zero argument form, :func:`super` is not
1530 limited to use inside methods. The two argument form specifies the
1531 arguments exactly and makes the appropriate references. The zero
1532 argument form only works inside a class definition, as the compiler fills
1533 in the necessary details to correctly retrieve the class being defined,
1534 as well as accessing the current instance for ordinary methods.
Georg Brandl116aa622007-08-15 14:28:22 +00001535
Raymond Hettinger90289282011-06-01 16:17:23 -07001536 For practical suggestions on how to design cooperative classes using
1537 :func:`super`, see `guide to using super()
Georg Brandl5d941342016-02-26 19:37:12 +01001538 <https://rhettinger.wordpress.com/2011/05/26/super-considered-super/>`_.
Raymond Hettinger90289282011-06-01 16:17:23 -07001539
Georg Brandl116aa622007-08-15 14:28:22 +00001540
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001541.. _func-tuple:
Georg Brandl116aa622007-08-15 14:28:22 +00001542.. function:: tuple([iterable])
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001543 :noindex:
Georg Brandl116aa622007-08-15 14:28:22 +00001544
Nick Coghlan83c0ae52012-08-21 17:42:52 +10001545 Rather than being a function, :class:`tuple` is actually an immutable
Chris Jerdonek006d9072012-10-12 20:28:26 -07001546 sequence type, as documented in :ref:`typesseq-tuple` and :ref:`typesseq`.
Georg Brandl116aa622007-08-15 14:28:22 +00001547
1548
Georg Brandleb7e8f62014-10-06 13:54:36 +02001549.. class:: type(object)
1550 type(name, bases, dict)
Georg Brandl116aa622007-08-15 14:28:22 +00001551
1552 .. index:: object: type
1553
Ezio Melotti837cd062012-10-24 23:06:25 +03001554 With one argument, return the type of an *object*. The return value is a
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001555 type object and generally the same object as returned by
1556 :attr:`object.__class__ <instance.__class__>`.
Georg Brandl116aa622007-08-15 14:28:22 +00001557
Georg Brandl85eb8c12007-08-31 16:33:38 +00001558 The :func:`isinstance` built-in function is recommended for testing the type
1559 of an object, because it takes subclasses into account.
1560
Georg Brandl116aa622007-08-15 14:28:22 +00001561
Ezio Melotti837cd062012-10-24 23:06:25 +03001562 With three arguments, return a new type object. This is essentially a
1563 dynamic form of the :keyword:`class` statement. The *name* string is the
Martin Panterbae5d812016-06-18 03:57:31 +00001564 class name and becomes the :attr:`~definition.__name__` attribute; the *bases*
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001565 tuple itemizes the base classes and becomes the :attr:`~class.__bases__`
1566 attribute; and the *dict* dictionary is the namespace containing definitions
R David Murraydd4fcf52016-06-02 20:05:43 -04001567 for class body and is copied to a standard dictionary to become the
1568 :attr:`~object.__dict__` attribute. For example, the following two
1569 statements create identical :class:`type` objects:
Georg Brandl116aa622007-08-15 14:28:22 +00001570
Éric Araujo28053fb2010-11-22 03:09:19 +00001571 >>> class X:
Georg Brandl116aa622007-08-15 14:28:22 +00001572 ... a = 1
Georg Brandl48310cd2009-01-03 21:18:54 +00001573 ...
Georg Brandl116aa622007-08-15 14:28:22 +00001574 >>> X = type('X', (object,), dict(a=1))
1575
Chris Jerdonek006d9072012-10-12 20:28:26 -07001576 See also :ref:`bltin-type-objects`.
1577
Berker Peksag3f015a62016-08-19 11:04:07 +03001578 .. versionchanged:: 3.6
1579 Subclasses of :class:`type` which don't override ``type.__new__`` may no
1580 longer use the one-argument form to get the type of an object.
Georg Brandl116aa622007-08-15 14:28:22 +00001581
1582.. function:: vars([object])
1583
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001584 Return the :attr:`~object.__dict__` attribute for a module, class, instance,
Martin Panterbae5d812016-06-18 03:57:31 +00001585 or any other object with a :attr:`~object.__dict__` attribute.
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +00001586
Martin Panterbae5d812016-06-18 03:57:31 +00001587 Objects such as modules and instances have an updateable :attr:`~object.__dict__`
Raymond Hettingerd7100172013-06-02 10:03:05 -07001588 attribute; however, other objects may have write restrictions on their
Martin Panterbae5d812016-06-18 03:57:31 +00001589 :attr:`~object.__dict__` attributes (for example, classes use a
Berker Peksag37e87e62016-06-24 09:12:01 +03001590 :class:`types.MappingProxyType` to prevent direct dictionary updates).
Georg Brandl116aa622007-08-15 14:28:22 +00001591
Raymond Hettingerd7100172013-06-02 10:03:05 -07001592 Without an argument, :func:`vars` acts like :func:`locals`. Note, the
1593 locals dictionary is only useful for reads since updates to the locals
1594 dictionary are ignored.
1595
Georg Brandl116aa622007-08-15 14:28:22 +00001596
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001597.. function:: zip(*iterables)
Georg Brandl116aa622007-08-15 14:28:22 +00001598
Georg Brandl48310cd2009-01-03 21:18:54 +00001599 Make an iterator that aggregates elements from each of the iterables.
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001600
1601 Returns an iterator of tuples, where the *i*-th tuple contains
Georg Brandl952aea22007-09-04 17:50:40 +00001602 the *i*-th element from each of the argument sequences or iterables. The
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001603 iterator stops when the shortest input iterable is exhausted. With a single
Georg Brandl48310cd2009-01-03 21:18:54 +00001604 iterable argument, it returns an iterator of 1-tuples. With no arguments,
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001605 it returns an empty iterator. Equivalent to::
1606
Raymond Hettinger2f08df32010-10-10 05:54:39 +00001607 def zip(*iterables):
1608 # zip('ABCD', 'xy') --> Ax By
1609 sentinel = object()
Raymond Hettinger6f45d182011-10-30 15:06:14 -07001610 iterators = [iter(it) for it in iterables]
1611 while iterators:
Raymond Hettinger2f08df32010-10-10 05:54:39 +00001612 result = []
Raymond Hettinger6f45d182011-10-30 15:06:14 -07001613 for it in iterators:
Raymond Hettinger2f08df32010-10-10 05:54:39 +00001614 elem = next(it, sentinel)
1615 if elem is sentinel:
1616 return
1617 result.append(elem)
1618 yield tuple(result)
Georg Brandl116aa622007-08-15 14:28:22 +00001619
Christian Heimes1af737c2008-01-23 08:24:23 +00001620 The left-to-right evaluation order of the iterables is guaranteed. This
1621 makes possible an idiom for clustering a data series into n-length groups
Raymond Hettinger0907a452015-05-13 02:34:38 -07001622 using ``zip(*[iter(s)]*n)``. This repeats the *same* iterator ``n`` times
1623 so that each output tuple has the result of ``n`` calls to the iterator.
1624 This has the effect of dividing the input into n-length chunks.
Christian Heimes1af737c2008-01-23 08:24:23 +00001625
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001626 :func:`zip` should only be used with unequal length inputs when you don't
1627 care about trailing, unmatched values from the longer iterables. If those
1628 values are important, use :func:`itertools.zip_longest` instead.
Georg Brandl116aa622007-08-15 14:28:22 +00001629
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001630 :func:`zip` in conjunction with the ``*`` operator can be used to unzip a
1631 list::
1632
1633 >>> x = [1, 2, 3]
1634 >>> y = [4, 5, 6]
1635 >>> zipped = zip(x, y)
Georg Brandl17fe3642008-12-06 14:28:56 +00001636 >>> list(zipped)
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001637 [(1, 4), (2, 5), (3, 6)]
Georg Brandl17fe3642008-12-06 14:28:56 +00001638 >>> x2, y2 = zip(*zip(x, y))
Benjamin Petersonfa0d7032009-06-01 22:42:33 +00001639 >>> x == list(x2) and y == list(y2)
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001640 True
1641
Georg Brandl2ee470f2008-07-16 12:55:28 +00001642
Brett Cannoncb4996a2012-08-06 16:34:44 -04001643.. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0)
Georg Brandl48367812008-12-05 15:55:41 +00001644
1645 .. index::
1646 statement: import
1647 module: imp
1648
1649 .. note::
1650
1651 This is an advanced function that is not needed in everyday Python
Éric Araujoe801aa22011-07-29 17:50:58 +02001652 programming, unlike :func:`importlib.import_module`.
Georg Brandl48367812008-12-05 15:55:41 +00001653
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001654 This function is invoked by the :keyword:`import` statement. It can be
1655 replaced (by importing the :mod:`builtins` module and assigning to
1656 ``builtins.__import__``) in order to change semantics of the
Brett Cannonf5ebd262013-08-23 10:58:49 -04001657 :keyword:`import` statement, but doing so is **strongly** discouraged as it
1658 is usually simpler to use import hooks (see :pep:`302`) to attain the same
1659 goals and does not cause issues with code which assumes the default import
1660 implementation is in use. Direct use of :func:`__import__` is also
1661 discouraged in favor of :func:`importlib.import_module`.
Georg Brandl48367812008-12-05 15:55:41 +00001662
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001663 The function imports the module *name*, potentially using the given *globals*
1664 and *locals* to determine how to interpret the name in a package context.
1665 The *fromlist* gives the names of objects or submodules that should be
1666 imported from the module given by *name*. The standard implementation does
1667 not use its *locals* argument at all, and uses its *globals* only to
1668 determine the package context of the :keyword:`import` statement.
1669
Brett Cannon2b9fd472009-03-15 02:18:41 +00001670 *level* specifies whether to use absolute or relative imports. ``0`` (the
1671 default) means only perform absolute imports. Positive values for
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001672 *level* indicate the number of parent directories to search relative to the
Brett Cannon2a082ad2012-04-14 21:58:33 -04001673 directory of the module calling :func:`__import__` (see :pep:`328` for the
1674 details).
Georg Brandl48367812008-12-05 15:55:41 +00001675
1676 When the *name* variable is of the form ``package.module``, normally, the
1677 top-level package (the name up till the first dot) is returned, *not* the
1678 module named by *name*. However, when a non-empty *fromlist* argument is
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001679 given, the module named by *name* is returned.
Georg Brandl48367812008-12-05 15:55:41 +00001680
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001681 For example, the statement ``import spam`` results in bytecode resembling the
1682 following code::
Georg Brandl48310cd2009-01-03 21:18:54 +00001683
Brett Cannon2b9fd472009-03-15 02:18:41 +00001684 spam = __import__('spam', globals(), locals(), [], 0)
Georg Brandl48367812008-12-05 15:55:41 +00001685
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001686 The statement ``import spam.ham`` results in this call::
Georg Brandl48367812008-12-05 15:55:41 +00001687
Brett Cannon2b9fd472009-03-15 02:18:41 +00001688 spam = __import__('spam.ham', globals(), locals(), [], 0)
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001689
1690 Note how :func:`__import__` returns the toplevel module here because this is
1691 the object that is bound to a name by the :keyword:`import` statement.
1692
1693 On the other hand, the statement ``from spam.ham import eggs, sausage as
1694 saus`` results in ::
1695
Brett Cannon2b9fd472009-03-15 02:18:41 +00001696 _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001697 eggs = _temp.eggs
1698 saus = _temp.sausage
1699
1700 Here, the ``spam.ham`` module is returned from :func:`__import__`. From this
1701 object, the names to import are retrieved and assigned to their respective
1702 names.
1703
1704 If you simply want to import a module (potentially within a package) by name,
Éric Araujoe801aa22011-07-29 17:50:58 +02001705 use :func:`importlib.import_module`.
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001706
Brett Cannon73df3642012-07-30 18:35:17 -04001707 .. versionchanged:: 3.3
Brett Cannon222d4732012-08-05 20:49:53 -04001708 Negative values for *level* are no longer supported (which also changes
1709 the default value to 0).
Brett Cannon73df3642012-07-30 18:35:17 -04001710
Georg Brandl48367812008-12-05 15:55:41 +00001711
Georg Brandl116aa622007-08-15 14:28:22 +00001712.. rubric:: Footnotes
1713
Georg Brandl47f27a32009-03-31 16:57:13 +00001714.. [#] Note that the parser only accepts the Unix-style end of line convention.
1715 If you are reading the code from a file, make sure to use newline conversion
1716 mode to convert Windows or Mac-style newlines.