7 The Python interpreter has a number of functions built into it that are always
8 available. They are listed here in alphabetical order.
11 .. function:: __import__(name[, globals[, locals[, fromlist[, level]]]])
21 This is an advanced function that is not needed in everyday Python
24 The function is invoked by the :keyword:`import` statement. It mainly exists
25 so that you can replace it with another function that has a compatible
26 interface, in order to change the semantics of the :keyword:`import` statement.
27 For examples of why and how you would do this, see the standard library modules
28 :mod:`ihooks` and :mod:`rexec`. See also the built-in module :mod:`imp`, which
29 defines some useful operations out of which you can build your own
30 :func:`__import__` function.
32 For example, the statement ``import spam`` results in the following call:
33 ``__import__('spam', globals(), locals(), [], -1)``; the statement
34 ``from spam.ham import eggs`` results in ``__import__('spam.ham', globals(),
35 locals(), ['eggs'], -1)``. Note that even though ``locals()`` and ``['eggs']``
36 are passed in as arguments, the :func:`__import__` function does not set the
37 local variable named ``eggs``; this is done by subsequent code that is generated
38 for the import statement. (In fact, the standard implementation does not use
39 its *locals* argument at all, and uses its *globals* only to determine the
40 package context of the :keyword:`import` statement.)
42 When the *name* variable is of the form ``package.module``, normally, the
43 top-level package (the name up till the first dot) is returned, *not* the
44 module named by *name*. However, when a non-empty *fromlist* argument is
45 given, the module named by *name* is returned. This is done for
46 compatibility with the :term:`bytecode` generated for the different kinds of import
47 statement; when using ``import spam.ham.eggs``, the top-level package
48 :mod:`spam` must be placed in the importing namespace, but when using ``from
49 spam.ham import eggs``, the ``spam.ham`` subpackage must be used to find the
50 ``eggs`` variable. As a workaround for this behavior, use :func:`getattr` to
51 extract the desired components. For example, you could define the following
55 mod = __import__(name)
56 components = name.split('.')
57 for comp in components[1:]:
58 mod = getattr(mod, comp)
61 *level* specifies whether to use absolute or relative imports. The default is
62 ``-1`` which indicates both absolute and relative imports will be attempted.
63 ``0`` means only perform absolute imports. Positive values for *level* indicate
64 the number of parent directories to search relative to the directory of the
65 module calling :func:`__import__`.
67 .. versionchanged:: 2.5
68 The level parameter was added.
70 .. versionchanged:: 2.5
71 Keyword support for parameters was added.
76 Return the absolute value of a number. The argument may be a plain or long
77 integer or a floating point number. If the argument is a complex number, its
78 magnitude is returned.
81 .. function:: all(iterable)
83 Return True if all elements of the *iterable* are true. Equivalent to::
86 for element in iterable:
94 .. function:: any(iterable)
96 Return True if any element of the *iterable* is true. Equivalent to::
99 for element in iterable:
104 .. versionadded:: 2.5
107 .. function:: basestring()
109 This abstract type is the superclass for :class:`str` and :class:`unicode`. It
110 cannot be called or instantiated, but it can be used to test whether an object
111 is an instance of :class:`str` or :class:`unicode`. ``isinstance(obj,
112 basestring)`` is equivalent to ``isinstance(obj, (str, unicode))``.
114 .. versionadded:: 2.3
117 .. function:: bool([x])
119 Convert a value to a Boolean, using the standard truth testing procedure. If
120 *x* is false or omitted, this returns :const:`False`; otherwise it returns
121 :const:`True`. :class:`bool` is also a class, which is a subclass of
122 :class:`int`. Class :class:`bool` cannot be subclassed further. Its only
123 instances are :const:`False` and :const:`True`.
125 .. index:: pair: Boolean; type
127 .. versionadded:: 2.2.1
129 .. versionchanged:: 2.3
130 If no argument is given, this function returns :const:`False`.
133 .. function:: callable(object)
135 Return :const:`True` if the *object* argument appears callable,
136 :const:`False` if not. If this
137 returns true, it is still possible that a call fails, but if it is false,
138 calling *object* will never succeed. Note that classes are callable (calling a
139 class returns a new instance); class instances are callable if they have a
140 :meth:`__call__` method.
145 Return a string of one character whose ASCII code is the integer *i*. For
146 example, ``chr(97)`` returns the string ``'a'``. This is the inverse of
147 :func:`ord`. The argument must be in the range [0..255], inclusive;
148 :exc:`ValueError` will be raised if *i* is outside that range. See
152 .. function:: classmethod(function)
154 Return a class method for *function*.
156 A class method receives the class as implicit first argument, just like an
157 instance method receives the instance. To declare a class method, use this
162 def f(cls, arg1, arg2, ...): ...
164 The ``@classmethod`` form is a function :term:`decorator` -- see the description
165 of function definitions in :ref:`function` for details.
167 It can be called either on the class (such as ``C.f()``) or on an instance (such
168 as ``C().f()``). The instance is ignored except for its class. If a class
169 method is called for a derived class, the derived class object is passed as the
170 implied first argument.
172 Class methods are different than C++ or Java static methods. If you want those,
173 see :func:`staticmethod` in this section.
175 For more information on class methods, consult the documentation on the standard
176 type hierarchy in :ref:`types`.
178 .. versionadded:: 2.2
180 .. versionchanged:: 2.4
181 Function decorator syntax added.
184 .. function:: cmp(x, y)
186 Compare the two objects *x* and *y* and return an integer according to the
187 outcome. The return value is negative if ``x < y``, zero if ``x == y`` and
188 strictly positive if ``x > y``.
191 .. function:: compile(source, filename, mode[, flags[, dont_inherit]])
193 Compile the *source* into a code or AST object. Code objects can be executed
194 by an :keyword:`exec` statement or evaluated by a call to :func:`eval`.
195 *source* can either be a string or an AST object. Refer to the :mod:`_ast`
196 module documentation for information on how to compile into and from AST
199 When compiling a string with multi-line statements, two caveats apply: line
200 endings must be represented by a single newline character (``'\n'``), and the
201 input must be terminated by at least one newline character. If line endings
202 are represented by ``'\r\n'``, use the string :meth:`replace` method to
203 change them into ``'\n'``.
205 The *filename* argument should give the file from which the code was read;
206 pass some recognizable value if it wasn't read from a file (``'<string>'`` is
209 The *mode* argument specifies what kind of code must be compiled; it can be
210 ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
211 consists of a single expression, or ``'single'`` if it consists of a single
212 interactive statement (in the latter case, expression statements that
213 evaluate to something else than ``None`` will be printed).
215 The optional arguments *flags* and *dont_inherit* (which are new in Python 2.2)
216 control which future statements (see :pep:`236`) affect the compilation of
217 *source*. If neither is present (or both are zero) the code is compiled with
218 those future statements that are in effect in the code that is calling compile.
219 If the *flags* argument is given and *dont_inherit* is not (or is zero) then the
220 future statements specified by the *flags* argument are used in addition to
221 those that would be used anyway. If *dont_inherit* is a non-zero integer then
222 the *flags* argument is it -- the future statements in effect around the call to
225 Future statements are specified by bits which can be bitwise ORed together to
226 specify multiple statements. The bitfield required to specify a given feature
227 can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
228 instance in the :mod:`__future__` module.
230 This function raises :exc:`SyntaxError` if the compiled source is invalid,
231 and :exc:`TypeError` if the source contains null bytes.
233 .. versionadded:: 2.6
234 Support for compiling AST objects.
237 .. function:: complex([real[, imag]])
239 Create a complex number with the value *real* + *imag*\*j or convert a string or
240 number to a complex number. If the first parameter is a string, it will be
241 interpreted as a complex number and the function must be called without a second
242 parameter. The second parameter can never be a string. Each argument may be any
243 numeric type (including complex). If *imag* is omitted, it defaults to zero and
244 the function serves as a numeric conversion function like :func:`int`,
245 :func:`long` and :func:`float`. If both arguments are omitted, returns ``0j``.
247 The complex type is described in :ref:`typesnumeric`.
250 .. function:: delattr(object, name)
252 This is a relative of :func:`setattr`. The arguments are an object and a
253 string. The string must be the name of one of the object's attributes. The
254 function deletes the named attribute, provided the object allows it. For
255 example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
258 .. function:: dict([arg])
261 Create a new data dictionary, optionally with items taken from *arg*.
262 The dictionary type is described in :ref:`typesmapping`.
264 For other containers see the built in :class:`list`, :class:`set`, and
265 :class:`tuple` classes, and the :mod:`collections` module.
268 .. function:: dir([object])
270 Without arguments, return the list of names in the current local scope. With an
271 argument, attempt to return a list of valid attributes for that object.
273 If the object has a method named :meth:`__dir__`, this method will be called and
274 must return the list of attributes. This allows objects that implement a custom
275 :func:`__getattr__` or :func:`__getattribute__` function to customize the way
276 :func:`dir` reports their attributes.
278 If the object does not provide :meth:`__dir__`, the function tries its best to
279 gather information from the object's :attr:`__dict__` attribute, if defined, and
280 from its type object. The resulting list is not necessarily complete, and may
281 be inaccurate when the object has a custom :func:`__getattr__`.
283 The default :func:`dir` mechanism behaves differently with different types of
284 objects, as it attempts to produce the most relevant, rather than complete,
287 * If the object is a module object, the list contains the names of the module's
290 * If the object is a type or class object, the list contains the names of its
291 attributes, and recursively of the attributes of its bases.
293 * Otherwise, the list contains the object's attributes' names, the names of its
294 class's attributes, and recursively of the attributes of its class's base
297 The resulting list is sorted alphabetically. For example:
300 >>> dir() # doctest: +SKIP
301 ['__builtins__', '__doc__', '__name__', 'struct']
302 >>> dir(struct) # doctest: +NORMALIZE_WHITESPACE
303 ['Struct', '__builtins__', '__doc__', '__file__', '__name__',
304 '__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
305 'unpack', 'unpack_from']
306 >>> class Foo(object):
307 ... def __dir__(self):
308 ... return ["kan", "ga", "roo"]
316 Because :func:`dir` is supplied primarily as a convenience for use at an
317 interactive prompt, it tries to supply an interesting set of names more than it
318 tries to supply a rigorously or consistently defined set of names, and its
319 detailed behavior may change across releases. For example, metaclass attributes
320 are not in the result list when the argument is a class.
323 .. function:: divmod(a, b)
325 Take two (non complex) numbers as arguments and return a pair of numbers
326 consisting of their quotient and remainder when using long division. With mixed
327 operand types, the rules for binary arithmetic operators apply. For plain and
328 long integers, the result is the same as ``(a // b, a % b)``. For floating point
329 numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a / b)``
330 but may be 1 less than that. In any case ``q * b + a % b`` is very close to
331 *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0 <= abs(a % b)
334 .. versionchanged:: 2.3
335 Using :func:`divmod` with complex numbers is deprecated.
338 .. function:: enumerate(sequence[, start=0])
340 Return an enumerate object. *sequence* must be a sequence, an
341 :term:`iterator`, or some other object which supports iteration. The
342 :meth:`next` method of the iterator returned by :func:`enumerate` returns a
343 tuple containing a count (from *start* which defaults to 0) and the
344 corresponding value obtained from iterating over *iterable*.
345 :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``,
346 ``(1, seq[1])``, ``(2, seq[2])``, .... For example:
348 >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter']):
355 .. versionadded:: 2.3
356 .. versionadded:: 2.6
357 The *start* parameter.
360 .. function:: eval(expression[, globals[, locals]])
362 The arguments are a string and optional globals and locals. If provided,
363 *globals* must be a dictionary. If provided, *locals* can be any mapping
366 .. versionchanged:: 2.4
367 formerly *locals* was required to be a dictionary.
369 The *expression* argument is parsed and evaluated as a Python expression
370 (technically speaking, a condition list) using the *globals* and *locals*
371 dictionaries as global and local namespace. If the *globals* dictionary is
372 present and lacks '__builtins__', the current globals are copied into *globals*
373 before *expression* is parsed. This means that *expression* normally has full
374 access to the standard :mod:`__builtin__` module and restricted environments are
375 propagated. If the *locals* dictionary is omitted it defaults to the *globals*
376 dictionary. If both dictionaries are omitted, the expression is executed in the
377 environment where :func:`eval` is called. The return value is the result of
378 the evaluated expression. Syntax errors are reported as exceptions. Example:
381 >>> print eval('x+1')
384 This function can also be used to execute arbitrary code objects (such as those
385 created by :func:`compile`). In this case pass a code object instead of a
386 string. The code object must have been compiled passing ``'eval'`` as the
389 Hints: dynamic execution of statements is supported by the :keyword:`exec`
390 statement. Execution of statements from a file is supported by the
391 :func:`execfile` function. The :func:`globals` and :func:`locals` functions
392 returns the current global and local dictionary, respectively, which may be
393 useful to pass around for use by :func:`eval` or :func:`execfile`.
396 .. function:: execfile(filename[, globals[, locals]])
398 This function is similar to the :keyword:`exec` statement, but parses a file
399 instead of a string. It is different from the :keyword:`import` statement in
400 that it does not use the module administration --- it reads the file
401 unconditionally and does not create a new module. [#]_
403 The arguments are a file name and two optional dictionaries. The file is parsed
404 and evaluated as a sequence of Python statements (similarly to a module) using
405 the *globals* and *locals* dictionaries as global and local namespace. If
406 provided, *locals* can be any mapping object.
408 .. versionchanged:: 2.4
409 formerly *locals* was required to be a dictionary.
411 If the *locals* dictionary is omitted it defaults to the *globals* dictionary.
412 If both dictionaries are omitted, the expression is executed in the environment
413 where :func:`execfile` is called. The return value is ``None``.
417 The default *locals* act as described for function :func:`locals` below:
418 modifications to the default *locals* dictionary should not be attempted. Pass
419 an explicit *locals* dictionary if you need to see effects of the code on
420 *locals* after function :func:`execfile` returns. :func:`execfile` cannot be
421 used reliably to modify a function's locals.
424 .. function:: file(filename[, mode[, bufsize]])
426 Constructor function for the :class:`file` type, described further in section
427 :ref:`bltin-file-objects`. The constructor's arguments are the same as those
428 of the :func:`open` built-in function described below.
430 When opening a file, it's preferable to use :func:`open` instead of invoking
431 this constructor directly. :class:`file` is more suited to type testing (for
432 example, writing ``isinstance(f, file)``).
434 .. versionadded:: 2.2
437 .. function:: filter(function, iterable)
439 Construct a list from those elements of *iterable* for which *function* returns
440 true. *iterable* may be either a sequence, a container which supports
441 iteration, or an iterator. If *iterable* is a string or a tuple, the result
442 also has that type; otherwise it is always a list. If *function* is ``None``,
443 the identity function is assumed, that is, all elements of *iterable* that are
446 Note that ``filter(function, iterable)`` is equivalent to ``[item for item in
447 iterable if function(item)]`` if function is not ``None`` and ``[item for item
448 in iterable if item]`` if function is ``None``.
451 .. function:: float([x])
453 Convert a string or a number to floating point. If the argument is a string, it
454 must contain a possibly signed decimal or floating point number, possibly
455 embedded in whitespace. The argument may also be [+|-]nan or [+|-]inf.
456 Otherwise, the argument may be a plain or long integer
457 or a floating point number, and a floating point number with the same value
458 (within Python's floating point precision) is returned. If no argument is
459 given, returns ``0.0``.
467 When passing in a string, values for NaN and Infinity may be returned, depending
468 on the underlying C library. Float accepts the strings nan, inf and -inf for
469 NaN and positive or negative infinity. The case and a leading + are ignored as
470 well as a leading - is ignored for NaN. Float always represents NaN and infinity
473 The float type is described in :ref:`typesnumeric`.
475 .. function:: frozenset([iterable])
478 Return a frozenset object, optionally with elements taken from *iterable*.
479 The frozenset type is described in :ref:`types-set`.
481 For other containers see the built in :class:`dict`, :class:`list`, and
482 :class:`tuple` classes, and the :mod:`collections` module.
484 .. versionadded:: 2.4
487 .. function:: getattr(object, name[, default])
489 Return the value of the named attributed of *object*. *name* must be a string.
490 If the string is the name of one of the object's attributes, the result is the
491 value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
492 ``x.foobar``. If the named attribute does not exist, *default* is returned if
493 provided, otherwise :exc:`AttributeError` is raised.
496 .. function:: globals()
498 Return a dictionary representing the current global symbol table. This is always
499 the dictionary of the current module (inside a function or method, this is the
500 module where it is defined, not the module from which it is called).
503 .. function:: hasattr(object, name)
505 The arguments are an object and a string. The result is ``True`` if the string
506 is the name of one of the object's attributes, ``False`` if not. (This is
507 implemented by calling ``getattr(object, name)`` and seeing whether it raises an
511 .. function:: hash(object)
513 Return the hash value of the object (if it has one). Hash values are integers.
514 They are used to quickly compare dictionary keys during a dictionary lookup.
515 Numeric values that compare equal have the same hash value (even if they are of
516 different types, as is the case for 1 and 1.0).
519 .. function:: help([object])
521 Invoke the built-in help system. (This function is intended for interactive
522 use.) If no argument is given, the interactive help system starts on the
523 interpreter console. If the argument is a string, then the string is looked up
524 as the name of a module, function, class, method, keyword, or documentation
525 topic, and a help page is printed on the console. If the argument is any other
526 kind of object, a help page on the object is generated.
528 This function is added to the built-in namespace by the :mod:`site` module.
530 .. versionadded:: 2.2
535 Convert an integer number (of any size) to a hexadecimal string. The result is a
536 valid Python expression.
538 .. versionchanged:: 2.4
539 Formerly only returned an unsigned literal.
542 .. function:: id(object)
544 Return the "identity" of an object. This is an integer (or long integer) which
545 is guaranteed to be unique and constant for this object during its lifetime.
546 Two objects with non-overlapping lifetimes may have the same :func:`id` value.
547 (Implementation note: this is the address of the object.)
550 .. function:: input([prompt])
552 Equivalent to ``eval(raw_input(prompt))``.
556 This function is not safe from user errors! It expects a valid Python
557 expression as input; if the input is not syntactically valid, a
558 :exc:`SyntaxError` will be raised. Other exceptions may be raised if there is an
559 error during evaluation. (On the other hand, sometimes this is exactly what you
560 need when writing a quick script for expert use.)
562 If the :mod:`readline` module was loaded, then :func:`input` will use it to
563 provide elaborate line editing and history features.
565 Consider using the :func:`raw_input` function for general input from users.
568 .. function:: int([x[, radix]])
570 Convert a string or number to a plain integer. If the argument is a string,
571 it must contain a possibly signed decimal number representable as a Python
572 integer, possibly embedded in whitespace. The *radix* parameter gives the
573 base for the conversion (which is 10 by default) and may be any integer in
574 the range [2, 36], or zero. If *radix* is zero, the proper radix is guessed
575 based on the contents of string; the interpretation is the same as for
576 integer literals. If *radix* is specified and *x* is not a string,
577 :exc:`TypeError` is raised. Otherwise, the argument may be a plain or long
578 integer or a floating point number. Conversion of floating point numbers to
579 integers truncates (towards zero). If the argument is outside the integer
580 range a long object will be returned instead. If no arguments are given,
583 The integer type is described in :ref:`typesnumeric`.
586 .. function:: isinstance(object, classinfo)
588 Return true if the *object* argument is an instance of the *classinfo* argument,
589 or of a (direct or indirect) subclass thereof. Also return true if *classinfo*
590 is a type object (new-style class) and *object* is an object of that type or of
591 a (direct or indirect) subclass thereof. If *object* is not a class instance or
592 an object of the given type, the function always returns false. If *classinfo*
593 is neither a class object nor a type object, it may be a tuple of class or type
594 objects, or may recursively contain other such tuples (other sequence types are
595 not accepted). If *classinfo* is not a class, type, or tuple of classes, types,
596 and such tuples, a :exc:`TypeError` exception is raised.
598 .. versionchanged:: 2.2
599 Support for a tuple of type information was added.
602 .. function:: issubclass(class, classinfo)
604 Return true if *class* is a subclass (direct or indirect) of *classinfo*. A
605 class is considered a subclass of itself. *classinfo* may be a tuple of class
606 objects, in which case every entry in *classinfo* will be checked. In any other
607 case, a :exc:`TypeError` exception is raised.
609 .. versionchanged:: 2.3
610 Support for a tuple of type information was added.
613 .. function:: iter(o[, sentinel])
615 Return an :term:`iterator` object. The first argument is interpreted very differently
616 depending on the presence of the second argument. Without a second argument, *o*
617 must be a collection object which supports the iteration protocol (the
618 :meth:`__iter__` method), or it must support the sequence protocol (the
619 :meth:`__getitem__` method with integer arguments starting at ``0``). If it
620 does not support either of those protocols, :exc:`TypeError` is raised. If the
621 second argument, *sentinel*, is given, then *o* must be a callable object. The
622 iterator created in this case will call *o* with no arguments for each call to
623 its :meth:`next` method; if the value returned is equal to *sentinel*,
624 :exc:`StopIteration` will be raised, otherwise the value will be returned.
626 .. versionadded:: 2.2
631 Return the length (the number of items) of an object. The argument may be a
632 sequence (string, tuple or list) or a mapping (dictionary).
635 .. function:: list([iterable])
637 Return a list whose items are the same and in the same order as *iterable*'s
638 items. *iterable* may be either a sequence, a container that supports
639 iteration, or an iterator object. If *iterable* is already a list, a copy is
640 made and returned, similar to ``iterable[:]``. For instance, ``list('abc')``
641 returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. If
642 no argument is given, returns a new empty list, ``[]``.
644 :class:`list` is a mutable sequence type, as documented in
645 :ref:`typesseq`. For other containers see the built in :class:`dict`,
646 :class:`set`, and :class:`tuple` classes, and the :mod:`collections` module.
649 .. function:: locals()
651 Update and return a dictionary representing the current local symbol table.
655 The contents of this dictionary should not be modified; changes may not affect
656 the values of local variables used by the interpreter.
658 Free variables are returned by :func:`locals` when it is called in a function block.
659 Modifications of free variables may not affect the values used by the
660 interpreter. Free variables are not returned in class blocks.
663 .. function:: long([x[, radix]])
665 Convert a string or number to a long integer. If the argument is a string, it
666 must contain a possibly signed number of arbitrary size, possibly embedded in
667 whitespace. The *radix* argument is interpreted in the same way as for
668 :func:`int`, and may only be given when *x* is a string. Otherwise, the argument
669 may be a plain or long integer or a floating point number, and a long integer
670 with the same value is returned. Conversion of floating point numbers to
671 integers truncates (towards zero). If no arguments are given, returns ``0L``.
673 The long type is described in :ref:`typesnumeric`.
675 .. function:: map(function, iterable, ...)
677 Apply *function* to every item of *iterable* and return a list of the results.
678 If additional *iterable* arguments are passed, *function* must take that many
679 arguments and is applied to the items from all iterables in parallel. If one
680 iterable is shorter than another it is assumed to be extended with ``None``
681 items. If *function* is ``None``, the identity function is assumed; if there
682 are multiple arguments, :func:`map` returns a list consisting of tuples
683 containing the corresponding items from all iterables (a kind of transpose
684 operation). The *iterable* arguments may be a sequence or any iterable object;
685 the result is always a list.
688 .. function:: max(iterable[, args...][key])
690 With a single argument *iterable*, return the largest item of a non-empty
691 iterable (such as a string, tuple or list). With more than one argument, return
692 the largest of the arguments.
694 The optional *key* argument specifies a one-argument ordering function like that
695 used for :meth:`list.sort`. The *key* argument, if supplied, must be in keyword
696 form (for example, ``max(a,b,c,key=func)``).
698 .. versionchanged:: 2.5
699 Added support for the optional *key* argument.
702 .. function:: min(iterable[, args...][key])
704 With a single argument *iterable*, return the smallest item of a non-empty
705 iterable (such as a string, tuple or list). With more than one argument, return
706 the smallest of the arguments.
708 The optional *key* argument specifies a one-argument ordering function like that
709 used for :meth:`list.sort`. The *key* argument, if supplied, must be in keyword
710 form (for example, ``min(a,b,c,key=func)``).
712 .. versionchanged:: 2.5
713 Added support for the optional *key* argument.
716 .. function:: next(iterator[, default])
718 Retrieve the next item from the *iterator* by calling its :meth:`next`
719 method. If *default* is given, it is returned if the iterator is exhausted,
720 otherwise :exc:`StopIteration` is raised.
722 .. versionadded:: 2.6
725 .. function:: object()
727 Return a new featureless object. :class:`object` is a base for all new style
728 classes. It has the methods that are common to all instances of new style
731 .. versionadded:: 2.2
733 .. versionchanged:: 2.3
734 This function does not accept any arguments. Formerly, it accepted arguments but
740 Convert an integer number (of any size) to an octal string. The result is a
741 valid Python expression.
743 .. versionchanged:: 2.4
744 Formerly only returned an unsigned literal.
747 .. function:: open(filename[, mode[, bufsize]])
749 Open a file, returning an object of the :class:`file` type described in
750 section :ref:`bltin-file-objects`. If the file cannot be opened,
751 :exc:`IOError` is raised. When opening a file, it's preferable to use
752 :func:`open` instead of invoking the :class:`file` constructor directly.
754 The first two arguments are the same as for ``stdio``'s :cfunc:`fopen`:
755 *filename* is the file name to be opened, and *mode* is a string indicating how
756 the file is to be opened.
758 The most commonly-used values of *mode* are ``'r'`` for reading, ``'w'`` for
759 writing (truncating the file if it already exists), and ``'a'`` for appending
760 (which on *some* Unix systems means that *all* writes append to the end of the
761 file regardless of the current seek position). If *mode* is omitted, it
762 defaults to ``'r'``. The default is to use text mode, which may convert
763 ``'\n'`` characters to a platform-specific representation on writing and back
764 on reading. Thus, when opening a binary file, you should append ``'b'`` to
765 the *mode* value to open the file in binary mode, which will improve
766 portability. (Appending ``'b'`` is useful even on systems that don't treat
767 binary and text files differently, where it serves as documentation.) See below
768 for more possible values of *mode*.
771 single: line-buffered I/O
772 single: unbuffered I/O
773 single: buffer size, I/O
774 single: I/O control; buffering
776 The optional *bufsize* argument specifies the file's desired buffer size: 0
777 means unbuffered, 1 means line buffered, any other positive value means use a
778 buffer of (approximately) that size. A negative *bufsize* means to use the
779 system default, which is usually line buffered for tty devices and fully
780 buffered for other files. If omitted, the system default is used. [#]_
782 Modes ``'r+'``, ``'w+'`` and ``'a+'`` open the file for updating (note that
783 ``'w+'`` truncates the file). Append ``'b'`` to the mode to open the file in
784 binary mode, on systems that differentiate between binary and text files; on
785 systems that don't have this distinction, adding the ``'b'`` has no effect.
787 In addition to the standard :cfunc:`fopen` values *mode* may be ``'U'`` or
788 ``'rU'``. Python is usually built with universal newline support; supplying
789 ``'U'`` opens the file as a text file, but lines may be terminated by any of the
790 following: the Unix end-of-line convention ``'\n'``, the Macintosh convention
791 ``'\r'``, or the Windows convention ``'\r\n'``. All of these external
792 representations are seen as ``'\n'`` by the Python program. If Python is built
793 without universal newline support a *mode* with ``'U'`` is the same as normal
794 text mode. Note that file objects so opened also have an attribute called
795 :attr:`newlines` which has a value of ``None`` (if no newlines have yet been
796 seen), ``'\n'``, ``'\r'``, ``'\r\n'``, or a tuple containing all the newline
799 Python enforces that the mode, after stripping ``'U'``, begins with ``'r'``,
802 Python provides many file handling modules including
803 :mod:`fileinput`, :mod:`os`, :mod:`os.path`, :mod:`tempfile`, and
806 .. versionchanged:: 2.5
807 Restriction on first letter of mode string introduced.
812 Given a string of length one, return an integer representing the Unicode code
813 point of the character when the argument is a unicode object, or the value of
814 the byte when the argument is an 8-bit string. For example, ``ord('a')`` returns
815 the integer ``97``, ``ord(u'\u2020')`` returns ``8224``. This is the inverse of
816 :func:`chr` for 8-bit strings and of :func:`unichr` for unicode objects. If a
817 unicode argument is given and Python was built with UCS2 Unicode, then the
818 character's code point must be in the range [0..65535] inclusive; otherwise the
819 string length is two, and a :exc:`TypeError` will be raised.
822 .. function:: pow(x, y[, z])
824 Return *x* to the power *y*; if *z* is present, return *x* to the power *y*,
825 modulo *z* (computed more efficiently than ``pow(x, y) % z``). The two-argument
826 form ``pow(x, y)`` is equivalent to using the power operator: ``x**y``.
828 The arguments must have numeric types. With mixed operand types, the coercion
829 rules for binary arithmetic operators apply. For int and long int operands, the
830 result has the same type as the operands (after coercion) unless the second
831 argument is negative; in that case, all arguments are converted to float and a
832 float result is delivered. For example, ``10**2`` returns ``100``, but
833 ``10**-2`` returns ``0.01``. (This last feature was added in Python 2.2. In
834 Python 2.1 and before, if both arguments were of integer types and the second
835 argument was negative, an exception was raised.) If the second argument is
836 negative, the third argument must be omitted. If *z* is present, *x* and *y*
837 must be of integer types, and *y* must be non-negative. (This restriction was
838 added in Python 2.2. In Python 2.1 and before, floating 3-argument ``pow()``
839 returned platform-dependent results depending on floating-point rounding
843 .. function:: print([object, ...][, sep=' '][, end='\n'][, file=sys.stdout])
845 Print *object*\(s) to the stream *file*, separated by *sep* and followed by
846 *end*. *sep*, *end* and *file*, if present, must be given as keyword
849 All non-keyword arguments are converted to strings like :func:`str` does and
850 written to the stream, separated by *sep* and followed by *end*. Both *sep*
851 and *end* must be strings; they can also be ``None``, which means to use the
852 default values. If no *object* is given, :func:`print` will just write
855 The *file* argument must be an object with a ``write(string)`` method; if it
856 is not present or ``None``, :data:`sys.stdout` will be used.
860 This function is not normally available as a builtin since the name
861 ``print`` is recognized as the :keyword:`print` statement. To disable the
862 statement and use the :func:`print` function, use this future statement at
863 the top of your module::
865 from __future__ import print_function
867 .. versionadded:: 2.6
870 .. function:: property([fget[, fset[, fdel[, doc]]]])
872 Return a property attribute for :term:`new-style class`\es (classes that
873 derive from :class:`object`).
875 *fget* is a function for getting an attribute value, likewise *fset* is a
876 function for setting, and *fdel* a function for del'ing, an attribute. Typical
877 use is to define a managed attribute x::
885 def setx(self, value):
889 x = property(getx, setx, delx, "I'm the 'x' property.")
891 If given, *doc* will be the docstring of the property attribute. Otherwise, the
892 property will copy *fget*'s docstring (if it exists). This makes it possible to
893 create read-only properties easily using :func:`property` as a :term:`decorator`::
895 class Parrot(object):
897 self._voltage = 100000
901 """Get the current voltage."""
904 turns the :meth:`voltage` method into a "getter" for a read-only attribute
907 A property object has :attr:`getter`, :attr:`setter`, and :attr:`deleter`
908 methods usable as decorators that create a copy of the property with the
909 corresponding accessor function set to the decorated function. This is
910 best explained with an example::
913 def __init__(self): self._x = None
917 """I'm the 'x' property."""
928 This code is exactly equivalent to the first example. Be sure to give the
929 additional functions the same name as the original property (``x`` in this
932 The returned property also has the attributes ``fget``, ``fset``, and
933 ``fdel`` corresponding to the constructor arguments.
935 .. versionadded:: 2.2
937 .. versionchanged:: 2.5
938 Use *fget*'s docstring if no *doc* given.
940 .. versionchanged:: 2.6
941 The ``getter``, ``setter``, and ``deleter`` attributes were added.
944 .. function:: range([start,] stop[, step])
946 This is a versatile function to create lists containing arithmetic progressions.
947 It is most often used in :keyword:`for` loops. The arguments must be plain
948 integers. If the *step* argument is omitted, it defaults to ``1``. If the
949 *start* argument is omitted, it defaults to ``0``. The full form returns a list
950 of plain integers ``[start, start + step, start + 2 * step, ...]``. If *step*
951 is positive, the last element is the largest ``start + i * step`` less than
952 *stop*; if *step* is negative, the last element is the smallest ``start + i *
953 step`` greater than *stop*. *step* must not be zero (or else :exc:`ValueError`
957 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
959 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
961 [0, 5, 10, 15, 20, 25]
964 >>> range(0, -10, -1)
965 [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
972 .. function:: raw_input([prompt])
974 If the *prompt* argument is present, it is written to standard output without a
975 trailing newline. The function then reads a line from input, converts it to a
976 string (stripping a trailing newline), and returns that. When EOF is read,
977 :exc:`EOFError` is raised. Example::
979 >>> s = raw_input('--> ')
980 --> Monty Python's Flying Circus
982 "Monty Python's Flying Circus"
984 If the :mod:`readline` module was loaded, then :func:`raw_input` will use it to
985 provide elaborate line editing and history features.
988 .. function:: reduce(function, iterable[, initializer])
990 Apply *function* of two arguments cumulatively to the items of *iterable*, from
991 left to right, so as to reduce the iterable to a single value. For example,
992 ``reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])`` calculates ``((((1+2)+3)+4)+5)``.
993 The left argument, *x*, is the accumulated value and the right argument, *y*, is
994 the update value from the *iterable*. If the optional *initializer* is present,
995 it is placed before the items of the iterable in the calculation, and serves as
996 a default when the iterable is empty. If *initializer* is not given and
997 *iterable* contains only one item, the first item is returned.
1000 .. function:: reload(module)
1002 Reload a previously imported *module*. The argument must be a module object, so
1003 it must have been successfully imported before. This is useful if you have
1004 edited the module source file using an external editor and want to try out the
1005 new version without leaving the Python interpreter. The return value is the
1006 module object (the same as the *module* argument).
1008 When ``reload(module)`` is executed:
1010 * Python modules' code is recompiled and the module-level code reexecuted,
1011 defining a new set of objects which are bound to names in the module's
1012 dictionary. The ``init`` function of extension modules is not called a second
1015 * As with all other objects in Python the old objects are only reclaimed after
1016 their reference counts drop to zero.
1018 * The names in the module namespace are updated to point to any new or changed
1021 * Other references to the old objects (such as names external to the module) are
1022 not rebound to refer to the new objects and must be updated in each namespace
1023 where they occur if that is desired.
1025 There are a number of other caveats:
1027 If a module is syntactically correct but its initialization fails, the first
1028 :keyword:`import` statement for it does not bind its name locally, but does
1029 store a (partially initialized) module object in ``sys.modules``. To reload the
1030 module you must first :keyword:`import` it again (this will bind the name to the
1031 partially initialized module object) before you can :func:`reload` it.
1033 When a module is reloaded, its dictionary (containing the module's global
1034 variables) is retained. Redefinitions of names will override the old
1035 definitions, so this is generally not a problem. If the new version of a module
1036 does not define a name that was defined by the old version, the old definition
1037 remains. This feature can be used to the module's advantage if it maintains a
1038 global table or cache of objects --- with a :keyword:`try` statement it can test
1039 for the table's presence and skip its initialization if desired::
1046 It is legal though generally not very useful to reload built-in or dynamically
1047 loaded modules, except for :mod:`sys`, :mod:`__main__` and :mod:`__builtin__`.
1048 In many cases, however, extension modules are not designed to be initialized
1049 more than once, and may fail in arbitrary ways when reloaded.
1051 If a module imports objects from another module using :keyword:`from` ...
1052 :keyword:`import` ..., calling :func:`reload` for the other module does not
1053 redefine the objects imported from it --- one way around this is to re-execute
1054 the :keyword:`from` statement, another is to use :keyword:`import` and qualified
1055 names (*module*.*name*) instead.
1057 If a module instantiates instances of a class, reloading the module that defines
1058 the class does not affect the method definitions of the instances --- they
1059 continue to use the old class definition. The same is true for derived classes.
1062 .. function:: repr(object)
1064 Return a string containing a printable representation of an object. This is
1065 the same value yielded by conversions (reverse quotes). It is sometimes
1066 useful to be able to access this operation as an ordinary function. For many
1067 types, this function makes an attempt to return a string that would yield an
1068 object with the same value when passed to :func:`eval`, otherwise the
1069 representation is a string enclosed in angle brackets that contains the name
1070 of the type of the object together with additional information often
1071 including the name and address of the object. A class can control what this
1072 function returns for its instances by defining a :meth:`__repr__` method.
1075 .. function:: reversed(seq)
1077 Return a reverse :term:`iterator`. *seq* must be an object which has
1078 a :meth:`__reversed__` method or supports the sequence protocol (the
1079 :meth:`__len__` method and the :meth:`__getitem__` method with integer
1080 arguments starting at ``0``).
1082 .. versionadded:: 2.4
1084 .. versionchanged:: 2.6
1085 Added the possibility to write a custom :meth:`__reversed__` method.
1088 .. function:: round(x[, n])
1090 Return the floating point value *x* rounded to *n* digits after the decimal
1091 point. If *n* is omitted, it defaults to zero. The result is a floating point
1092 number. Values are rounded to the closest multiple of 10 to the power minus
1093 *n*; if two multiples are equally close, rounding is done away from 0 (so. for
1094 example, ``round(0.5)`` is ``1.0`` and ``round(-0.5)`` is ``-1.0``).
1097 .. function:: set([iterable])
1100 Return a new set, optionally with elements are taken from *iterable*.
1101 The set type is described in :ref:`types-set`.
1103 For other containers see the built in :class:`dict`, :class:`list`, and
1104 :class:`tuple` classes, and the :mod:`collections` module.
1106 .. versionadded:: 2.4
1109 .. function:: setattr(object, name, value)
1111 This is the counterpart of :func:`getattr`. The arguments are an object, a
1112 string and an arbitrary value. The string may name an existing attribute or a
1113 new attribute. The function assigns the value to the attribute, provided the
1114 object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to
1118 .. function:: slice([start,] stop[, step])
1120 .. index:: single: Numerical Python
1122 Return a :term:`slice` object representing the set of indices specified by
1123 ``range(start, stop, step)``. The *start* and *step* arguments default to
1124 ``None``. Slice objects have read-only data attributes :attr:`start`,
1125 :attr:`stop` and :attr:`step` which merely return the argument values (or their
1126 default). They have no other explicit functionality; however they are used by
1127 Numerical Python and other third party extensions. Slice objects are also
1128 generated when extended indexing syntax is used. For example:
1129 ``a[start:stop:step]`` or ``a[start:stop, i]``.
1132 .. function:: sorted(iterable[, cmp[, key[, reverse]]])
1134 Return a new sorted list from the items in *iterable*.
1136 The optional arguments *cmp*, *key*, and *reverse* have the same meaning as
1137 those for the :meth:`list.sort` method (described in section
1138 :ref:`typesseq-mutable`).
1140 *cmp* specifies a custom comparison function of two arguments (iterable
1141 elements) which should return a negative, zero or positive number depending on
1142 whether the first argument is considered smaller than, equal to, or larger than
1143 the second argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``. The default
1146 *key* specifies a function of one argument that is used to extract a comparison
1147 key from each list element: ``key=str.lower``. The default value is ``None``.
1149 *reverse* is a boolean value. If set to ``True``, then the list elements are
1150 sorted as if each comparison were reversed.
1152 In general, the *key* and *reverse* conversion processes are much faster than
1153 specifying an equivalent *cmp* function. This is because *cmp* is called
1154 multiple times for each list element while *key* and *reverse* touch each
1157 .. versionadded:: 2.4
1160 .. function:: staticmethod(function)
1162 Return a static method for *function*.
1164 A static method does not receive an implicit first argument. To declare a static
1165 method, use this idiom::
1169 def f(arg1, arg2, ...): ...
1171 The ``@staticmethod`` form is a function :term:`decorator` -- see the
1172 description of function definitions in :ref:`function` for details.
1174 It can be called either on the class (such as ``C.f()``) or on an instance (such
1175 as ``C().f()``). The instance is ignored except for its class.
1177 Static methods in Python are similar to those found in Java or C++. For a more
1178 advanced concept, see :func:`classmethod` in this section.
1180 For more information on static methods, consult the documentation on the
1181 standard type hierarchy in :ref:`types`.
1183 .. versionadded:: 2.2
1185 .. versionchanged:: 2.4
1186 Function decorator syntax added.
1189 .. function:: str([object])
1191 Return a string containing a nicely printable representation of an object. For
1192 strings, this returns the string itself. The difference with ``repr(object)``
1193 is that ``str(object)`` does not always attempt to return a string that is
1194 acceptable to :func:`eval`; its goal is to return a printable string. If no
1195 argument is given, returns the empty string, ``''``.
1197 For more information on strings see :ref:`typesseq` which describes sequence
1198 functionality (strings are sequences), and also the string-specific methods
1199 described in the :ref:`string-methods` section. To output formatted strings
1200 use template strings or the ``%`` operator described in the
1201 :ref:`string-formatting` section. In addition see the :ref:`stringservices`
1202 section. See also :func:`unicode`.
1205 .. function:: sum(iterable[, start])
1207 Sums *start* and the items of an *iterable* from left to right and returns the
1208 total. *start* defaults to ``0``. The *iterable*'s items are normally numbers,
1209 and are not allowed to be strings. The fast, correct way to concatenate a
1210 sequence of strings is by calling ``''.join(sequence)``. Note that
1211 ``sum(range(n), m)`` is equivalent to ``reduce(operator.add, range(n), m)``
1213 .. versionadded:: 2.3
1216 .. function:: super(type[, object-or-type])
1218 Return the superclass of *type*. If the second argument is omitted the super
1219 object returned is unbound. If the second argument is an object,
1220 ``isinstance(obj, type)`` must be true. If the second argument is a type,
1221 ``issubclass(type2, type)`` must be true. :func:`super` only works for
1222 :term:`new-style class`\es.
1224 A typical use for calling a cooperative superclass method is::
1227 def meth(self, arg):
1228 super(C, self).meth(arg)
1230 Note that :func:`super` is implemented as part of the binding process for
1231 explicit dotted attribute lookups such as ``super(C, self).__getitem__(name)``.
1232 Accordingly, :func:`super` is undefined for implicit lookups using statements or
1233 operators such as ``super(C, self)[name]``.
1235 .. versionadded:: 2.2
1238 .. function:: tuple([iterable])
1240 Return a tuple whose items are the same and in the same order as *iterable*'s
1241 items. *iterable* may be a sequence, a container that supports iteration, or an
1242 iterator object. If *iterable* is already a tuple, it is returned unchanged.
1243 For instance, ``tuple('abc')`` returns ``('a', 'b', 'c')`` and ``tuple([1, 2,
1244 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty
1247 :class:`tuple` is an immutable sequence type, as documented in
1248 :ref:`typesseq`. For other containers see the built in :class:`dict`,
1249 :class:`list`, and :class:`set` classes, and the :mod:`collections` module.
1252 .. function:: type(object)
1254 .. index:: object: type
1256 Return the type of an *object*. The return value is a type object. The
1257 :func:`isinstance` built-in function is recommended for testing the type of an
1260 With three arguments, :func:`type` functions as a constructor as detailed below.
1263 .. function:: type(name, bases, dict)
1266 Return a new type object. This is essentially a dynamic form of the
1267 :keyword:`class` statement. The *name* string is the class name and becomes the
1268 :attr:`__name__` attribute; the *bases* tuple itemizes the base classes and
1269 becomes the :attr:`__bases__` attribute; and the *dict* dictionary is the
1270 namespace containing definitions for class body and becomes the :attr:`__dict__`
1271 attribute. For example, the following two statements create identical
1272 :class:`type` objects:
1274 >>> class X(object):
1277 >>> X = type('X', (object,), dict(a=1))
1279 .. versionadded:: 2.2
1282 .. function:: unichr(i)
1284 Return the Unicode string of one character whose Unicode code is the integer
1285 *i*. For example, ``unichr(97)`` returns the string ``u'a'``. This is the
1286 inverse of :func:`ord` for Unicode strings. The valid range for the argument
1287 depends how Python was configured -- it may be either UCS2 [0..0xFFFF] or UCS4
1288 [0..0x10FFFF]. :exc:`ValueError` is raised otherwise. For ASCII and 8-bit
1289 strings see :func:`chr`.
1291 .. versionadded:: 2.0
1294 .. function:: unicode([object[, encoding [, errors]]])
1296 Return the Unicode string version of *object* using one of the following modes:
1298 If *encoding* and/or *errors* are given, ``unicode()`` will decode the object
1299 which can either be an 8-bit string or a character buffer using the codec for
1300 *encoding*. The *encoding* parameter is a string giving the name of an encoding;
1301 if the encoding is not known, :exc:`LookupError` is raised. Error handling is
1302 done according to *errors*; this specifies the treatment of characters which are
1303 invalid in the input encoding. If *errors* is ``'strict'`` (the default), a
1304 :exc:`ValueError` is raised on errors, while a value of ``'ignore'`` causes
1305 errors to be silently ignored, and a value of ``'replace'`` causes the official
1306 Unicode replacement character, ``U+FFFD``, to be used to replace input
1307 characters which cannot be decoded. See also the :mod:`codecs` module.
1309 If no optional parameters are given, ``unicode()`` will mimic the behaviour of
1310 ``str()`` except that it returns Unicode strings instead of 8-bit strings. More
1311 precisely, if *object* is a Unicode string or subclass it will return that
1312 Unicode string without any additional decoding applied.
1314 For objects which provide a :meth:`__unicode__` method, it will call this method
1315 without arguments to create a Unicode string. For all other objects, the 8-bit
1316 string version or representation is requested and then converted to a Unicode
1317 string using the codec for the default encoding in ``'strict'`` mode.
1319 For more information on Unicode strings see :ref:`typesseq` which describes
1320 sequence functionality (Unicode strings are sequences), and also the
1321 string-specific methods described in the :ref:`string-methods` section. To
1322 output formatted strings use template strings or the ``%`` operator described
1323 in the :ref:`string-formatting` section. In addition see the
1324 :ref:`stringservices` section. See also :func:`str`.
1326 .. versionadded:: 2.0
1328 .. versionchanged:: 2.2
1329 Support for :meth:`__unicode__` added.
1332 .. function:: vars([object])
1334 Without arguments, return a dictionary corresponding to the current local symbol
1335 table. With a module, class or class instance object as argument (or anything
1336 else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
1337 to the object's symbol table. The returned dictionary should not be modified:
1338 the effects on the corresponding symbol table are undefined. [#]_
1341 .. function:: xrange([start,] stop[, step])
1343 This function is very similar to :func:`range`, but returns an "xrange object"
1344 instead of a list. This is an opaque sequence type which yields the same values
1345 as the corresponding list, without actually storing them all simultaneously.
1346 The advantage of :func:`xrange` over :func:`range` is minimal (since
1347 :func:`xrange` still has to create the values when asked for them) except when a
1348 very large range is used on a memory-starved machine or when all of the range's
1349 elements are never used (such as when the loop is usually terminated with
1354 :func:`xrange` is intended to be simple and fast. Implementations may impose
1355 restrictions to achieve this. The C implementation of Python restricts all
1356 arguments to native C longs ("short" Python integers), and also requires that
1357 the number of elements fit in a native C long.
1360 .. function:: zip([iterable, ...])
1362 This function returns a list of tuples, where the *i*-th tuple contains the
1363 *i*-th element from each of the argument sequences or iterables. The returned
1364 list is truncated in length to the length of the shortest argument sequence.
1365 When there are multiple arguments which are all of the same length, :func:`zip`
1366 is similar to :func:`map` with an initial argument of ``None``. With a single
1367 sequence argument, it returns a list of 1-tuples. With no arguments, it returns
1370 The left-to-right evaluation order of the iterables is guaranteed. This
1371 makes possible an idiom for clustering a data series into n-length groups
1372 using ``zip(*[iter(s)]*n)``.
1374 .. versionadded:: 2.0
1376 .. versionchanged:: 2.4
1377 Formerly, :func:`zip` required at least one argument and ``zip()`` raised a
1378 :exc:`TypeError` instead of returning an empty list.
1380 .. ---------------------------------------------------------------------------
1383 .. _non-essential-built-in-funcs:
1385 Non-essential Built-in Functions
1386 ================================
1388 There are several built-in functions that are no longer essential to learn, know
1389 or use in modern Python programming. They have been kept here to maintain
1390 backwards compatibility with programs written for older versions of Python.
1392 Python programmers, trainers, students and bookwriters should feel free to
1393 bypass these functions without concerns about missing something important.
1396 .. function:: apply(function, args[, keywords])
1398 The *function* argument must be a callable object (a user-defined or built-in
1399 function or method, or a class object) and the *args* argument must be a
1400 sequence. The *function* is called with *args* as the argument list; the number
1401 of arguments is the length of the tuple. If the optional *keywords* argument is
1402 present, it must be a dictionary whose keys are strings. It specifies keyword
1403 arguments to be added to the end of the argument list. Calling :func:`apply` is
1404 different from just calling ``function(args)``, since in that case there is
1405 always exactly one argument. The use of :func:`apply` is equivalent to
1406 ``function(*args, **keywords)``.
1409 Use the extended call syntax with ``*args`` and ``**keywords`` instead.
1412 .. function:: buffer(object[, offset[, size]])
1414 The *object* argument must be an object that supports the buffer call interface
1415 (such as strings, arrays, and buffers). A new buffer object will be created
1416 which references the *object* argument. The buffer object will be a slice from
1417 the beginning of *object* (or from the specified *offset*). The slice will
1418 extend to the end of *object* (or will have a length given by the *size*
1422 .. function:: coerce(x, y)
1424 Return a tuple consisting of the two numeric arguments converted to a common
1425 type, using the same rules as used by arithmetic operations. If coercion is not
1426 possible, raise :exc:`TypeError`.
1429 .. function:: intern(string)
1431 Enter *string* in the table of "interned" strings and return the interned string
1432 -- which is *string* itself or a copy. Interning strings is useful to gain a
1433 little performance on dictionary lookup -- if the keys in a dictionary are
1434 interned, and the lookup key is interned, the key comparisons (after hashing)
1435 can be done by a pointer compare instead of a string compare. Normally, the
1436 names used in Python programs are automatically interned, and the dictionaries
1437 used to hold module, class or instance attributes have interned keys.
1439 .. versionchanged:: 2.3
1440 Interned strings are not immortal (like they used to be in Python 2.2 and
1441 before); you must keep a reference to the return value of :func:`intern` around
1444 .. rubric:: Footnotes
1446 .. [#] It is used relatively rarely so does not warrant being made into a statement.
1448 .. [#] Specifying a buffer size currently has no effect on systems that don't have
1449 :cfunc:`setvbuf`. The interface to specify the buffer size is not done using a
1450 method that calls :cfunc:`setvbuf`, because that may dump core when called after
1451 any I/O has been performed, and there's no reliable way to determine whether
1454 .. [#] In the current implementation, local variable bindings cannot normally be
1455 affected this way, but variables retrieved from other scopes (such as modules)
1456 can be. This may change.