1
.. XXX document all delegations to __special__ methods
7
The Python interpreter has a number of functions and types built into it that
8
are always available. They are listed here in alphabetical order.
10
=================== ================= ================== ================ ====================
11
.. .. Built-in Functions .. ..
12
=================== ================= ================== ================ ====================
13
:func:`abs` |func-dict|_ :func:`help` :func:`min` :func:`setattr`
14
:func:`all` :func:`dir` :func:`hex` :func:`next` :func:`slice`
15
:func:`any` :func:`divmod` :func:`id` :func:`object` :func:`sorted`
16
:func:`ascii` :func:`enumerate` :func:`input` :func:`oct` :func:`staticmethod`
17
:func:`bin` :func:`eval` :func:`int` :func:`open` |func-str|_
18
:func:`bool` :func:`exec` :func:`isinstance` :func:`ord` :func:`sum`
19
:func:`bytearray` :func:`filter` :func:`issubclass` :func:`pow` :func:`super`
20
:func:`bytes` :func:`float` :func:`iter` :func:`print` |func-tuple|_
21
:func:`callable` :func:`format` :func:`len` :func:`property` :func:`type`
22
:func:`chr` |func-frozenset|_ |func-list|_ |func-range|_ :func:`vars`
23
:func:`classmethod` :func:`getattr` :func:`locals` :func:`repr` :func:`zip`
24
:func:`compile` :func:`globals` :func:`map` :func:`reversed` :func:`__import__`
25
:func:`complex` :func:`hasattr` :func:`max` :func:`round`
26
:func:`delattr` :func:`hash` |func-memoryview|_ |func-set|_
27
=================== ================= ================== ================ ====================
29
.. 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
32
.. |func-dict| replace:: ``dict()``
33
.. |func-frozenset| replace:: ``frozenset()``
34
.. |func-memoryview| replace:: ``memoryview()``
35
.. |func-set| replace:: ``set()``
36
.. |func-list| replace:: ``list()``
37
.. |func-str| replace:: ``str()``
38
.. |func-tuple| replace:: ``tuple()``
39
.. |func-range| replace:: ``range()``
44
Return the absolute value of a number. The argument may be an
45
integer or a floating point number. If the argument is a complex number, its
46
magnitude is returned.
49
.. function:: all(iterable)
51
Return True if all elements of the *iterable* are true (or if the iterable
52
is empty). Equivalent to::
55
for element in iterable:
61
.. function:: any(iterable)
63
Return True if any element of the *iterable* is true. If the iterable
64
is empty, return False. Equivalent to::
67
for element in iterable:
73
.. function:: ascii(object)
75
As :func:`repr`, return a string containing a printable representation of an
76
object, but escape the non-ASCII characters in the string returned by
77
:func:`repr` using ``\x``, ``\u`` or ``\U`` escapes. This generates a string
78
similar to that returned by :func:`repr` in Python 2.
83
Convert an integer number to a binary string. The result is a valid Python
84
expression. If *x* is not a Python :class:`int` object, it has to define an
85
:meth:`__index__` method that returns an integer.
88
.. function:: bool([x])
90
Convert a value to a Boolean, using the standard :ref:`truth testing
91
procedure <truth>`. If *x* is false or omitted, this returns ``False``;
92
otherwise it returns ``True``. :class:`bool` is also a class, which is a
93
subclass of :class:`int` (see :ref:`typesnumeric`). Class :class:`bool`
94
cannot be subclassed further. Its only instances are ``False`` and
95
``True`` (see :ref:`bltin-boolean-values`).
97
.. index:: pair: Boolean; type
101
.. function:: bytearray([source[, encoding[, errors]]])
103
Return a new array of bytes. The :class:`bytearray` type is a mutable
104
sequence of integers in the range 0 <= x < 256. It has most of the usual
105
methods of mutable sequences, described in :ref:`typesseq-mutable`, as well
106
as most methods that the :class:`bytes` type has, see :ref:`bytes-methods`.
108
The optional *source* parameter can be used to initialize the array in a few
111
* If it is a *string*, you must also give the *encoding* (and optionally,
112
*errors*) parameters; :func:`bytearray` then converts the string to
113
bytes using :meth:`str.encode`.
115
* If it is an *integer*, the array will have that size and will be
116
initialized with null bytes.
118
* If it is an object conforming to the *buffer* interface, a read-only buffer
119
of the object will be used to initialize the bytes array.
121
* If it is an *iterable*, it must be an iterable of integers in the range
122
``0 <= x < 256``, which are used as the initial contents of the array.
124
Without an argument, an array of size 0 is created.
126
See also :ref:`binaryseq` and :ref:`typebytearray`.
130
.. function:: bytes([source[, encoding[, errors]]])
132
Return a new "bytes" object, which is an immutable sequence of integers in
133
the range ``0 <= x < 256``. :class:`bytes` is an immutable version of
134
:class:`bytearray` -- it has the same non-mutating methods and the same
135
indexing and slicing behavior.
137
Accordingly, constructor arguments are interpreted as for :func:`bytearray`.
139
Bytes objects can also be created with literals, see :ref:`strings`.
141
See also :ref:`binaryseq`, :ref:`typebytes`, and :ref:`bytes-methods`.
144
.. function:: callable(object)
146
Return :const:`True` if the *object* argument appears callable,
147
:const:`False` if not. If this returns true, it is still possible that a
148
call fails, but if it is false, calling *object* will never succeed.
149
Note that classes are callable (calling a class returns a new instance);
150
instances are callable if their class has a :meth:`__call__` method.
152
.. versionadded:: 3.2
153
This function was first removed in Python 3.0 and then brought back
159
Return the string representing a character whose Unicode codepoint is the integer
160
*i*. For example, ``chr(97)`` returns the string ``'a'``. This is the
161
inverse of :func:`ord`. The valid range for the argument is from 0 through
162
1,114,111 (0x10FFFF in base 16). :exc:`ValueError` will be raised if *i* is
166
.. function:: classmethod(function)
168
Return a class method for *function*.
170
A class method receives the class as implicit first argument, just like an
171
instance method receives the instance. To declare a class method, use this
176
def f(cls, arg1, arg2, ...): ...
178
The ``@classmethod`` form is a function :term:`decorator` -- see the description
179
of function definitions in :ref:`function` for details.
181
It can be called either on the class (such as ``C.f()``) or on an instance (such
182
as ``C().f()``). The instance is ignored except for its class. If a class
183
method is called for a derived class, the derived class object is passed as the
184
implied first argument.
186
Class methods are different than C++ or Java static methods. If you want those,
187
see :func:`staticmethod` in this section.
189
For more information on class methods, consult the documentation on the standard
190
type hierarchy in :ref:`types`.
193
.. function:: compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1)
195
Compile the *source* into a code or AST object. Code objects can be executed
196
by :func:`exec` or :func:`eval`. *source* can either be a string or an AST
197
object. Refer to the :mod:`ast` module documentation for information on how
198
to work with AST objects.
200
The *filename* argument should give the file from which the code was read;
201
pass some recognizable value if it wasn't read from a file (``'<string>'`` is
204
The *mode* argument specifies what kind of code must be compiled; it can be
205
``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
206
consists of a single expression, or ``'single'`` if it consists of a single
207
interactive statement (in the latter case, expression statements that
208
evaluate to something other than ``None`` will be printed).
210
The optional arguments *flags* and *dont_inherit* control which future
211
statements (see :pep:`236`) affect the compilation of *source*. If neither
212
is present (or both are zero) the code is compiled with those future
213
statements that are in effect in the code that is calling compile. If the
214
*flags* argument is given and *dont_inherit* is not (or is zero) then the
215
future statements specified by the *flags* argument are used in addition to
216
those that would be used anyway. If *dont_inherit* is a non-zero integer then
217
the *flags* argument is it -- the future statements in effect around the call
218
to compile are ignored.
220
Future statements are specified by bits which can be bitwise ORed together to
221
specify multiple statements. The bitfield required to specify a given feature
222
can be found as the :attr:`~__future__._Feature.compiler_flag` attribute on
223
the :class:`~__future__._Feature` instance in the :mod:`__future__` module.
225
The argument *optimize* specifies the optimization level of the compiler; the
226
default value of ``-1`` selects the optimization level of the interpreter as
227
given by :option:`-O` options. Explicit levels are ``0`` (no optimization;
228
``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)
229
or ``2`` (docstrings are removed too).
231
This function raises :exc:`SyntaxError` if the compiled source is invalid,
232
and :exc:`TypeError` if the source contains null bytes.
236
When compiling a string with multi-line code in ``'single'`` or
237
``'eval'`` mode, input must be terminated by at least one newline
238
character. This is to facilitate detection of incomplete and complete
239
statements in the :mod:`code` module.
241
.. versionchanged:: 3.2
242
Allowed use of Windows and Mac newlines. Also input in ``'exec'`` mode
243
does not have to end in a newline anymore. Added the *optimize* parameter.
246
.. function:: complex([real[, imag]])
248
Create a complex number with the value *real* + *imag*\*j or convert a string or
249
number to a complex number. If the first parameter is a string, it will be
250
interpreted as a complex number and the function must be called without a second
251
parameter. The second parameter can never be a string. Each argument may be any
252
numeric type (including complex). If *imag* is omitted, it defaults to zero and
253
the function serves as a numeric conversion function like :func:`int`
254
and :func:`float`. If both arguments are omitted, returns ``0j``.
258
When converting from a string, the string must not contain whitespace
259
around the central ``+`` or ``-`` operator. For example,
260
``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` raises
263
The complex type is described in :ref:`typesnumeric`.
266
.. function:: delattr(object, name)
268
This is a relative of :func:`setattr`. The arguments are an object and a
269
string. The string must be the name of one of the object's attributes. The
270
function deletes the named attribute, provided the object allows it. For
271
example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
275
.. function:: dict(**kwarg)
276
dict(mapping, **kwarg)
277
dict(iterable, **kwarg)
280
Create a new dictionary. The :class:`dict` object is the dictionary class.
281
See :class:`dict` and :ref:`typesmapping` for documentation about this
284
For other containers see the built-in :class:`list`, :class:`set`, and
285
:class:`tuple` classes, as well as the :mod:`collections` module.
288
.. function:: dir([object])
290
Without arguments, return the list of names in the current local scope. With an
291
argument, attempt to return a list of valid attributes for that object.
293
If the object has a method named :meth:`__dir__`, this method will be called and
294
must return the list of attributes. This allows objects that implement a custom
295
:func:`__getattr__` or :func:`__getattribute__` function to customize the way
296
:func:`dir` reports their attributes.
298
If the object does not provide :meth:`__dir__`, the function tries its best to
299
gather information from the object's :attr:`__dict__` attribute, if defined, and
300
from its type object. The resulting list is not necessarily complete, and may
301
be inaccurate when the object has a custom :func:`__getattr__`.
303
The default :func:`dir` mechanism behaves differently with different types of
304
objects, as it attempts to produce the most relevant, rather than complete,
307
* If the object is a module object, the list contains the names of the module's
310
* If the object is a type or class object, the list contains the names of its
311
attributes, and recursively of the attributes of its bases.
313
* Otherwise, the list contains the object's attributes' names, the names of its
314
class's attributes, and recursively of the attributes of its class's base
317
The resulting list is sorted alphabetically. For example:
320
>>> dir() # show the names in the module namespace
321
['__builtins__', '__name__', 'struct']
322
>>> dir(struct) # show the names in the struct module # doctest: +SKIP
323
['Struct', '__all__', '__builtins__', '__cached__', '__doc__', '__file__',
324
'__initializing__', '__loader__', '__name__', '__package__',
325
'_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
326
'unpack', 'unpack_from']
328
... def __dir__(self):
329
... return ['area', 'perimeter', 'location']
332
['area', 'location', 'perimeter']
336
Because :func:`dir` is supplied primarily as a convenience for use at an
337
interactive prompt, it tries to supply an interesting set of names more
338
than it tries to supply a rigorously or consistently defined set of names,
339
and its detailed behavior may change across releases. For example,
340
metaclass attributes are not in the result list when the argument is a
344
.. function:: divmod(a, b)
346
Take two (non complex) numbers as arguments and return a pair of numbers
347
consisting of their quotient and remainder when using integer division. With
348
mixed operand types, the rules for binary arithmetic operators apply. For
349
integers, the result is the same as ``(a // b, a % b)``. For floating point
350
numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a /
351
b)`` but may be 1 less than that. In any case ``q * b + a % b`` is very
352
close to *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0
353
<= abs(a % b) < abs(b)``.
356
.. function:: enumerate(iterable, start=0)
358
Return an enumerate object. *iterable* must be a sequence, an
359
:term:`iterator`, or some other object which supports iteration.
360
The :meth:`~iterator.__next__` method of the iterator returned by
361
:func:`enumerate` returns a tuple containing a count (from *start* which
362
defaults to 0) and the values obtained from iterating over *iterable*.
364
>>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
365
>>> list(enumerate(seasons))
366
[(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
367
>>> list(enumerate(seasons, start=1))
368
[(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]
372
def enumerate(sequence, start=0):
374
for elem in sequence:
379
.. function:: eval(expression, globals=None, locals=None)
381
The arguments are a string and optional globals and locals. If provided,
382
*globals* must be a dictionary. If provided, *locals* can be any mapping
385
The *expression* argument is parsed and evaluated as a Python expression
386
(technically speaking, a condition list) using the *globals* and *locals*
387
dictionaries as global and local namespace. If the *globals* dictionary is
388
present and lacks '__builtins__', the current globals are copied into *globals*
389
before *expression* is parsed. This means that *expression* normally has full
390
access to the standard :mod:`builtins` module and restricted environments are
391
propagated. If the *locals* dictionary is omitted it defaults to the *globals*
392
dictionary. If both dictionaries are omitted, the expression is executed in the
393
environment where :func:`eval` is called. The return value is the result of
394
the evaluated expression. Syntax errors are reported as exceptions. Example:
400
This function can also be used to execute arbitrary code objects (such as
401
those created by :func:`compile`). In this case pass a code object instead
402
of a string. If the code object has been compiled with ``'exec'`` as the
403
*mode* argument, :func:`eval`\'s return value will be ``None``.
405
Hints: dynamic execution of statements is supported by the :func:`exec`
406
function. The :func:`globals` and :func:`locals` functions
407
returns the current global and local dictionary, respectively, which may be
408
useful to pass around for use by :func:`eval` or :func:`exec`.
410
See :func:`ast.literal_eval` for a function that can safely evaluate strings
411
with expressions containing only literals.
414
.. function:: exec(object[, globals[, locals]])
416
This function supports dynamic execution of Python code. *object* must be
417
either a string or a code object. If it is a string, the string is parsed as
418
a suite of Python statements which is then executed (unless a syntax error
419
occurs). [#]_ If it is a code object, it is simply executed. In all cases,
420
the code that's executed is expected to be valid as file input (see the
421
section "File input" in the Reference Manual). Be aware that the
422
:keyword:`return` and :keyword:`yield` statements may not be used outside of
423
function definitions even within the context of code passed to the
424
:func:`exec` function. The return value is ``None``.
426
In all cases, if the optional parts are omitted, the code is executed in the
427
current scope. If only *globals* is provided, it must be a dictionary, which
428
will be used for both the global and the local variables. If *globals* and
429
*locals* are given, they are used for the global and local variables,
430
respectively. If provided, *locals* can be any mapping object. Remember
431
that at module level, globals and locals are the same dictionary. If exec
432
gets two separate objects as *globals* and *locals*, the code will be
433
executed as if it were embedded in a class definition.
435
If the *globals* dictionary does not contain a value for the key
436
``__builtins__``, a reference to the dictionary of the built-in module
437
:mod:`builtins` is inserted under that key. That way you can control what
438
builtins are available to the executed code by inserting your own
439
``__builtins__`` dictionary into *globals* before passing it to :func:`exec`.
443
The built-in functions :func:`globals` and :func:`locals` return the current
444
global and local dictionary, respectively, which may be useful to pass around
445
for use as the second and third argument to :func:`exec`.
449
The default *locals* act as described for function :func:`locals` below:
450
modifications to the default *locals* dictionary should not be attempted.
451
Pass an explicit *locals* dictionary if you need to see effects of the
452
code on *locals* after function :func:`exec` returns.
455
.. function:: filter(function, iterable)
457
Construct an iterator from those elements of *iterable* for which *function*
458
returns true. *iterable* may be either a sequence, a container which
459
supports iteration, or an iterator. If *function* is ``None``, the identity
460
function is assumed, that is, all elements of *iterable* that are false are
463
Note that ``filter(function, iterable)`` is equivalent to the generator
464
expression ``(item for item in iterable if function(item))`` if function is
465
not ``None`` and ``(item for item in iterable if item)`` if function is
468
See :func:`itertools.filterfalse` for the complementary function that returns
469
elements of *iterable* for which *function* returns false.
472
.. function:: float([x])
478
Convert a string or a number to floating point.
480
If the argument is a string, it should contain a decimal number, optionally
481
preceded by a sign, and optionally embedded in whitespace. The optional
482
sign may be ``'+'`` or ``'-'``; a ``'+'`` sign has no effect on the value
483
produced. The argument may also be a string representing a NaN
484
(not-a-number), or a positive or negative infinity. More precisely, the
485
input must conform to the following grammar after leading and trailing
486
whitespace characters are removed:
490
infinity: "Infinity" | "inf"
492
numeric_value: `floatnumber` | `infinity` | `nan`
493
numeric_string: [`sign`] `numeric_value`
495
Here ``floatnumber`` is the form of a Python floating-point literal,
496
described in :ref:`floating`. Case is not significant, so, for example,
497
"inf", "Inf", "INFINITY" and "iNfINity" are all acceptable spellings for
500
Otherwise, if the argument is an integer or a floating point number, a
501
floating point number with the same value (within Python's floating point
502
precision) is returned. If the argument is outside the range of a Python
503
float, an :exc:`OverflowError` will be raised.
505
For a general Python object ``x``, ``float(x)`` delegates to
508
If no argument is given, ``0.0`` is returned.
514
>>> float(' -12345\n')
520
>>> float('-Infinity')
523
The float type is described in :ref:`typesnumeric`.
527
single: string; format() (built-in function)
530
.. function:: format(value[, format_spec])
532
Convert a *value* to a "formatted" representation, as controlled by
533
*format_spec*. The interpretation of *format_spec* will depend on the type
534
of the *value* argument, however there is a standard formatting syntax that
535
is used by most built-in types: :ref:`formatspec`.
537
The default *format_spec* is an empty string which usually gives the same
538
effect as calling :func:`str(value) <str>`.
540
A call to ``format(value, format_spec)`` is translated to
541
``type(value).__format__(format_spec)`` which bypasses the instance
542
dictionary when searching for the value's :meth:`__format__` method. A
543
:exc:`TypeError` exception is raised if the method is not found or if either
544
the *format_spec* or the return value are not strings.
546
.. versionadded:: 3.4
547
``object().__format__(format_spec)`` raises :exc:`TypeError`
548
if *format_spec* is not empty string.
552
.. function:: frozenset([iterable])
555
Return a new :class:`frozenset` object, optionally with elements taken from
556
*iterable*. ``frozenset`` is a built-in class. See :class:`frozenset` and
557
:ref:`types-set` for documentation about this class.
559
For other containers see the built-in :class:`set`, :class:`list`,
560
:class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections`
564
.. function:: getattr(object, name[, default])
566
Return the value of the named attribute of *object*. *name* must be a string.
567
If the string is the name of one of the object's attributes, the result is the
568
value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
569
``x.foobar``. If the named attribute does not exist, *default* is returned if
570
provided, otherwise :exc:`AttributeError` is raised.
573
.. function:: globals()
575
Return a dictionary representing the current global symbol table. This is always
576
the dictionary of the current module (inside a function or method, this is the
577
module where it is defined, not the module from which it is called).
580
.. function:: hasattr(object, name)
582
The arguments are an object and a string. The result is ``True`` if the
583
string is the name of one of the object's attributes, ``False`` if not. (This
584
is implemented by calling ``getattr(object, name)`` and seeing whether it
585
raises an :exc:`AttributeError` or not.)
588
.. function:: hash(object)
590
Return the hash value of the object (if it has one). Hash values are
591
integers. They are used to quickly compare dictionary keys during a
592
dictionary lookup. Numeric values that compare equal have the same hash
593
value (even if they are of different types, as is the case for 1 and 1.0).
597
For object's with custom :meth:`__hash__` methods, note that :func:`hash`
598
truncates the return value based on the bit width of the host machine.
599
See :meth:`__hash__` for details.
601
.. function:: help([object])
603
Invoke the built-in help system. (This function is intended for interactive
604
use.) If no argument is given, the interactive help system starts on the
605
interpreter console. If the argument is a string, then the string is looked up
606
as the name of a module, function, class, method, keyword, or documentation
607
topic, and a help page is printed on the console. If the argument is any other
608
kind of object, a help page on the object is generated.
610
This function is added to the built-in namespace by the :mod:`site` module.
615
Convert an integer number to a hexadecimal string. The result is a valid Python
616
expression. If *x* is not a Python :class:`int` object, it has to define an
617
:meth:`__index__` method that returns an integer.
621
To obtain a hexadecimal string representation for a float, use the
622
:meth:`float.hex` method.
625
.. function:: id(object)
627
Return the "identity" of an object. This is an integer which
628
is guaranteed to be unique and constant for this object during its lifetime.
629
Two objects with non-overlapping lifetimes may have the same :func:`id`
632
.. impl-detail:: This is the address of the object in memory.
635
.. function:: input([prompt])
637
If the *prompt* argument is present, it is written to standard output without
638
a trailing newline. The function then reads a line from input, converts it
639
to a string (stripping a trailing newline), and returns that. When EOF is
640
read, :exc:`EOFError` is raised. Example::
642
>>> s = input('--> ') # doctest: +SKIP
643
--> Monty Python's Flying Circus
644
>>> s # doctest: +SKIP
645
"Monty Python's Flying Circus"
647
If the :mod:`readline` module was loaded, then :func:`input` will use it
648
to provide elaborate line editing and history features.
651
.. function:: int(x=0)
654
Convert a number or string *x* to an integer, or return ``0`` if no
655
arguments are given. If *x* is a number, return :meth:`x.__int__()
656
<object.__int__>`. For floating point numbers, this truncates towards zero.
658
If *x* is not a number or if *base* is given, then *x* must be a string,
659
:class:`bytes`, or :class:`bytearray` instance representing an :ref:`integer
660
literal <integers>` in radix *base*. Optionally, the literal can be
661
preceded by ``+`` or ``-`` (with no space in between) and surrounded by
662
whitespace. A base-n literal consists of the digits 0 to n-1, with ``a``
663
to ``z`` (or ``A`` to ``Z``) having
664
values 10 to 35. The default *base* is 10. The allowed values are 0 and 2-36.
665
Base-2, -8, and -16 literals can be optionally prefixed with ``0b``/``0B``,
666
``0o``/``0O``, or ``0x``/``0X``, as with integer literals in code. Base 0
667
means to interpret exactly as a code literal, so that the actual base is 2,
668
8, 10, or 16, and so that ``int('010', 0)`` is not legal, while
669
``int('010')`` is, as well as ``int('010', 8)``.
671
The integer type is described in :ref:`typesnumeric`.
673
.. versionchanged:: 3.4
674
If *base* is not an instance of :class:`int` and the *base* object has a
675
:meth:`base.__index__ <object.__index__>` method, that method is called
676
to obtain an integer for the base. Previous versions used
677
:meth:`base.__int__ <object.__int__>` instead of :meth:`base.__index__
680
.. function:: isinstance(object, classinfo)
682
Return true if the *object* argument is an instance of the *classinfo*
683
argument, or of a (direct, indirect or :term:`virtual <abstract base
684
class>`) subclass thereof. If *object* is not
685
an object of the given type, the function always returns false. If
686
*classinfo* is not a class (type object), it may be a tuple of type objects,
687
or may recursively contain other such tuples (other sequence types are not
688
accepted). If *classinfo* is not a type or tuple of types and such tuples,
689
a :exc:`TypeError` exception is raised.
692
.. function:: issubclass(class, classinfo)
694
Return true if *class* is a subclass (direct, indirect or :term:`virtual
695
<abstract base class>`) of *classinfo*. A
696
class is considered a subclass of itself. *classinfo* may be a tuple of class
697
objects, in which case every entry in *classinfo* will be checked. In any other
698
case, a :exc:`TypeError` exception is raised.
701
.. function:: iter(object[, sentinel])
703
Return an :term:`iterator` object. The first argument is interpreted very
704
differently depending on the presence of the second argument. Without a
705
second argument, *object* must be a collection object which supports the
706
iteration protocol (the :meth:`__iter__` method), or it must support the
707
sequence protocol (the :meth:`__getitem__` method with integer arguments
708
starting at ``0``). If it does not support either of those protocols,
709
:exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
710
then *object* must be a callable object. The iterator created in this case
711
will call *object* with no arguments for each call to its
712
:meth:`~iterator.__next__` method; if the value returned is equal to
713
*sentinel*, :exc:`StopIteration` will be raised, otherwise the value will
716
See also :ref:`typeiter`.
718
One useful application of the second form of :func:`iter` is to read lines of
719
a file until a certain line is reached. The following example reads a file
720
until the :meth:`~io.TextIOBase.readline` method returns an empty string::
722
with open('mydata.txt') as fp:
723
for line in iter(fp.readline, ''):
729
Return the length (the number of items) of an object. The argument may be a
730
sequence (string, tuple or list) or a mapping (dictionary).
734
.. function:: list([iterable])
737
Rather than being a function, :class:`list` is actually a mutable
738
sequence type, as documented in :ref:`typesseq-list` and :ref:`typesseq`.
741
.. function:: locals()
743
Update and return a dictionary representing the current local symbol table.
744
Free variables are returned by :func:`locals` when it is called in function
745
blocks, but not in class blocks.
748
The contents of this dictionary should not be modified; changes may not
749
affect the values of local and free variables used by the interpreter.
751
.. function:: map(function, iterable, ...)
753
Return an iterator that applies *function* to every item of *iterable*,
754
yielding the results. If additional *iterable* arguments are passed,
755
*function* must take that many arguments and is applied to the items from all
756
iterables in parallel. With multiple iterables, the iterator stops when the
757
shortest iterable is exhausted. For cases where the function inputs are
758
already arranged into argument tuples, see :func:`itertools.starmap`\.
761
.. function:: max(iterable, *[, default, key])
762
max(arg1, arg2, *args[, key])
764
Return the largest item in an iterable or the largest of two or more
767
If one positional argument is provided, it should be an :term:`iterable`.
768
The largest item in the iterable is returned. If two or more positional
769
arguments are provided, the smallest of the positional arguments is
772
There are two optional keyword-only arguments. The *key* argument specifies
773
a one-argument ordering function like that used for :meth:`list.sort`. The
774
*default* argument specifies an object to return if the provided iterable is
775
empty. If the iterable is empty and *default* is not provided, a
776
:exc:`ValueError` is raised.
778
If multiple items are maximal, the function returns the first one
779
encountered. This is consistent with other sort-stability preserving tools
780
such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and
781
``heapq.nlargest(1, iterable, key=keyfunc)``.
785
.. function:: memoryview(obj)
788
Return a "memory view" object created from the given argument. See
789
:ref:`typememoryview` for more information.
792
.. function:: min(iterable, *[, default, key])
793
min(arg1, arg2, *args[, key])
795
Return the smallest item in an iterable or the smallest of two or more
798
If one positional argument is provided, it should be an :term:`iterable`.
799
The smallest item in the iterable is returned. If two or more positional
800
arguments are provided, the smallest of the positional arguments is
803
There are two optional keyword-only arguments. The *key* argument specifies
804
a one-argument ordering function like that used for :meth:`list.sort`. The
805
*default* argument specifies an object to return if the provided iterable is
806
empty. If the iterable is empty and *default* is not provided, a
807
:exc:`ValueError` is raised.
809
If multiple items are minimal, the function returns the first one
810
encountered. This is consistent with other sort-stability preserving tools
811
such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1,
812
iterable, key=keyfunc)``.
814
.. function:: next(iterator[, default])
816
Retrieve the next item from the *iterator* by calling its
817
:meth:`~iterator.__next__` method. If *default* is given, it is returned
818
if the iterator is exhausted, otherwise :exc:`StopIteration` is raised.
821
.. function:: object()
823
Return a new featureless object. :class:`object` is a base for all classes.
824
It has the methods that are common to all instances of Python classes. This
825
function does not accept any arguments.
829
:class:`object` does *not* have a :attr:`~object.__dict__`, so you can't
830
assign arbitrary attributes to an instance of the :class:`object` class.
835
Convert an integer number to an octal string. The result is a valid Python
836
expression. If *x* is not a Python :class:`int` object, it has to define an
837
:meth:`__index__` method that returns an integer.
841
single: file object; open() built-in function
843
.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)
845
Open *file* and return a corresponding :term:`file object`. If the file
846
cannot be opened, an :exc:`OSError` is raised.
848
*file* is either a string or bytes object giving the pathname (absolute or
849
relative to the current working directory) of the file to be opened or
850
an integer file descriptor of the file to be wrapped. (If a file descriptor
851
is given, it is closed when the returned I/O object is closed, unless
852
*closefd* is set to ``False``.)
854
*mode* is an optional string that specifies the mode in which the file is
855
opened. It defaults to ``'r'`` which means open for reading in text mode.
856
Other common values are ``'w'`` for writing (truncating the file if it
857
already exists), ``'x'`` for exclusive creation and ``'a'`` for appending
858
(which on *some* Unix systems, means that *all* writes append to the end of
859
the file regardless of the current seek position). In text mode, if
860
*encoding* is not specified the encoding used is platform dependent:
861
``locale.getpreferredencoding(False)`` is called to get the current locale
862
encoding. (For reading and writing raw bytes use binary mode and leave
863
*encoding* unspecified.) The available modes are:
865
========= ===============================================================
867
========= ===============================================================
868
``'r'`` open for reading (default)
869
``'w'`` open for writing, truncating the file first
870
``'x'`` open for exclusive creation, failing if the file already exists
871
``'a'`` open for writing, appending to the end of the file if it exists
873
``'t'`` text mode (default)
874
``'+'`` open a disk file for updating (reading and writing)
875
``'U'`` :term:`universal newlines` mode (deprecated)
876
========= ===============================================================
878
The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``).
879
For binary read-write access, the mode ``'w+b'`` opens and truncates the file
880
to 0 bytes. ``'r+b'`` opens the file without truncation.
882
As mentioned in the :ref:`io-overview`, Python distinguishes between binary
883
and text I/O. Files opened in binary mode (including ``'b'`` in the *mode*
884
argument) return contents as :class:`bytes` objects without any decoding. In
885
text mode (the default, or when ``'t'`` is included in the *mode* argument),
886
the contents of the file are returned as :class:`str`, the bytes having been
887
first decoded using a platform-dependent encoding or using the specified
892
Python doesn't depend on the underlying operating system's notion of text
893
files; all the processing is done by Python itself, and is therefore
894
platform-independent.
896
*buffering* is an optional integer used to set the buffering policy. Pass 0
897
to switch buffering off (only allowed in binary mode), 1 to select line
898
buffering (only usable in text mode), and an integer > 1 to indicate the size
899
in bytes of a fixed-size chunk buffer. When no *buffering* argument is
900
given, the default buffering policy works as follows:
902
* Binary files are buffered in fixed-size chunks; the size of the buffer is
903
chosen using a heuristic trying to determine the underlying device's "block
904
size" and falling back on :attr:`io.DEFAULT_BUFFER_SIZE`. On many systems,
905
the buffer will typically be 4096 or 8192 bytes long.
907
* "Interactive" text files (files for which :meth:`~io.IOBase.isatty`
908
returns True) use line buffering. Other text files use the policy
909
described above for binary files.
911
*encoding* is the name of the encoding used to decode or encode the file.
912
This should only be used in text mode. The default encoding is platform
913
dependent (whatever :func:`locale.getpreferredencoding` returns), but any
914
encoding supported by Python can be used. See the :mod:`codecs` module for
915
the list of supported encodings.
917
*errors* is an optional string that specifies how encoding and decoding
918
errors are to be handled--this cannot be used in binary mode.
919
A variety of standard error handlers are available, though any
920
error handling name that has been registered with
921
:func:`codecs.register_error` is also valid. The standard names
924
* ``'strict'`` to raise a :exc:`ValueError` exception if there is
925
an encoding error. The default value of ``None`` has the same
928
* ``'ignore'`` ignores errors. Note that ignoring encoding errors
929
can lead to data loss.
931
* ``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted
932
where there is malformed data.
934
* ``'surrogateescape'`` will represent any incorrect bytes as code
935
points in the Unicode Private Use Area ranging from U+DC80 to
936
U+DCFF. These private code points will then be turned back into
937
the same bytes when the ``surrogateescape`` error handler is used
938
when writing data. This is useful for processing files in an
941
* ``'xmlcharrefreplace'`` is only supported when writing to a file.
942
Characters not supported by the encoding are replaced with the
943
appropriate XML character reference ``&#nnn;``.
945
* ``'backslashreplace'`` (also only supported when writing)
946
replaces unsupported characters with Python's backslashed escape
950
single: universal newlines; open() built-in function
952
*newline* controls how :term:`universal newlines` mode works (it only
953
applies to text mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and
954
``'\r\n'``. It works as follows:
956
* When reading input from the stream, if *newline* is ``None``, universal
957
newlines mode is enabled. Lines in the input can end in ``'\n'``,
958
``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` before
959
being returned to the caller. If it is ``''``, universal newlines mode is
960
enabled, but line endings are returned to the caller untranslated. If it
961
has any of the other legal values, input lines are only terminated by the
962
given string, and the line ending is returned to the caller untranslated.
964
* When writing output to the stream, if *newline* is ``None``, any ``'\n'``
965
characters written are translated to the system default line separator,
966
:data:`os.linesep`. If *newline* is ``''`` or ``'\n'``, no translation
967
takes place. If *newline* is any of the other legal values, any ``'\n'``
968
characters written are translated to the given string.
970
If *closefd* is ``False`` and a file descriptor rather than a filename was
971
given, the underlying file descriptor will be kept open when the file is
972
closed. If a filename is given *closefd* has no effect and must be ``True``
975
A custom opener can be used by passing a callable as *opener*. The underlying
976
file descriptor for the file object is then obtained by calling *opener* with
977
(*file*, *flags*). *opener* must return an open file descriptor (passing
978
:mod:`os.open` as *opener* results in functionality similar to passing
981
The newly created file is :ref:`non-inheritable <fd_inheritance>`.
983
The following example uses the :ref:`dir_fd <dir_fd>` parameter of the
984
:func:`os.open` function to open a file relative to a given directory::
987
>>> dir_fd = os.open('somedir', os.O_RDONLY)
988
>>> def opener(path, flags):
989
... return os.open(path, flags, dir_fd=dir_fd)
991
>>> with open('spamspam.txt', 'w', opener=opener) as f:
992
... print('This will be written to somedir/spamspam.txt', file=f)
994
>>> os.close(dir_fd) # don't leak a file descriptor
996
The type of :term:`file object` returned by the :func:`open` function
997
depends on the mode. When :func:`open` is used to open a file in a text
998
mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
999
:class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used
1000
to open a file in a binary mode with buffering, the returned class is a
1001
subclass of :class:`io.BufferedIOBase`. The exact class varies: in read
1002
binary mode, it returns a :class:`io.BufferedReader`; in write binary and
1003
append binary modes, it returns a :class:`io.BufferedWriter`, and in
1004
read/write mode, it returns a :class:`io.BufferedRandom`. When buffering is
1005
disabled, the raw stream, a subclass of :class:`io.RawIOBase`,
1006
:class:`io.FileIO`, is returned.
1009
single: line-buffered I/O
1010
single: unbuffered I/O
1011
single: buffer size, I/O
1012
single: I/O control; buffering
1017
See also the file handling modules, such as, :mod:`fileinput`, :mod:`io`
1018
(where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:`tempfile`,
1021
.. versionchanged:: 3.3
1022
The *opener* parameter was added.
1023
The ``'x'`` mode was added.
1024
:exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`.
1025
:exc:`FileExistsError` is now raised if the file opened in exclusive
1026
creation mode (``'x'``) already exists.
1028
.. versionchanged:: 3.4
1029
The file is now non-inheritable.
1031
.. deprecated-removed:: 3.4 4.0
1035
.. XXX works for bytes too, but should it?
1036
.. function:: ord(c)
1038
Given a string representing one Unicode character, return an integer
1039
representing the Unicode code
1040
point of that character. For example, ``ord('a')`` returns the integer ``97``
1041
and ``ord('\u2020')`` returns ``8224``. This is the inverse of :func:`chr`.
1044
.. function:: pow(x, y[, z])
1046
Return *x* to the power *y*; if *z* is present, return *x* to the power *y*,
1047
modulo *z* (computed more efficiently than ``pow(x, y) % z``). The two-argument
1048
form ``pow(x, y)`` is equivalent to using the power operator: ``x**y``.
1050
The arguments must have numeric types. With mixed operand types, the
1051
coercion rules for binary arithmetic operators apply. For :class:`int`
1052
operands, the result has the same type as the operands (after coercion)
1053
unless the second argument is negative; in that case, all arguments are
1054
converted to float and a float result is delivered. For example, ``10**2``
1055
returns ``100``, but ``10**-2`` returns ``0.01``. If the second argument is
1056
negative, the third argument must be omitted. If *z* is present, *x* and *y*
1057
must be of integer types, and *y* must be non-negative.
1060
.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout, flush=False)
1062
Print *objects* to the stream *file*, separated by *sep* and followed by
1063
*end*. *sep*, *end* and *file*, if present, must be given as keyword
1066
All non-keyword arguments are converted to strings like :func:`str` does and
1067
written to the stream, separated by *sep* and followed by *end*. Both *sep*
1068
and *end* must be strings; they can also be ``None``, which means to use the
1069
default values. If no *objects* are given, :func:`print` will just write
1072
The *file* argument must be an object with a ``write(string)`` method; if it
1073
is not present or ``None``, :data:`sys.stdout` will be used. Whether output
1074
is buffered is usually determined by *file*, but if the *flush* keyword
1075
argument is true, the stream is forcibly flushed.
1077
.. versionchanged:: 3.3
1078
Added the *flush* keyword argument.
1081
.. function:: property(fget=None, fset=None, fdel=None, doc=None)
1083
Return a property attribute.
1085
*fget* is a function for getting an attribute value, likewise *fset* is a
1086
function for setting, and *fdel* a function for del'ing, an attribute. Typical
1087
use is to define a managed attribute ``x``::
1095
def setx(self, value):
1099
x = property(getx, setx, delx, "I'm the 'x' property.")
1101
If then *c* is an instance of *C*, ``c.x`` will invoke the getter,
1102
``c.x = value`` will invoke the setter and ``del c.x`` the deleter.
1104
If given, *doc* will be the docstring of the property attribute. Otherwise, the
1105
property will copy *fget*'s docstring (if it exists). This makes it possible to
1106
create read-only properties easily using :func:`property` as a :term:`decorator`::
1110
self._voltage = 100000
1114
"""Get the current voltage."""
1115
return self._voltage
1117
turns the :meth:`voltage` method into a "getter" for a read-only attribute
1120
A property object has :attr:`~property.getter`, :attr:`~property.setter`,
1121
and :attr:`~property.deleter` methods usable as decorators that create a
1122
copy of the property with the corresponding accessor function set to the
1123
decorated function. This is best explained with an example::
1131
"""I'm the 'x' property."""
1142
This code is exactly equivalent to the first example. Be sure to give the
1143
additional functions the same name as the original property (``x`` in this
1146
The returned property also has the attributes ``fget``, ``fset``, and
1147
``fdel`` corresponding to the constructor arguments.
1151
.. function:: range(stop)
1152
range(start, stop[, step])
1155
Rather than being a function, :class:`range` is actually an immutable
1156
sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`.
1159
.. function:: repr(object)
1161
Return a string containing a printable representation of an object. For many
1162
types, this function makes an attempt to return a string that would yield an
1163
object with the same value when passed to :func:`eval`, otherwise the
1164
representation is a string enclosed in angle brackets that contains the name
1165
of the type of the object together with additional information often
1166
including the name and address of the object. A class can control what this
1167
function returns for its instances by defining a :meth:`__repr__` method.
1170
.. function:: reversed(seq)
1172
Return a reverse :term:`iterator`. *seq* must be an object which has
1173
a :meth:`__reversed__` method or supports the sequence protocol (the
1174
:meth:`__len__` method and the :meth:`__getitem__` method with integer
1175
arguments starting at ``0``).
1178
.. function:: round(number[, ndigits])
1180
Return the floating point value *number* rounded to *ndigits* digits after
1181
the decimal point. If *ndigits* is omitted, it defaults to zero. Delegates
1182
to ``number.__round__(ndigits)``.
1184
For the built-in types supporting :func:`round`, values are rounded to the
1185
closest multiple of 10 to the power minus *ndigits*; if two multiples are
1186
equally close, rounding is done toward the even choice (so, for example,
1187
both ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is
1188
``2``). The return value is an integer if called with one argument,
1189
otherwise of the same type as *number*.
1193
The behavior of :func:`round` for floats can be surprising: for example,
1194
``round(2.675, 2)`` gives ``2.67`` instead of the expected ``2.68``.
1195
This is not a bug: it's a result of the fact that most decimal fractions
1196
can't be represented exactly as a float. See :ref:`tut-fp-issues` for
1201
.. function:: set([iterable])
1204
Return a new :class:`set` object, optionally with elements taken from
1205
*iterable*. ``set`` is a built-in class. See :class:`set` and
1206
:ref:`types-set` for documentation about this class.
1208
For other containers see the built-in :class:`frozenset`, :class:`list`,
1209
:class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections`
1213
.. function:: setattr(object, name, value)
1215
This is the counterpart of :func:`getattr`. The arguments are an object, a
1216
string and an arbitrary value. The string may name an existing attribute or a
1217
new attribute. The function assigns the value to the attribute, provided the
1218
object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to
1222
.. function:: slice(stop)
1223
slice(start, stop[, step])
1225
.. index:: single: Numerical Python
1227
Return a :term:`slice` object representing the set of indices specified by
1228
``range(start, stop, step)``. The *start* and *step* arguments default to
1229
``None``. Slice objects have read-only data attributes :attr:`~slice.start`,
1230
:attr:`~slice.stop` and :attr:`~slice.step` which merely return the argument
1231
values (or their default). They have no other explicit functionality;
1232
however they are used by Numerical Python and other third party extensions.
1233
Slice objects are also generated when extended indexing syntax is used. For
1234
example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See
1235
:func:`itertools.islice` for an alternate version that returns an iterator.
1238
.. function:: sorted(iterable[, key][, reverse])
1240
Return a new sorted list from the items in *iterable*.
1242
Has two optional arguments which must be specified as keyword arguments.
1244
*key* specifies a function of one argument that is used to extract a comparison
1245
key from each list element: ``key=str.lower``. The default value is ``None``
1246
(compare the elements directly).
1248
*reverse* is a boolean value. If set to ``True``, then the list elements are
1249
sorted as if each comparison were reversed.
1251
Use :func:`functools.cmp_to_key` to convert an old-style *cmp* function to a
1254
For sorting examples and a brief sorting tutorial, see `Sorting HowTo
1255
<http://wiki.python.org/moin/HowTo/Sorting/>`_\.
1257
.. function:: staticmethod(function)
1259
Return a static method for *function*.
1261
A static method does not receive an implicit first argument. To declare a static
1262
method, use this idiom::
1266
def f(arg1, arg2, ...): ...
1268
The ``@staticmethod`` form is a function :term:`decorator` -- see the
1269
description of function definitions in :ref:`function` for details.
1271
It can be called either on the class (such as ``C.f()``) or on an instance (such
1272
as ``C().f()``). The instance is ignored except for its class.
1274
Static methods in Python are similar to those found in Java or C++. Also see
1275
:func:`classmethod` for a variant that is useful for creating alternate class
1278
For more information on static methods, consult the documentation on the
1279
standard type hierarchy in :ref:`types`.
1282
single: string; str() (built-in function)
1286
.. function:: str(object='')
1287
str(object=b'', encoding='utf-8', errors='strict')
1290
Return a :class:`str` version of *object*. See :func:`str` for details.
1292
``str`` is the built-in string :term:`class`. For general information
1293
about strings, see :ref:`textseq`.
1296
.. function:: sum(iterable[, start])
1298
Sums *start* and the items of an *iterable* from left to right and returns the
1299
total. *start* defaults to ``0``. The *iterable*'s items are normally numbers,
1300
and the start value is not allowed to be a string.
1302
For some use cases, there are good alternatives to :func:`sum`.
1303
The preferred, fast way to concatenate a sequence of strings is by calling
1304
``''.join(sequence)``. To add floating point values with extended precision,
1305
see :func:`math.fsum`\. To concatenate a series of iterables, consider using
1306
:func:`itertools.chain`.
1308
.. function:: super([type[, object-or-type]])
1310
Return a proxy object that delegates method calls to a parent or sibling
1311
class of *type*. This is useful for accessing inherited methods that have
1312
been overridden in a class. The search order is same as that used by
1313
:func:`getattr` except that the *type* itself is skipped.
1315
The :attr:`~class.__mro__` attribute of the *type* lists the method
1316
resolution search order used by both :func:`getattr` and :func:`super`. The
1317
attribute is dynamic and can change whenever the inheritance hierarchy is
1320
If the second argument is omitted, the super object returned is unbound. If
1321
the second argument is an object, ``isinstance(obj, type)`` must be true. If
1322
the second argument is a type, ``issubclass(type2, type)`` must be true (this
1323
is useful for classmethods).
1325
There are two typical use cases for *super*. In a class hierarchy with
1326
single inheritance, *super* can be used to refer to parent classes without
1327
naming them explicitly, thus making the code more maintainable. This use
1328
closely parallels the use of *super* in other programming languages.
1330
The second use case is to support cooperative multiple inheritance in a
1331
dynamic execution environment. This use case is unique to Python and is
1332
not found in statically compiled languages or languages that only support
1333
single inheritance. This makes it possible to implement "diamond diagrams"
1334
where multiple base classes implement the same method. Good design dictates
1335
that this method have the same calling signature in every case (because the
1336
order of calls is determined at runtime, because that order adapts
1337
to changes in the class hierarchy, and because that order can include
1338
sibling classes that are unknown prior to runtime).
1340
For both use cases, a typical superclass call looks like this::
1343
def method(self, arg):
1344
super().method(arg) # This does the same thing as:
1345
# super(C, self).method(arg)
1347
Note that :func:`super` is implemented as part of the binding process for
1348
explicit dotted attribute lookups such as ``super().__getitem__(name)``.
1349
It does so by implementing its own :meth:`__getattribute__` method for searching
1350
classes in a predictable order that supports cooperative multiple inheritance.
1351
Accordingly, :func:`super` is undefined for implicit lookups using statements or
1352
operators such as ``super()[name]``.
1354
Also note that, aside from the zero argument form, :func:`super` is not
1355
limited to use inside methods. The two argument form specifies the
1356
arguments exactly and makes the appropriate references. The zero
1357
argument form only works inside a class definition, as the compiler fills
1358
in the necessary details to correctly retrieve the class being defined,
1359
as well as accessing the current instance for ordinary methods.
1361
For practical suggestions on how to design cooperative classes using
1362
:func:`super`, see `guide to using super()
1363
<http://rhettinger.wordpress.com/2011/05/26/super-considered-super/>`_.
1367
.. function:: tuple([iterable])
1370
Rather than being a function, :class:`tuple` is actually an immutable
1371
sequence type, as documented in :ref:`typesseq-tuple` and :ref:`typesseq`.
1374
.. function:: type(object)
1375
type(name, bases, dict)
1377
.. index:: object: type
1380
With one argument, return the type of an *object*. The return value is a
1381
type object and generally the same object as returned by
1382
:attr:`object.__class__ <instance.__class__>`.
1384
The :func:`isinstance` built-in function is recommended for testing the type
1385
of an object, because it takes subclasses into account.
1388
With three arguments, return a new type object. This is essentially a
1389
dynamic form of the :keyword:`class` statement. The *name* string is the
1390
class name and becomes the :attr:`~class.__name__` attribute; the *bases*
1391
tuple itemizes the base classes and becomes the :attr:`~class.__bases__`
1392
attribute; and the *dict* dictionary is the namespace containing definitions
1393
for class body and becomes the :attr:`~object.__dict__` attribute. For
1394
example, the following two statements create identical :class:`type` objects:
1399
>>> X = type('X', (object,), dict(a=1))
1401
See also :ref:`bltin-type-objects`.
1404
.. function:: vars([object])
1406
Return the :attr:`~object.__dict__` attribute for a module, class, instance,
1407
or any other object with a :attr:`__dict__` attribute.
1409
Objects such as modules and instances have an updateable :attr:`__dict__`
1410
attribute; however, other objects may have write restrictions on their
1411
:attr:`__dict__` attributes (for example, classes use a
1412
dictproxy to prevent direct dictionary updates).
1414
Without an argument, :func:`vars` acts like :func:`locals`. Note, the
1415
locals dictionary is only useful for reads since updates to the locals
1416
dictionary are ignored.
1419
.. function:: zip(*iterables)
1421
Make an iterator that aggregates elements from each of the iterables.
1423
Returns an iterator of tuples, where the *i*-th tuple contains
1424
the *i*-th element from each of the argument sequences or iterables. The
1425
iterator stops when the shortest input iterable is exhausted. With a single
1426
iterable argument, it returns an iterator of 1-tuples. With no arguments,
1427
it returns an empty iterator. Equivalent to::
1429
def zip(*iterables):
1430
# zip('ABCD', 'xy') --> Ax By
1432
iterators = [iter(it) for it in iterables]
1435
for it in iterators:
1436
elem = next(it, sentinel)
1437
if elem is sentinel:
1442
The left-to-right evaluation order of the iterables is guaranteed. This
1443
makes possible an idiom for clustering a data series into n-length groups
1444
using ``zip(*[iter(s)]*n)``.
1446
:func:`zip` should only be used with unequal length inputs when you don't
1447
care about trailing, unmatched values from the longer iterables. If those
1448
values are important, use :func:`itertools.zip_longest` instead.
1450
:func:`zip` in conjunction with the ``*`` operator can be used to unzip a
1455
>>> zipped = zip(x, y)
1457
[(1, 4), (2, 5), (3, 6)]
1458
>>> x2, y2 = zip(*zip(x, y))
1459
>>> x == list(x2) and y == list(y2)
1463
.. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0)
1471
This is an advanced function that is not needed in everyday Python
1472
programming, unlike :func:`importlib.import_module`.
1474
This function is invoked by the :keyword:`import` statement. It can be
1475
replaced (by importing the :mod:`builtins` module and assigning to
1476
``builtins.__import__``) in order to change semantics of the
1477
:keyword:`import` statement, but doing so is **strongly** discouraged as it
1478
is usually simpler to use import hooks (see :pep:`302`) to attain the same
1479
goals and does not cause issues with code which assumes the default import
1480
implementation is in use. Direct use of :func:`__import__` is also
1481
discouraged in favor of :func:`importlib.import_module`.
1483
The function imports the module *name*, potentially using the given *globals*
1484
and *locals* to determine how to interpret the name in a package context.
1485
The *fromlist* gives the names of objects or submodules that should be
1486
imported from the module given by *name*. The standard implementation does
1487
not use its *locals* argument at all, and uses its *globals* only to
1488
determine the package context of the :keyword:`import` statement.
1490
*level* specifies whether to use absolute or relative imports. ``0`` (the
1491
default) means only perform absolute imports. Positive values for
1492
*level* indicate the number of parent directories to search relative to the
1493
directory of the module calling :func:`__import__` (see :pep:`328` for the
1496
When the *name* variable is of the form ``package.module``, normally, the
1497
top-level package (the name up till the first dot) is returned, *not* the
1498
module named by *name*. However, when a non-empty *fromlist* argument is
1499
given, the module named by *name* is returned.
1501
For example, the statement ``import spam`` results in bytecode resembling the
1504
spam = __import__('spam', globals(), locals(), [], 0)
1506
The statement ``import spam.ham`` results in this call::
1508
spam = __import__('spam.ham', globals(), locals(), [], 0)
1510
Note how :func:`__import__` returns the toplevel module here because this is
1511
the object that is bound to a name by the :keyword:`import` statement.
1513
On the other hand, the statement ``from spam.ham import eggs, sausage as
1514
saus`` results in ::
1516
_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
1518
saus = _temp.sausage
1520
Here, the ``spam.ham`` module is returned from :func:`__import__`. From this
1521
object, the names to import are retrieved and assigned to their respective
1524
If you simply want to import a module (potentially within a package) by name,
1525
use :func:`importlib.import_module`.
1527
.. versionchanged:: 3.3
1528
Negative values for *level* are no longer supported (which also changes
1529
the default value to 0).
1532
.. rubric:: Footnotes
1534
.. [#] Note that the parser only accepts the Unix-style end of line convention.
1535
If you are reading the code from a file, make sure to use newline conversion
1536
mode to convert Windows or Mac-style newlines.
added
removed
Doc/library/functions.rst
