.. _built-in-funcs:

Built-in Functions

==================

The Python interpreter has a number of functions built into it that are always

available.  They are listed here in alphabetical order.

.. function:: __import__(name[, globals[, locals[, fromlist[, level]]]])

   .. index::

      statement: import

      module: ihooks

      module: rexec

      module: imp

   .. note::

      This is an advanced function that is not needed in everyday Python

      programming.

   The function is invoked by the :keyword:`import` statement.  It mainly exists

   so that you can replace it with another function that has a compatible

   interface, in order to change the semantics of the :keyword:`import` statement.

   See the built-in module :mod:`imp`, which defines some useful operations out

   of which you can build your own :func:`__import__` function.

   For example, the statement ``import spam`` results in the following call:

   ``__import__('spam', globals(), locals(), [], -1)``; the statement

   ``from spam.ham import eggs`` results in ``__import__('spam.ham', globals(),

   locals(), ['eggs'], -1)``.  Note that even though ``locals()`` and ``['eggs']``

   are passed in as arguments, the :func:`__import__` function does not set the

   local variable named ``eggs``; this is done by subsequent code that is generated

   for the import statement.  (In fact, the standard implementation does not use

   its *locals* argument at all, and uses its *globals* only to determine the

   package context of the :keyword:`import` statement.)

   When the *name* variable is of the form ``package.module``, normally, the

   top-level package (the name up till the first dot) is returned, *not* the

   module named by *name*.  However, when a non-empty *fromlist* argument is

   given, the module named by *name* is returned.  This is done for

   compatibility with the :term:`bytecode` generated for the different kinds of import

   statement; when using ``import spam.ham.eggs``, the top-level package

   :mod:`spam` must be placed in the importing namespace, but when using ``from

   spam.ham import eggs``, the ``spam.ham`` subpackage must be used to find the

   ``eggs`` variable.  As a workaround for this behavior, use :func:`getattr` to

   extract the desired components.  For example, you could define the following

   helper::

      def my_import(name):

          mod = __import__(name)

          components = name.split('.')

          for comp in components[1:]:

              mod = getattr(mod, comp)

          return mod

   *level* specifies whether to use absolute or relative imports. The default is

   ``-1`` which indicates both absolute and relative imports will be attempted.

   ``0`` means only perform absolute imports. Positive values for *level* indicate

   the number of parent directories to search relative to the directory of the

   module calling :func:`__import__`.

   .. versionchanged:: 2.5

      The level parameter was added.

   .. versionchanged:: 2.5

      Keyword support for parameters was added.

.. function:: abs(x)

   Return the absolute value of a number.  The argument may be a plain or long

   integer or a floating point number.  If the argument is a complex number, its

   magnitude is returned.

.. function:: all(iterable)

   Return True if all elements of the *iterable* are true. Equivalent to::

      def all(iterable):

          for element in iterable:

              if not element:

                  return False

          return True

   .. versionadded:: 2.5

.. function:: any(iterable)

   Return True if any element of the *iterable* is true. Equivalent to::

      def any(iterable):

          for element in iterable:

              if element:

                  return True

          return False

   .. versionadded:: 2.5

.. function:: basestring()

   This abstract type is the superclass for :class:`str` and :class:`unicode`. It

   cannot be called or instantiated, but it can be used to test whether an object

   is an instance of :class:`str` or :class:`unicode`. ``isinstance(obj,

   basestring)`` is equivalent to ``isinstance(obj, (str, unicode))``.

   .. versionadded:: 2.3

.. function:: bin(x)

   Convert an integer number to a binary string. The result is a valid Python

   expression.  If *x* is not a Python :class:`int` object, it has to define an

   :meth:`__index__` method that returns an integer.

   .. versionadded:: 2.6

.. function:: bool([x])

   Convert a value to a Boolean, using the standard truth testing procedure.  If

   *x* is false or omitted, this returns :const:`False`; otherwise it returns

   :const:`True`. :class:`bool` is also a class, which is a subclass of

   :class:`int`. Class :class:`bool` cannot be subclassed further.  Its only

   instances are :const:`False` and :const:`True`.

   .. index:: pair: Boolean; type

   .. versionadded:: 2.2.1

   .. versionchanged:: 2.3

      If no argument is given, this function returns :const:`False`.

.. function:: callable(object)

   Return :const:`True` if the *object* argument appears callable,

   :const:`False` if not.  If this

   returns true, it is still possible that a call fails, but if it is false,

   calling *object* will never succeed.  Note that classes are callable (calling a

   class returns a new instance); class instances are callable if they have a

   :meth:`__call__` method.

.. function:: chr(i)

   Return a string of one character whose ASCII code is the integer *i*.  For

   example, ``chr(97)`` returns the string ``'a'``. This is the inverse of

   :func:`ord`.  The argument must be in the range [0..255], inclusive;

   :exc:`ValueError` will be raised if *i* is outside that range. See

   also :func:`unichr`.

.. function:: classmethod(function)

   Return a class method for *function*.

   A class method receives the class as implicit first argument, just like an

   instance method receives the instance. To declare a class method, use this

   idiom::

      class C:

          @classmethod

          def f(cls, arg1, arg2, ...): ...

   The ``@classmethod`` form is a function :term:`decorator` -- see the description

   of function definitions in :ref:`function` for details.

   It can be called either on the class (such as ``C.f()``) or on an instance (such

   as ``C().f()``).  The instance is ignored except for its class. If a class

   method is called for a derived class, the derived class object is passed as the

   implied first argument.

   Class methods are different than C++ or Java static methods. If you want those,

   see :func:`staticmethod` in this section.

   For more information on class methods, consult the documentation on the standard

   type hierarchy in :ref:`types`.

   .. versionadded:: 2.2

   .. versionchanged:: 2.4

      Function decorator syntax added.

.. function:: cmp(x, y)

   Compare the two objects *x* and *y* and return an integer according to the

   outcome.  The return value is negative if ``x < y``, zero if ``x == y`` and

   strictly positive if ``x > y``.

.. function:: compile(source, filename, mode[, flags[, dont_inherit]])

   Compile the *source* into a code or AST object.  Code objects can be executed

   by an :keyword:`exec` statement or evaluated by a call to :func:`eval`.

   *source* can either be a string or an AST object.  Refer to the :mod:`_ast`

   module documentation for information on how to compile into and from AST

   objects.

   When compiling a string with multi-line statements, two caveats apply: line

   endings must be represented by a single newline character (``'\n'``), and the

   input must be terminated by at least one newline character.  If line endings

   are represented by ``'\r\n'``, use the string :meth:`replace` method to

   change them into ``'\n'``.

   The *filename* argument should give the file from which the code was read;

   pass some recognizable value if it wasn't read from a file (``'<string>'`` is

   commonly used).

   The *mode* argument specifies what kind of code must be compiled; it can be

   ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it

   consists of a single expression, or ``'single'`` if it consists of a single

   interactive statement (in the latter case, expression statements that

   evaluate to something else than ``None`` will be printed).

   The optional arguments *flags* and *dont_inherit* (which are new in Python 2.2)

   control which future statements (see :pep:`236`) affect the compilation of

   *source*.  If neither is present (or both are zero) the code is compiled with

   those future statements that are in effect in the code that is calling compile.

   If the *flags* argument is given and *dont_inherit* is not (or is zero) then the

   future statements specified by the *flags* argument are used in addition to

   those that would be used anyway. If *dont_inherit* is a non-zero integer then

   the *flags* argument is it -- the future statements in effect around the call to

   compile are ignored.

   Future statements are specified by bits which can be bitwise ORed together to

   specify multiple statements.  The bitfield required to specify a given feature

   can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`

   instance in the :mod:`__future__` module.

   This function raises :exc:`SyntaxError` if the compiled source is invalid,

   and :exc:`TypeError` if the source contains null bytes.

   .. versionadded:: 2.6

      Support for compiling AST objects.

.. function:: complex([real[, imag]])

   Create a complex number with the value *real* + *imag*\*j or convert a string or

   number to a complex number.  If the first parameter is a string, it will be

   interpreted as a complex number and the function must be called without a second

   parameter.  The second parameter can never be a string. Each argument may be any

   numeric type (including complex). If *imag* is omitted, it defaults to zero and

   the function serves as a numeric conversion function like :func:`int`,

   :func:`long` and :func:`float`.  If both arguments are omitted, returns ``0j``.

   The complex type is described in :ref:`typesnumeric`.

.. function:: delattr(object, name)

   This is a relative of :func:`setattr`.  The arguments are an object and a

   string.  The string must be the name of one of the object's attributes.  The

   function deletes the named attribute, provided the object allows it.  For

   example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.

.. function:: dict([arg])

   :noindex:

   Create a new data dictionary, optionally with items taken from *arg*.

   The dictionary type is described in :ref:`typesmapping`.

   For other containers see the built in :class:`list`, :class:`set`, and

   :class:`tuple` classes, and the :mod:`collections` module.

.. function:: dir([object])

   Without arguments, return the list of names in the current local scope.  With an

   argument, attempt to return a list of valid attributes for that object.

   If the object has a method named :meth:`__dir__`, this method will be called and

   must return the list of attributes. This allows objects that implement a custom

   :func:`__getattr__` or :func:`__getattribute__` function to customize the way

   :func:`dir` reports their attributes.

   If the object does not provide :meth:`__dir__`, the function tries its best to

   gather information from the object's :attr:`__dict__` attribute, if defined, and

   from its type object.  The resulting list is not necessarily complete, and may

   be inaccurate when the object has a custom :func:`__getattr__`.

   The default :func:`dir` mechanism behaves differently with different types of

   objects, as it attempts to produce the most relevant, rather than complete,

   information:

   * If the object is a module object, the list contains the names of the module's

     attributes.

   * If the object is a type or class object, the list contains the names of its

     attributes, and recursively of the attributes of its bases.

   * Otherwise, the list contains the object's attributes' names, the names of its

     class's attributes, and recursively of the attributes of its class's base

     classes.

   The resulting list is sorted alphabetically.  For example:

      >>> import struct

      >>> dir()   # doctest: +SKIP

      ['__builtins__', '__doc__', '__name__', 'struct']

      >>> dir(struct)   # doctest: +NORMALIZE_WHITESPACE

      ['Struct', '__builtins__', '__doc__', '__file__', '__name__',

       '__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',

       'unpack', 'unpack_from']

      >>> class Foo(object):

      ...     def __dir__(self):

      ...         return ["kan", "ga", "roo"]

      ...

      >>> f = Foo()

      >>> dir(f)

      ['ga', 'kan', 'roo']

   .. note::

      Because :func:`dir` is supplied primarily as a convenience for use at an

      interactive prompt, it tries to supply an interesting set of names more than it

      tries to supply a rigorously or consistently defined set of names, and its

      detailed behavior may change across releases.  For example, metaclass attributes

      are not in the result list when the argument is a class.

.. function:: divmod(a, b)

   Take two (non complex) numbers as arguments and return a pair of numbers

   consisting of their quotient and remainder when using long division.  With mixed

   operand types, the rules for binary arithmetic operators apply.  For plain and

   long integers, the result is the same as ``(a // b, a % b)``. For floating point

   numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a / b)``

   but may be 1 less than that.  In any case ``q * b + a % b`` is very close to

   *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0 <= abs(a % b)

   < abs(b)``.

   .. versionchanged:: 2.3

      Using :func:`divmod` with complex numbers is deprecated.

.. function:: enumerate(sequence[, start=0])

   Return an enumerate object. *sequence* must be a sequence, an

   :term:`iterator`, or some other object which supports iteration.  The

   :meth:`next` method of the iterator returned by :func:`enumerate` returns a

   tuple containing a count (from *start* which defaults to 0) and the

   corresponding value obtained from iterating over *iterable*.

   :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``,

   ``(1, seq[1])``, ``(2, seq[2])``, .... For example:

      >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter']):

      ...     print i, season

      0 Spring

      1 Summer

      2 Fall

      3 Winter

   .. versionadded:: 2.3

   .. versionadded:: 2.6

      The *start* parameter.

.. function:: eval(expression[, globals[, locals]])

   The arguments are a string and optional globals and locals.  If provided,

   *globals* must be a dictionary.  If provided, *locals* can be any mapping

   object.

   .. versionchanged:: 2.4

      formerly *locals* was required to be a dictionary.

   The *expression* argument is parsed and evaluated as a Python expression

   (technically speaking, a condition list) using the *globals* and *locals*

   dictionaries as global and local namespace.  If the *globals* dictionary is

   present and lacks '__builtins__', the current globals are copied into *globals*

   before *expression* is parsed.  This means that *expression* normally has full

   access to the standard :mod:`__builtin__` module and restricted environments are

   propagated.  If the *locals* dictionary is omitted it defaults to the *globals*

   dictionary.  If both dictionaries are omitted, the expression is executed in the

   environment where :func:`eval` is called.  The return value is the result of

   the evaluated expression. Syntax errors are reported as exceptions.  Example:

      >>> x = 1

      >>> print eval('x+1')

      2

   This function can also be used to execute arbitrary code objects (such as

   those created by :func:`compile`).  In this case pass a code object instead

   of a string.  If the code object has been compiled with ``'exec'`` as the

   *kind* argument, :func:`eval`\'s return value will be ``None``.

   Hints: dynamic execution of statements is supported by the :keyword:`exec`

   statement.  Execution of statements from a file is supported by the

   :func:`execfile` function.  The :func:`globals` and :func:`locals` functions

   returns the current global and local dictionary, respectively, which may be

   useful to pass around for use by :func:`eval` or :func:`execfile`.

.. function:: execfile(filename[, globals[, locals]])

   This function is similar to the :keyword:`exec` statement, but parses a file

   instead of a string.  It is different from the :keyword:`import` statement in

   that it does not use the module administration --- it reads the file

   unconditionally and does not create a new module. [#]_

   The arguments are a file name and two optional dictionaries.  The file is parsed

   and evaluated as a sequence of Python statements (similarly to a module) using

   the *globals* and *locals* dictionaries as global and local namespace. If

   provided, *locals* can be any mapping object.

   .. versionchanged:: 2.4

      formerly *locals* was required to be a dictionary.

   If the *locals* dictionary is omitted it defaults to the *globals* dictionary.

   If both dictionaries are omitted, the expression is executed in the environment

   where :func:`execfile` is called.  The return value is ``None``.

   .. warning::

      The default *locals* act as described for function :func:`locals` below:

      modifications to the default *locals* dictionary should not be attempted.  Pass

      an explicit *locals* dictionary if you need to see effects of the code on

      *locals* after function :func:`execfile` returns.  :func:`execfile` cannot be

      used reliably to modify a function's locals.

.. function:: file(filename[, mode[, bufsize]])

   Constructor function for the :class:`file` type, described further in section

   :ref:`bltin-file-objects`.  The constructor's arguments are the same as those

   of the :func:`open` built-in function described below.

   When opening a file, it's preferable to use :func:`open` instead of  invoking

   this constructor directly.  :class:`file` is more suited to type testing (for

   example, writing ``isinstance(f, file)``).

   .. versionadded:: 2.2

.. function:: filter(function, iterable)

   Construct a list from those elements of *iterable* for which *function* returns

   true.  *iterable* may be either a sequence, a container which supports

   iteration, or an iterator.  If *iterable* is a string or a tuple, the result

   also has that type; otherwise it is always a list.  If *function* is ``None``,

   the identity function is assumed, that is, all elements of *iterable* that are

   false are removed.

   Note that ``filter(function, iterable)`` is equivalent to ``[item for item in

   iterable if function(item)]`` if function is not ``None`` and ``[item for item

   in iterable if item]`` if function is ``None``.

.. function:: float([x])

   Convert a string or a number to floating point.  If the argument is a string, it

   must contain a possibly signed decimal or floating point number, possibly

   embedded in whitespace. The argument may also be [+|-]nan or [+|-]inf.

   Otherwise, the argument may be a plain or long integer

   or a floating point number, and a floating point number with the same value

   (within Python's floating point precision) is returned.  If no argument is

   given, returns ``0.0``.

   .. note::

      .. index::

         single: NaN

         single: Infinity

      When passing in a string, values for NaN and Infinity may be returned, depending

      on the underlying C library.  Float accepts the strings nan, inf and -inf for

      NaN and positive or negative infinity. The case and a leading + are ignored as

      well as a leading - is ignored for NaN. Float always represents NaN and infinity

      as nan, inf or -inf.

   The float type is described in :ref:`typesnumeric`.

.. function:: frozenset([iterable])

   :noindex:

   Return a frozenset object, optionally with elements taken from *iterable*.

   The frozenset type is described in :ref:`types-set`.

   For other containers see the built in :class:`dict`, :class:`list`, and

   :class:`tuple` classes, and the :mod:`collections` module.

   .. versionadded:: 2.4

.. function:: getattr(object, name[, default])

   Return the value of the named attributed of *object*.  *name* must be a string.

   If the string is the name of one of the object's attributes, the result is the

   value of that attribute.  For example, ``getattr(x, 'foobar')`` is equivalent to

   ``x.foobar``.  If the named attribute does not exist, *default* is returned if

   provided, otherwise :exc:`AttributeError` is raised.

.. function:: globals()

   Return a dictionary representing the current global symbol table. This is always

   the dictionary of the current module (inside a function or method, this is the

   module where it is defined, not the module from which it is called).

.. function:: hasattr(object, name)

   The arguments are an object and a string.  The result is ``True`` if the string

   is the name of one of the object's attributes, ``False`` if not. (This is

   implemented by calling ``getattr(object, name)`` and seeing whether it raises an

   exception or not.)

.. function:: hash(object)

   Return the hash value of the object (if it has one).  Hash values are integers.

   They are used to quickly compare dictionary keys during a dictionary lookup.

   Numeric values that compare equal have the same hash value (even if they are of

   different types, as is the case for 1 and 1.0).

.. function:: help([object])

   Invoke the built-in help system.  (This function is intended for interactive