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.
13 Return the absolute value of a number. The argument may be an
14 integer or a floating point number. If the argument is a complex number, its
15 magnitude is returned.
18 .. function:: all(iterable)
20 Return True if all elements of the *iterable* are true (or if the iterable
21 is empty). Equivalent to::
24 for element in iterable:
30 .. function:: any(iterable)
32 Return True if any element of the *iterable* is true. If the iterable
33 is empty, return False. Equivalent to::
36 for element in iterable:
42 .. function:: ascii(object)
44 As :func:`repr`, return a string containing a printable representation of an
45 object, but escape the non-ASCII characters in the string returned by
46 :func:`repr` using ``\x``, ``\u`` or ``\U`` escapes. This generates a string
47 similar to that returned by :func:`repr` in Python 2.
52 Convert an integer number to a binary string. The result is a valid Python
53 expression. If *x* is not a Python :class:`int` object, it has to define an
54 :meth:`__index__` method that returns an integer.
57 .. function:: bool([x])
59 Convert a value to a Boolean, using the standard truth testing procedure. If
60 *x* is false or omitted, this returns :const:`False`; otherwise it returns
61 :const:`True`. :class:`bool` is also a class, which is a subclass of
62 :class:`int`. Class :class:`bool` cannot be subclassed further. Its only
63 instances are :const:`False` and :const:`True`.
65 .. index:: pair: Boolean; type
68 .. function:: bytearray([source[, encoding[, errors]]])
70 Return a new array of bytes. The :class:`bytearray` type is a mutable
71 sequence of integers in the range 0 <= x < 256. It has most of the usual
72 methods of mutable sequences, described in :ref:`typesseq-mutable`, as well
73 as most methods that the :class:`str` type has, see :ref:`bytes-methods`.
75 The optional *source* parameter can be used to initialize the array in a few
78 * If it is a *string*, you must also give the *encoding* (and optionally,
79 *errors*) parameters; :func:`bytearray` then converts the string to
80 bytes using :meth:`str.encode`.
82 * If it is an *integer*, the array will have that size and will be
83 initialized with null bytes.
85 * If it is an object conforming to the *buffer* interface, a read-only buffer
86 of the object will be used to initialize the bytes array.
88 * If it is an *iterable*, it must be an iterable of integers in the range
89 ``0 <= x < 256``, which are used as the initial contents of the array.
91 Without an argument, an array of size 0 is created.
94 .. function:: bytes([source[, encoding[, errors]]])
96 Return a new "bytes" object, which is an immutable sequence of integers in
97 the range ``0 <= x < 256``. :class:`bytes` is an immutable version of
98 :class:`bytearray` -- it has the same non-mutating methods and the same
99 indexing and slicing behavior.
101 Accordingly, constructor arguments are interpreted as for :func:`bytearray`.
103 Bytes objects can also be created with literals, see :ref:`strings`.
108 Return the string of one character whose Unicode codepoint is the integer
109 *i*. For example, ``chr(97)`` returns the string ``'a'``. This is the
110 inverse of :func:`ord`. The valid range for the argument depends how Python
111 was configured -- it may be either UCS2 [0..0xFFFF] or UCS4 [0..0x10FFFF].
112 :exc:`ValueError` will be raised if *i* is outside that range.
115 .. function:: classmethod(function)
117 Return a class method for *function*.
119 A class method receives the class as implicit first argument, just like an
120 instance method receives the instance. To declare a class method, use this
125 def f(cls, arg1, arg2, ...): ...
127 The ``@classmethod`` form is a function :term:`decorator` -- see the description
128 of function definitions in :ref:`function` for details.
130 It can be called either on the class (such as ``C.f()``) or on an instance (such
131 as ``C().f()``). The instance is ignored except for its class. If a class
132 method is called for a derived class, the derived class object is passed as the
133 implied first argument.
135 Class methods are different than C++ or Java static methods. If you want those,
136 see :func:`staticmethod` in this section.
138 For more information on class methods, consult the documentation on the standard
139 type hierarchy in :ref:`types`.
142 .. function:: compile(source, filename, mode, flags=0, dont_inherit=False)
144 Compile the *source* into a code or AST object. Code objects can be executed
145 by:func:`exec` or :func:`eval`. *source* can either be a string or an AST
146 object. Refer to the :mod:`ast` module documentation for information on how
147 to work with AST objects.
149 The *filename* argument should give the file from which the code was read;
150 pass some recognizable value if it wasn't read from a file (``'<string>'`` is
153 The *mode* argument specifies what kind of code must be compiled; it can be
154 ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
155 consists of a single expression, or ``'single'`` if it consists of a single
156 interactive statement (in the latter case, expression statements that
157 evaluate to something other than ``None`` will be printed).
159 The optional arguments *flags* and *dont_inherit* control which future
160 statements (see :pep:`236`) affect the compilation of *source*. If neither
161 is present (or both are zero) the code is compiled with those future
162 statements that are in effect in the code that is calling compile. If the
163 *flags* argument is given and *dont_inherit* is not (or is zero) then the
164 future statements specified by the *flags* argument are used in addition to
165 those that would be used anyway. If *dont_inherit* is a non-zero integer then
166 the *flags* argument is it -- the future statements in effect around the call
167 to compile are ignored.
169 Future statements are specified by bits which can be bitwise ORed together to
170 specify multiple statements. The bitfield required to specify a given feature
171 can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
172 instance in the :mod:`__future__` module.
174 This function raises :exc:`SyntaxError` if the compiled source is invalid,
175 and :exc:`TypeError` if the source contains null bytes.
179 When compiling a string with multi-line statements, line endings must be
180 represented by a single newline character (``'\n'``), and the input must
181 be terminated by at least one newline character. If line endings are
182 represented by ``'\r\n'``, use :meth:`str.replace` to change them into
186 .. function:: complex([real[, imag]])
188 Create a complex number with the value *real* + *imag*\*j or convert a string or
189 number to a complex number. If the first parameter is a string, it will be
190 interpreted as a complex number and the function must be called without a second
191 parameter. The second parameter can never be a string. Each argument may be any
192 numeric type (including complex). If *imag* is omitted, it defaults to zero and
193 the function serves as a numeric conversion function like :func:`int`
194 and :func:`float`. If both arguments are omitted, returns ``0j``.
196 The complex type is described in :ref:`typesnumeric`.
199 .. function:: delattr(object, name)
201 This is a relative of :func:`setattr`. The arguments are an object and a
202 string. The string must be the name of one of the object's attributes. The
203 function deletes the named attribute, provided the object allows it. For
204 example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
207 .. function:: dict([arg])
210 Create a new data dictionary, optionally with items taken from *arg*.
211 The dictionary type is described in :ref:`typesmapping`.
213 For other containers see the built in :class:`list`, :class:`set`, and
214 :class:`tuple` classes, and the :mod:`collections` module.
217 .. function:: dir([object])
219 Without arguments, return the list of names in the current local scope. With an
220 argument, attempt to return a list of valid attributes for that object.
222 If the object has a method named :meth:`__dir__`, this method will be called and
223 must return the list of attributes. This allows objects that implement a custom
224 :func:`__getattr__` or :func:`__getattribute__` function to customize the way
225 :func:`dir` reports their attributes.
227 If the object does not provide :meth:`__dir__`, the function tries its best to
228 gather information from the object's :attr:`__dict__` attribute, if defined, and
229 from its type object. The resulting list is not necessarily complete, and may
230 be inaccurate when the object has a custom :func:`__getattr__`.
232 The default :func:`dir` mechanism behaves differently with different types of
233 objects, as it attempts to produce the most relevant, rather than complete,
236 * If the object is a module object, the list contains the names of the module's
239 * If the object is a type or class object, the list contains the names of its
240 attributes, and recursively of the attributes of its bases.
242 * Otherwise, the list contains the object's attributes' names, the names of its
243 class's attributes, and recursively of the attributes of its class's base
246 The resulting list is sorted alphabetically. For example:
249 >>> dir() # doctest: +SKIP
250 ['__builtins__', '__doc__', '__name__', 'struct']
251 >>> dir(struct) # doctest: +NORMALIZE_WHITESPACE
252 ['Struct', '__builtins__', '__doc__', '__file__', '__name__',
253 '__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
254 'unpack', 'unpack_from']
255 >>> class Foo(object):
256 ... def __dir__(self):
257 ... return ["kan", "ga", "roo"]
265 Because :func:`dir` is supplied primarily as a convenience for use at an
266 interactive prompt, it tries to supply an interesting set of names more
267 than it tries to supply a rigorously or consistently defined set of names,
268 and its detailed behavior may change across releases. For example,
269 metaclass attributes are not in the result list when the argument is a
273 .. function:: divmod(a, b)
275 Take two (non complex) numbers as arguments and return a pair of numbers
276 consisting of their quotient and remainder when using integer division. With
277 mixed operand types, the rules for binary arithmetic operators apply. For
278 integers, the result is the same as ``(a // b, a % b)``. For floating point
279 numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a /
280 b)`` but may be 1 less than that. In any case ``q * b + a % b`` is very
281 close to *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0
282 <= abs(a % b) < abs(b)``.
285 .. function:: enumerate(iterable, start=0)
287 Return an enumerate object. *iterable* must be a sequence, an
288 :term:`iterator`, or some other object which supports iteration. The
289 :meth:`__next__` method of the iterator returned by :func:`enumerate` returns a
290 tuple containing a count (from *start* which defaults to 0) and the
291 corresponding value obtained from iterating over *iterable*.
292 :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``,
293 ``(1, seq[1])``, ``(2, seq[2])``, .... For example:
295 >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter']):
303 .. function:: eval(expression, globals=None, locals=None)
305 The arguments are a string and optional globals and locals. If provided,
306 *globals* must be a dictionary. If provided, *locals* can be any mapping
309 The *expression* argument is parsed and evaluated as a Python expression
310 (technically speaking, a condition list) using the *globals* and *locals*
311 dictionaries as global and local namespace. If the *globals* dictionary is
312 present and lacks '__builtins__', the current globals are copied into *globals*
313 before *expression* is parsed. This means that *expression* normally has full
314 access to the standard :mod:`builtins` module and restricted environments are
315 propagated. If the *locals* dictionary is omitted it defaults to the *globals*
316 dictionary. If both dictionaries are omitted, the expression is executed in the
317 environment where :func:`eval` is called. The return value is the result of
318 the evaluated expression. Syntax errors are reported as exceptions. Example:
324 This function can also be used to execute arbitrary code objects (such as
325 those created by :func:`compile`). In this case pass a code object instead
326 of a string. If the code object has been compiled with ``'exec'`` as the
327 *kind* argument, :func:`eval`\'s return value will be ``None``.
329 Hints: dynamic execution of statements is supported by the :func:`exec`
330 function. The :func:`globals` and :func:`locals` functions
331 returns the current global and local dictionary, respectively, which may be
332 useful to pass around for use by :func:`eval` or :func:`exec`.
335 .. function:: exec(object[, globals[, locals]])
337 This function supports dynamic execution of Python code. *object* must be
338 either a string or a code object. If it is a string, the string is parsed as
339 a suite of Python statements which is then executed (unless a syntax error
340 occurs). [#]_ If it is a code object, it is simply executed. In all cases,
341 the code that's executed is expected to be valid as file input (see the
342 section "File input" in the Reference Manual). Be aware that the
343 :keyword:`return` and :keyword:`yield` statements may not be used outside of
344 function definitions even within the context of code passed to the
345 :func:`exec` function. The return value is ``None``.
347 In all cases, if the optional parts are omitted, the code is executed in the
348 current scope. If only *globals* is provided, it must be a dictionary, which
349 will be used for both the global and the local variables. If *globals* and
350 *locals* are given, they are used for the global and local variables,
351 respectively. If provided, *locals* can be any mapping object.
353 If the *globals* dictionary does not contain a value for the key
354 ``__builtins__``, a reference to the dictionary of the built-in module
355 :mod:`builtins` is inserted under that key. That way you can control what
356 builtins are available to the executed code by inserting your own
357 ``__builtins__`` dictionary into *globals* before passing it to :func:`exec`.
361 The built-in functions :func:`globals` and :func:`locals` return the current
362 global and local dictionary, respectively, which may be useful to pass around
363 for use as the second and third argument to :func:`exec`.
367 The default *locals* act as described for function :func:`locals` below:
368 modifications to the default *locals* dictionary should not be attempted.
369 Pass an explicit *locals* dictionary if you need to see effects of the
370 code on *locals* after function :func:`exec` returns.
373 .. function:: filter(function, iterable)
375 Construct an iterator from those elements of *iterable* for which *function*
376 returns true. *iterable* may be either a sequence, a container which
377 supports iteration, or an iterator. If *function* is ``None``, the identity
378 function is assumed, that is, all elements of *iterable* that are false are
381 Note that ``filter(function, iterable)`` is equivalent to the generator
382 expression ``(item for item in iterable if function(item))`` if function is
383 not ``None`` and ``(item for item in iterable if item)`` if function is
386 See :func:`itertools.filterfalse` for the complementary function that returns
387 elements of *iterable* for which *function* returns false.
390 .. function:: float([x])
392 Convert a string or a number to floating point. If the argument is a string,
393 it must contain a possibly signed decimal or floating point number, possibly
394 embedded in whitespace. The argument may also be ``'[+|-]nan'`` or
395 ``'[+|-]inf'``. Otherwise, the argument may be an integer or a floating
396 point number, and a floating point number with the same value (within
397 Python's floating point precision) is returned. If no argument is given,
406 When passing in a string, values for NaN and Infinity may be returned,
407 depending on the underlying C library. Float accepts the strings
408 ``'nan'``, ``'inf'`` and ``'-inf'`` for NaN and positive or negative
409 infinity. The case and a leading + are ignored as well as a leading - is
410 ignored for NaN. Float always represents NaN and infinity as ``nan``,
413 The float type is described in :ref:`typesnumeric`.
415 .. function:: format(value[, format_spec])
421 Convert a *value* to a "formatted" representation, as controlled by
422 *format_spec*. The interpretation of *format_spec* will depend on the type
423 of the *value* argument, however there is a standard formatting syntax that
424 is used by most built-in types: :ref:`formatspec`.
428 ``format(value, format_spec)`` merely calls
429 ``value.__format__(format_spec)``.
432 .. function:: frozenset([iterable])
435 Return a frozenset object, optionally with elements taken from *iterable*.
436 The frozenset type is described in :ref:`types-set`.
438 For other containers see the built in :class:`dict`, :class:`list`, and
439 :class:`tuple` classes, and the :mod:`collections` module.
442 .. function:: getattr(object, name[, default])
444 Return the value of the named attributed of *object*. *name* must be a string.
445 If the string is the name of one of the object's attributes, the result is the
446 value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
447 ``x.foobar``. If the named attribute does not exist, *default* is returned if
448 provided, otherwise :exc:`AttributeError` is raised.
451 .. function:: globals()
453 Return a dictionary representing the current global symbol table. This is always
454 the dictionary of the current module (inside a function or method, this is the
455 module where it is defined, not the module from which it is called).
458 .. function:: hasattr(object, name)
460 The arguments are an object and a string. The result is ``True`` if the string
461 is the name of one of the object's attributes, ``False`` if not. (This is
462 implemented by calling ``getattr(object, name)`` and seeing whether it raises an
466 .. function:: hash(object)
468 Return the hash value of the object (if it has one). Hash values are integers.
469 They are used to quickly compare dictionary keys during a dictionary lookup.
470 Numeric values that compare equal have the same hash value (even if they are of
471 different types, as is the case for 1 and 1.0).
474 .. function:: help([object])
476 Invoke the built-in help system. (This function is intended for interactive
477 use.) If no argument is given, the interactive help system starts on the
478 interpreter console. If the argument is a string, then the string is looked up
479 as the name of a module, function, class, method, keyword, or documentation
480 topic, and a help page is printed on the console. If the argument is any other
481 kind of object, a help page on the object is generated.
483 This function is added to the built-in namespace by the :mod:`site` module.
488 Convert an integer number to a hexadecimal string. The result is a valid Python
489 expression. If *x* is not a Python :class:`int` object, it has to define an
490 :meth:`__index__` method that returns an integer.
494 To obtain a hexadecimal string representation for a float, use the
495 :meth:`float.hex` method.
498 .. function:: id(object)
500 Return the "identity" of an object. This is an integer which
501 is guaranteed to be unique and constant for this object during its lifetime.
502 Two objects with non-overlapping lifetimes may have the same :func:`id`
505 .. impl-detail:: This is the address of the object.
508 .. function:: input([prompt])
510 If the *prompt* argument is present, it is written to standard output without
511 a trailing newline. The function then reads a line from input, converts it
512 to a string (stripping a trailing newline), and returns that. When EOF is
513 read, :exc:`EOFError` is raised. Example::
515 >>> s = input('--> ')
516 --> Monty Python's Flying Circus
518 "Monty Python's Flying Circus"
520 If the :mod:`readline` module was loaded, then :func:`input` will use it
521 to provide elaborate line editing and history features.
524 .. function:: int([number | string[, base]])
526 Convert a number or string to an integer. If no arguments are given, return
527 ``0``. If a number is given, return ``number.__int__()``. Conversion of
528 floating point numbers to integers truncates towards zero. A string must be
529 a base-radix integer literal optionally preceded by '+' or '-' (with no space
530 in between) and optionally surrounded by whitespace. A base-n literal
531 consists of the digits 0 to n-1, with 'a' to 'z' (or 'A' to 'Z') having
532 values 10 to 35. The default *base* is 10. The allowed values are 0 and 2-36.
533 Base-2, -8, and -16 literals can be optionally prefixed with ``0b``/``0B``,
534 ``0o``/``0O``, or ``0x``/``0X``, as with integer literals in code. Base 0
535 means to interpret exactly as a code literal, so that the actual base is 2,
536 8, 10, or 16, and so that ``int('010', 0)`` is not legal, while
537 ``int('010')`` is, as well as ``int('010', 8)``.
539 The integer type is described in :ref:`typesnumeric`.
542 .. function:: isinstance(object, classinfo)
544 Return true if the *object* argument is an instance of the *classinfo*
545 argument, or of a (direct or indirect) subclass thereof. If *object* is not
546 an object of the given type, the function always returns false. If
547 *classinfo* is not a class (type object), it may be a tuple of type objects,
548 or may recursively contain other such tuples (other sequence types are not
549 accepted). If *classinfo* is not a type or tuple of types and such tuples,
550 a :exc:`TypeError` exception is raised.
553 .. function:: issubclass(class, classinfo)
555 Return true if *class* is a subclass (direct or indirect) of *classinfo*. A
556 class is considered a subclass of itself. *classinfo* may be a tuple of class
557 objects, in which case every entry in *classinfo* will be checked. In any other
558 case, a :exc:`TypeError` exception is raised.
561 .. function:: iter(object[, sentinel])
563 Return an :term:`iterator` object. The first argument is interpreted very
564 differently depending on the presence of the second argument. Without a
565 second argument, *object* must be a collection object which supports the
566 iteration protocol (the :meth:`__iter__` method), or it must support the
567 sequence protocol (the :meth:`__getitem__` method with integer arguments
568 starting at ``0``). If it does not support either of those protocols,
569 :exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
570 then *object* must be a callable object. The iterator created in this case
571 will call *object* with no arguments for each call to its :meth:`__next__`
572 method; if the value returned is equal to *sentinel*, :exc:`StopIteration`
573 will be raised, otherwise the value will be returned.
575 One useful application of the second form of :func:`iter` is to read lines of
576 a file until a certain line is reached. The following example reads a file
577 until ``"STOP"`` is reached: ::
579 with open("mydata.txt") as fp:
580 for line in iter(fp.readline, "STOP"):
586 Return the length (the number of items) of an object. The argument may be a
587 sequence (string, tuple or list) or a mapping (dictionary).
590 .. function:: list([iterable])
592 Return a list whose items are the same and in the same order as *iterable*'s
593 items. *iterable* may be either a sequence, a container that supports
594 iteration, or an iterator object. If *iterable* is already a list, a copy is
595 made and returned, similar to ``iterable[:]``. For instance, ``list('abc')``
596 returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``.
597 If no argument is given, returns a new empty list, ``[]``.
599 :class:`list` is a mutable sequence type, as documented in :ref:`typesseq`.
602 .. function:: locals()
604 Update and return a dictionary representing the current local symbol table.
605 Free variables are returned by :func:`locals` when it is called in function
606 blocks, but not in class blocks.
609 The contents of this dictionary should not be modified; changes may not
610 affect the values of local and free variables used by the interpreter.
612 .. function:: map(function, iterable, ...)
614 Return an iterator that applies *function* to every item of *iterable*,
615 yielding the results. If additional *iterable* arguments are passed,
616 *function* must take that many arguments and is applied to the items from all
617 iterables in parallel. With multiple iterables, the iterator stops when the
618 shortest iterable is exhausted. For cases where the function inputs are
619 already arranged into argument tuples, see :func:`itertools.starmap`\.
622 .. function:: max(iterable[, args...], *[, key])
624 With a single argument *iterable*, return the largest item of a non-empty
625 iterable (such as a string, tuple or list). With more than one argument, return
626 the largest of the arguments.
628 The optional keyword-only *key* argument specifies a one-argument ordering
629 function like that used for :meth:`list.sort`.
632 .. function:: memoryview(obj)
635 Return a "memory view" object created from the given argument. See
636 :ref:`typememoryview` for more information.
639 .. function:: min(iterable[, args...], *[, key])
641 With a single argument *iterable*, return the smallest item of a non-empty
642 iterable (such as a string, tuple or list). With more than one argument, return
643 the smallest of the arguments.
645 The optional keyword-only *key* argument specifies a one-argument ordering
646 function like that used for :meth:`list.sort`.
649 .. function:: next(iterator[, default])
651 Retrieve the next item from the *iterator* by calling its :meth:`__next__`
652 method. If *default* is given, it is returned if the iterator is exhausted,
653 otherwise :exc:`StopIteration` is raised.
656 .. function:: object()
658 Return a new featureless object. :class:`object` is a base for all classes.
659 It has the methods that are common to all instances of Python classes. This
660 function does not accept any arguments.
664 :class:`object` does *not* have a :attr:`__dict__`, so you can't assign
665 arbitrary attributes to an instance of the :class:`object` class.
670 Convert an integer number to an octal string. The result is a valid Python
671 expression. If *x* is not a Python :class:`int` object, it has to define an
672 :meth:`__index__` method that returns an integer.
675 .. function:: open(file, mode='r', buffering=None, encoding=None, errors=None, newline=None, closefd=True)
677 Open *file* and return a corresponding stream. If the file cannot be opened,
678 an :exc:`IOError` is raised.
680 *file* is either a string or bytes object giving the name (and the path if
681 the file isn't in the current working directory) of the file to be opened or
682 an integer file descriptor of the file to be wrapped. (If a file descriptor
683 is given, it is closed when the returned I/O object is closed, unless
684 *closefd* is set to ``False``.)
686 *mode* is an optional string that specifies the mode in which the file is
687 opened. The available modes are:
689 ========= ===============================================================
691 --------- ---------------------------------------------------------------
692 ``'r'`` open for reading (default)
693 ``'w'`` open for writing, truncating the file first if it exists
694 ``'a'`` open for writing, appending to the end of the file if it exists
695 ========= ===============================================================
697 Several characters can be appended that modify the given mode:
699 ========= ===============================================================
700 ``'t'`` text mode (default)
702 ``'+'`` open for updating (reading and writing)
703 ``'U'`` universal newline mode (for backwards compatibility; should
704 not be used in new code)
705 ========= ===============================================================
707 The mode ``'w+'`` opens and truncates the file to 0 bytes, while ``'r+'``
708 opens the file without truncation. On *some* Unix systems, append mode means
709 that *all* writes append to the end of the file regardless of the current
712 Python distinguishes between files opened in binary and text modes, even when
713 the underlying operating system doesn't. Files opened in binary mode
714 (including ``'b'`` in the *mode* argument) return contents as ``bytes``
715 objects without any decoding. In text mode (the default, or when ``'t'`` is
716 included in the *mode* argument), the contents of the file are returned as
717 strings, the bytes having been first decoded using the specified *encoding*.
718 If *encoding* is not specified, a platform-dependent default encoding is
721 *buffering* is an optional integer used to set the buffering policy. By
722 default full buffering is on. Pass 0 to switch buffering off (only allowed
723 in binary mode), 1 to set line buffering, and an integer > 1 for full
726 *encoding* is the name of the encoding used to decode or encode the file.
727 This should only be used in text mode. The default encoding is platform
728 dependent (whatever :func:`locale.getpreferredencoding` returns), but any
729 encoding supported by Python can be used. See the :mod:`codecs` module for
730 the list of supported encodings.
732 *errors* is an optional string that specifies how encoding and decoding
733 errors are to be handled--this cannot be used in binary mode. Pass
734 ``'strict'`` to raise a :exc:`ValueError` exception if there is an encoding
735 error (the default of ``None`` has the same effect), or pass ``'ignore'`` to
736 ignore errors. (Note that ignoring encoding errors can lead to data loss.)
737 ``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted
738 where there is malformed data. When writing, ``'xmlcharrefreplace'``
739 (replace with the appropriate XML character reference) or
740 ``'backslashreplace'`` (replace with backslashed escape sequences) can be
741 used. Any other error handling name that has been registered with
742 :func:`codecs.register_error` is also valid.
744 *newline* controls how universal newlines works (it only applies to text
745 mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It
748 * On input, if *newline* is ``None``, universal newlines mode is enabled.
749 Lines in the input can end in ``'\n'``, ``'\r'``, or ``'\r\n'``, and these
750 are translated into ``'\n'`` before being returned to the caller. If it is
751 ``''``, universal newline mode is enabled, but line endings are returned to
752 the caller untranslated. If it has any of the other legal values, input
753 lines are only terminated by the given string, and the line ending is
754 returned to the caller untranslated.
756 * On output, if *newline* is ``None``, any ``'\n'`` characters written are
757 translated to the system default line separator, :data:`os.linesep`. If
758 *newline* is ``''``, no translation takes place. If *newline* is any of
759 the other legal values, any ``'\n'`` characters written are translated to
762 If *closefd* is ``False`` and a file descriptor rather than a filename was
763 given, the underlying file descriptor will be kept open when the file is
764 closed. If a filename is given *closefd* has no effect and must be ``True``
767 The type of file object returned by the :func:`open` function depends on the
768 mode. When :func:`open` is used to open a file in a text mode (``'w'``,
769 ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
770 :class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used
771 to open a file in a binary mode with buffering, the returned class is a
772 subclass of :class:`io.BufferedIOBase`. The exact class varies: in read
773 binary mode, it returns a :class:`io.BufferedReader`; in write binary and
774 append binary modes, it returns a :class:`io.BufferedWriter`, and in
775 read/write mode, it returns a :class:`io.BufferedRandom`. When buffering is
776 disabled, the raw stream, a subclass of :class:`io.RawIOBase`,
777 :class:`io.FileIO`, is returned.
780 single: line-buffered I/O
781 single: unbuffered I/O
782 single: buffer size, I/O
783 single: I/O control; buffering
788 See also the file handling modules, such as, :mod:`fileinput`, :mod:`io`
789 (where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:`tempfile`,
793 .. XXX works for bytes too, but should it?
796 Given a string of length one, return an integer representing the Unicode code
797 point of the character. For example, ``ord('a')`` returns the integer ``97``
798 and ``ord('\u2020')`` returns ``8224``. This is the inverse of :func:`chr`.
800 If the argument length is not one, a :exc:`TypeError` will be raised. (If
801 Python was built with UCS2 Unicode, then the character's code point must be
802 in the range [0..65535] inclusive; otherwise the string length is two!)
805 .. function:: pow(x, y[, z])
807 Return *x* to the power *y*; if *z* is present, return *x* to the power *y*,
808 modulo *z* (computed more efficiently than ``pow(x, y) % z``). The two-argument
809 form ``pow(x, y)`` is equivalent to using the power operator: ``x**y``.
811 The arguments must have numeric types. With mixed operand types, the
812 coercion rules for binary arithmetic operators apply. For :class:`int`
813 operands, the result has the same type as the operands (after coercion)
814 unless the second argument is negative; in that case, all arguments are
815 converted to float and a float result is delivered. For example, ``10**2``
816 returns ``100``, but ``10**-2`` returns ``0.01``. If the second argument is
817 negative, the third argument must be omitted. If *z* is present, *x* and *y*
818 must be of integer types, and *y* must be non-negative.
821 .. function:: print([object, ...], *, sep=' ', end='\\n', file=sys.stdout)
823 Print *object*\(s) to the stream *file*, separated by *sep* and followed by
824 *end*. *sep*, *end* and *file*, if present, must be given as keyword
827 All non-keyword arguments are converted to strings like :func:`str` does and
828 written to the stream, separated by *sep* and followed by *end*. Both *sep*
829 and *end* must be strings; they can also be ``None``, which means to use the
830 default values. If no *object* is given, :func:`print` will just write
833 The *file* argument must be an object with a ``write(string)`` method; if it
834 is not present or ``None``, :data:`sys.stdout` will be used.
837 .. function:: property(fget=None, fset=None, fdel=None, doc=None)
839 Return a property attribute.
841 *fget* is a function for getting an attribute value, likewise *fset* is a
842 function for setting, and *fdel* a function for del'ing, an attribute. Typical
843 use is to define a managed attribute x::
851 def setx(self, value):
855 x = property(getx, setx, delx, "I'm the 'x' property.")
857 If given, *doc* will be the docstring of the property attribute. Otherwise, the
858 property will copy *fget*'s docstring (if it exists). This makes it possible to
859 create read-only properties easily using :func:`property` as a :term:`decorator`::
861 class Parrot(object):
863 self._voltage = 100000
867 """Get the current voltage."""
870 turns the :meth:`voltage` method into a "getter" for a read-only attribute
873 A property object has :attr:`getter`, :attr:`setter`, and :attr:`deleter`
874 methods usable as decorators that create a copy of the property with the
875 corresponding accessor function set to the decorated function. This is
876 best explained with an example::
884 """I'm the 'x' property."""
895 This code is exactly equivalent to the first example. Be sure to give the
896 additional functions the same name as the original property (``x`` in this
899 The returned property also has the attributes ``fget``, ``fset``, and
900 ``fdel`` corresponding to the constructor arguments.
903 .. XXX does accept objects with __index__ too
904 .. function:: range([start,] stop[, step])
906 This is a versatile function to create iterables yielding arithmetic
907 progressions. It is most often used in :keyword:`for` loops. The arguments
908 must be integers. If the *step* argument is omitted, it defaults to ``1``.
909 If the *start* argument is omitted, it defaults to ``0``. The full form
910 returns an iterable of integers ``[start, start + step, start + 2 * step,
911 ...]``. If *step* is positive, the last element is the largest ``start + i *
912 step`` less than *stop*; if *step* is negative, the last element is the
913 smallest ``start + i * step`` greater than *stop*. *step* must not be zero
914 (or else :exc:`ValueError` is raised). Example:
917 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
918 >>> list(range(1, 11))
919 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
920 >>> list(range(0, 30, 5))
921 [0, 5, 10, 15, 20, 25]
922 >>> list(range(0, 10, 3))
924 >>> list(range(0, -10, -1))
925 [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
928 >>> list(range(1, 0))
932 .. function:: repr(object)
934 Return a string containing a printable representation of an object. For many
935 types, this function makes an attempt to return a string that would yield an
936 object with the same value when passed to :func:`eval`, otherwise the
937 representation is a string enclosed in angle brackets that contains the name
938 of the type of the object together with additional information often
939 including the name and address of the object. A class can control what this
940 function returns for its instances by defining a :meth:`__repr__` method.
943 .. function:: reversed(seq)
945 Return a reverse :term:`iterator`. *seq* must be an object which has
946 a :meth:`__reversed__` method or supports the sequence protocol (the
947 :meth:`__len__` method and the :meth:`__getitem__` method with integer
948 arguments starting at ``0``).
951 .. function:: round(x[, n])
953 Return the floating point value *x* rounded to *n* digits after the decimal
954 point. If *n* is omitted, it defaults to zero. Delegates to
957 For the built-in types supporting :func:`round`, values are rounded to the
958 closest multiple of 10 to the power minus *n*; if two multiples are equally
959 close, rounding is done toward the even choice (so, for example, both
960 ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is ``2``).
961 The return value is an integer if called with one argument, otherwise of the
965 .. function:: set([iterable])
968 Return a new set, optionally with elements taken from *iterable*.
969 The set type is described in :ref:`types-set`.
972 .. function:: setattr(object, name, value)
974 This is the counterpart of :func:`getattr`. The arguments are an object, a
975 string and an arbitrary value. The string may name an existing attribute or a
976 new attribute. The function assigns the value to the attribute, provided the
977 object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to
981 .. function:: slice([start,] stop[, step])
983 .. index:: single: Numerical Python
985 Return a :term:`slice` object representing the set of indices specified by
986 ``range(start, stop, step)``. The *start* and *step* arguments default to
987 ``None``. Slice objects have read-only data attributes :attr:`start`,
988 :attr:`stop` and :attr:`step` which merely return the argument values (or their
989 default). They have no other explicit functionality; however they are used by
990 Numerical Python and other third party extensions. Slice objects are also
991 generated when extended indexing syntax is used. For example:
992 ``a[start:stop:step]`` or ``a[start:stop, i]``. See :func:`itertools.islice`
993 for an alternate version that returns an iterator.
996 .. function:: sorted(iterable[, key][, reverse])
998 Return a new sorted list from the items in *iterable*.
1000 Has two optional arguments which must be specified as keyword arguments.
1002 *key* specifies a function of one argument that is used to extract a comparison
1003 key from each list element: ``key=str.lower``. The default value is ``None``.
1005 *reverse* is a boolean value. If set to ``True``, then the list elements are
1006 sorted as if each comparison were reversed.
1008 To convert an old-style *cmp* function to a *key* function, see the
1009 `CmpToKey recipe in the ASPN cookbook
1010 <http://code.activestate.com/recipes/576653/>`_\.
1012 For sorting examples and a brief sorting tutorial, see `Sorting HowTo
1013 <http://wiki.python.org/moin/HowTo/Sorting/>`_\.
1015 .. function:: staticmethod(function)
1017 Return a static method for *function*.
1019 A static method does not receive an implicit first argument. To declare a static
1020 method, use this idiom::
1024 def f(arg1, arg2, ...): ...
1026 The ``@staticmethod`` form is a function :term:`decorator` -- see the
1027 description of function definitions in :ref:`function` for details.
1029 It can be called either on the class (such as ``C.f()``) or on an instance (such
1030 as ``C().f()``). The instance is ignored except for its class.
1032 Static methods in Python are similar to those found in Java or C++. For a more
1033 advanced concept, see :func:`classmethod` in this section.
1035 For more information on static methods, consult the documentation on the
1036 standard type hierarchy in :ref:`types`.
1039 .. function:: str([object[, encoding[, errors]]])
1041 Return a string version of an object, using one of the following modes:
1043 If *encoding* and/or *errors* are given, :func:`str` will decode the
1044 *object* which can either be a byte string or a character buffer using
1045 the codec for *encoding*. The *encoding* parameter is a string giving
1046 the name of an encoding; if the encoding is not known, :exc:`LookupError`
1047 is raised. Error handling is done according to *errors*; this specifies the
1048 treatment of characters which are invalid in the input encoding. If
1049 *errors* is ``'strict'`` (the default), a :exc:`ValueError` is raised on
1050 errors, while a value of ``'ignore'`` causes errors to be silently ignored,
1051 and a value of ``'replace'`` causes the official Unicode replacement character,
1052 U+FFFD, to be used to replace input characters which cannot be decoded.
1053 See also the :mod:`codecs` module.
1055 When only *object* is given, this returns its nicely printable representation.
1056 For strings, this is the string itself. The difference with ``repr(object)``
1057 is that ``str(object)`` does not always attempt to return a string that is
1058 acceptable to :func:`eval`; its goal is to return a printable string.
1059 With no arguments, this returns the empty string.
1061 Objects can specify what ``str(object)`` returns by defining a :meth:`__str__`
1064 For more information on strings see :ref:`typesseq` which describes sequence
1065 functionality (strings are sequences), and also the string-specific methods
1066 described in the :ref:`string-methods` section. To output formatted strings,
1067 see the :ref:`string-formatting` section. In addition see the
1068 :ref:`stringservices` section.
1071 .. function:: sum(iterable[, start])
1073 Sums *start* and the items of an *iterable* from left to right and returns the
1074 total. *start* defaults to ``0``. The *iterable*'s items are normally numbers,
1075 and are not allowed to be strings. The fast, correct way to concatenate a
1076 sequence of strings is by calling ``''.join(sequence)``. To add floating
1077 point values with extended precision, see :func:`math.fsum`\.
1080 .. function:: super([type[, object-or-type]])
1082 Return a proxy object that delegates method calls to a parent or sibling
1083 class of *type*. This is useful for accessing inherited methods that have
1084 been overridden in a class. The search order is same as that used by
1085 :func:`getattr` except that the *type* itself is skipped.
1087 The :attr:`__mro__` attribute of the *type* lists the method resolution
1088 search order used by both :func:`getattr` and :func:`super`. The attribute
1089 is dynamic and can change whenever the inheritance hierarchy is updated.
1091 If the second argument is omitted, the super object returned is unbound. If
1092 the second argument is an object, ``isinstance(obj, type)`` must be true. If
1093 the second argument is a type, ``issubclass(type2, type)`` must be true (this
1094 is useful for classmethods).
1096 There are two typical use cases for *super*. In a class hierarchy with
1097 single inheritance, *super* can be used to refer to parent classes without
1098 naming them explicitly, thus making the code more maintainable. This use
1099 closely parallels the use of *super* in other programming languages.
1101 The second use case is to support cooperative multiple inheritance in a
1102 dynamic execution environment. This use case is unique to Python and is
1103 not found in statically compiled languages or languages that only support
1104 single inheritance. This makes it possible to implement "diamond diagrams"
1105 where multiple base classes implement the same method. Good design dictates
1106 that this method have the same calling signature in every case (because the
1107 order of calls is determined at runtime, because that order adapts
1108 to changes in the class hierarchy, and because that order can include
1109 sibling classes that are unknown prior to runtime).
1111 For both use cases, a typical superclass call looks like this::
1114 def method(self, arg):
1115 super().method(arg) # This does the same thing as:
1116 # super(C, self).method(arg)
1118 Note that :func:`super` is implemented as part of the binding process for
1119 explicit dotted attribute lookups such as ``super().__getitem__(name)``.
1120 It does so by implementing its own :meth:`__getattribute__` method for searching
1121 classes in a predictable order that supports cooperative multiple inheritance.
1122 Accordingly, :func:`super` is undefined for implicit lookups using statements or
1123 operators such as ``super()[name]``.
1125 Also note that :func:`super` is not limited to use inside methods. The two
1126 argument form specifies the arguments exactly and makes the appropriate
1127 references. The zero argument form automatically searches the stack frame
1128 for the class (``__class__``) and the first argument.
1131 .. function:: tuple([iterable])
1133 Return a tuple whose items are the same and in the same order as *iterable*'s
1134 items. *iterable* may be a sequence, a container that supports iteration, or an
1135 iterator object. If *iterable* is already a tuple, it is returned unchanged.
1136 For instance, ``tuple('abc')`` returns ``('a', 'b', 'c')`` and ``tuple([1, 2,
1137 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty
1140 :class:`tuple` is an immutable sequence type, as documented in :ref:`typesseq`.
1143 .. function:: type(object)
1145 .. index:: object: type
1147 Return the type of an *object*. The return value is a type object and
1148 generally the same object as returned by ``object.__class__``.
1150 The :func:`isinstance` built-in function is recommended for testing the type
1151 of an object, because it takes subclasses into account.
1153 With three arguments, :func:`type` functions as a constructor as detailed
1157 .. function:: type(name, bases, dict)
1160 Return a new type object. This is essentially a dynamic form of the
1161 :keyword:`class` statement. The *name* string is the class name and becomes the
1162 :attr:`__name__` attribute; the *bases* tuple itemizes the base classes and
1163 becomes the :attr:`__bases__` attribute; and the *dict* dictionary is the
1164 namespace containing definitions for class body and becomes the :attr:`__dict__`
1165 attribute. For example, the following two statements create identical
1166 :class:`type` objects:
1168 >>> class X(object):
1171 >>> X = type('X', (object,), dict(a=1))
1174 .. function:: vars([object])
1176 Without an argument, act like :func:`locals`.
1178 With a module, class or class instance object as argument (or anything else that
1179 has a :attr:`__dict__` attribute), return that attribute.
1182 The returned dictionary should not be modified:
1183 the effects on the corresponding symbol table are undefined. [#]_
1185 .. function:: zip(*iterables)
1187 Make an iterator that aggregates elements from each of the iterables.
1189 Returns an iterator of tuples, where the *i*-th tuple contains
1190 the *i*-th element from each of the argument sequences or iterables. The
1191 iterator stops when the shortest input iterable is exhausted. With a single
1192 iterable argument, it returns an iterator of 1-tuples. With no arguments,
1193 it returns an empty iterator. Equivalent to::
1195 def zip(*iterables):
1196 # zip('ABCD', 'xy') --> Ax By
1197 iterables = map(iter, iterables)
1199 yield tuple(map(next, iterables))
1201 The left-to-right evaluation order of the iterables is guaranteed. This
1202 makes possible an idiom for clustering a data series into n-length groups
1203 using ``zip(*[iter(s)]*n)``.
1205 :func:`zip` should only be used with unequal length inputs when you don't
1206 care about trailing, unmatched values from the longer iterables. If those
1207 values are important, use :func:`itertools.zip_longest` instead.
1209 :func:`zip` in conjunction with the ``*`` operator can be used to unzip a
1214 >>> zipped = zip(x, y)
1216 [(1, 4), (2, 5), (3, 6)]
1217 >>> x2, y2 = zip(*zip(x, y))
1218 >>> x == list(x2) and y == list(y2)
1222 .. function:: __import__(name, globals={}, locals={}, fromlist=[], level=0)
1230 This is an advanced function that is not needed in everyday Python
1233 This function is invoked by the :keyword:`import` statement. It can be
1234 replaced (by importing the :mod:`builtins` module and assigning to
1235 ``builtins.__import__``) in order to change semantics of the
1236 :keyword:`import` statement, but nowadays it is usually simpler to use import
1237 hooks (see :pep:`302`). Direct use of :func:`__import__` is rare, except in
1238 cases where you want to import a module whose name is only known at runtime.
1240 The function imports the module *name*, potentially using the given *globals*
1241 and *locals* to determine how to interpret the name in a package context.
1242 The *fromlist* gives the names of objects or submodules that should be
1243 imported from the module given by *name*. The standard implementation does
1244 not use its *locals* argument at all, and uses its *globals* only to
1245 determine the package context of the :keyword:`import` statement.
1247 *level* specifies whether to use absolute or relative imports. ``0`` (the
1248 default) means only perform absolute imports. Positive values for
1249 *level* indicate the number of parent directories to search relative to the
1250 directory of the module calling :func:`__import__`.
1252 When the *name* variable is of the form ``package.module``, normally, the
1253 top-level package (the name up till the first dot) is returned, *not* the
1254 module named by *name*. However, when a non-empty *fromlist* argument is
1255 given, the module named by *name* is returned.
1257 For example, the statement ``import spam`` results in bytecode resembling the
1260 spam = __import__('spam', globals(), locals(), [], 0)
1262 The statement ``import spam.ham`` results in this call::
1264 spam = __import__('spam.ham', globals(), locals(), [], 0)
1266 Note how :func:`__import__` returns the toplevel module here because this is
1267 the object that is bound to a name by the :keyword:`import` statement.
1269 On the other hand, the statement ``from spam.ham import eggs, sausage as
1270 saus`` results in ::
1272 _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
1274 saus = _temp.sausage
1276 Here, the ``spam.ham`` module is returned from :func:`__import__`. From this
1277 object, the names to import are retrieved and assigned to their respective
1280 If you simply want to import a module (potentially within a package) by name,
1281 you can call :func:`__import__` and then look it up in :data:`sys.modules`::
1284 >>> name = 'foo.bar.baz'
1285 >>> __import__(name)
1286 <module 'foo' from ...>
1287 >>> baz = sys.modules[name]
1289 <module 'foo.bar.baz' from ...>
1291 .. rubric:: Footnotes
1293 .. [#] Note that the parser only accepts the Unix-style end of line convention.
1294 If you are reading the code from a file, make sure to use newline conversion
1295 mode to convert Windows or Mac-style newlines.
1297 .. [#] In the current implementation, local variable bindings cannot normally be
1298 affected this way, but variables retrieved from other scopes (such as modules)
1299 can be. This may change.