blob: 5fb4f7024034b97e418c368b55587e57585a562c [file] [log] [blame]
Georg Brandl68ee3a52008-03-25 07:21:32 +00001.. XXX document all delegations to __special__ methods
Georg Brandl116aa622007-08-15 14:28:22 +00002.. _built-in-funcs:
3
4Built-in Functions
5==================
6
Georg Brandl42514812008-05-05 21:05:32 +00007The Python interpreter has a number of functions and types built into it that
8are always available. They are listed here in alphabetical order.
Georg Brandl116aa622007-08-15 14:28:22 +00009
10
Georg Brandl116aa622007-08-15 14:28:22 +000011.. function:: abs(x)
12
Georg Brandlba956ae2007-11-29 17:24:34 +000013 Return the absolute value of a number. The argument may be an
Georg Brandl116aa622007-08-15 14:28:22 +000014 integer or a floating point number. If the argument is a complex number, its
15 magnitude is returned.
16
17
18.. function:: all(iterable)
19
Georg Brandl0192bff2009-04-27 16:49:41 +000020 Return True if all elements of the *iterable* are true (or if the iterable
21 is empty). Equivalent to::
Georg Brandl116aa622007-08-15 14:28:22 +000022
23 def all(iterable):
24 for element in iterable:
25 if not element:
26 return False
27 return True
28
Georg Brandl116aa622007-08-15 14:28:22 +000029
30.. function:: any(iterable)
31
Georg Brandl0192bff2009-04-27 16:49:41 +000032 Return True if any element of the *iterable* is true. If the iterable
33 is empty, return False. Equivalent to::
Georg Brandl116aa622007-08-15 14:28:22 +000034
35 def any(iterable):
36 for element in iterable:
37 if element:
38 return True
39 return False
40
Georg Brandl116aa622007-08-15 14:28:22 +000041
Georg Brandl559e5d72008-06-11 18:37:52 +000042.. function:: ascii(object)
43
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.
48
49
Georg Brandl116aa622007-08-15 14:28:22 +000050.. function:: bin(x)
51
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.
55
Georg Brandl116aa622007-08-15 14:28:22 +000056
57.. function:: bool([x])
58
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`.
64
65 .. index:: pair: Boolean; type
66
Georg Brandl116aa622007-08-15 14:28:22 +000067
Georg Brandl036490d2009-05-17 13:00:36 +000068.. function:: bytearray([source[, encoding[, errors]]])
Georg Brandl85eb8c12007-08-31 16:33:38 +000069
Georg Brandl24eac032007-11-22 14:16:00 +000070 Return a new array of bytes. The :class:`bytearray` type is a mutable
Georg Brandl95414632007-11-22 11:00:28 +000071 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`.
Georg Brandl85eb8c12007-08-31 16:33:38 +000074
Georg Brandl036490d2009-05-17 13:00:36 +000075 The optional *source* parameter can be used to initialize the array in a few
Georg Brandl85eb8c12007-08-31 16:33:38 +000076 different ways:
77
78 * If it is a *string*, you must also give the *encoding* (and optionally,
Georg Brandlf6945182008-02-01 11:56:49 +000079 *errors*) parameters; :func:`bytearray` then converts the string to
Guido van Rossum98297ee2007-11-06 21:34:58 +000080 bytes using :meth:`str.encode`.
Georg Brandl85eb8c12007-08-31 16:33:38 +000081
82 * If it is an *integer*, the array will have that size and will be
83 initialized with null bytes.
84
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.
87
Guido van Rossum98297ee2007-11-06 21:34:58 +000088 * 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.
Georg Brandl85eb8c12007-08-31 16:33:38 +000090
91 Without an argument, an array of size 0 is created.
92
93
Georg Brandl036490d2009-05-17 13:00:36 +000094.. function:: bytes([source[, encoding[, errors]]])
Guido van Rossum98297ee2007-11-06 21:34:58 +000095
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
Georg Brandl95414632007-11-22 11:00:28 +000098 :class:`bytearray` -- it has the same non-mutating methods and the same
99 indexing and slicing behavior.
Georg Brandl48310cd2009-01-03 21:18:54 +0000100
Georg Brandl476b3552009-04-29 06:37:12 +0000101 Accordingly, constructor arguments are interpreted as for :func:`bytearray`.
Guido van Rossum98297ee2007-11-06 21:34:58 +0000102
103 Bytes objects can also be created with literals, see :ref:`strings`.
104
105
Georg Brandl116aa622007-08-15 14:28:22 +0000106.. function:: chr(i)
107
Georg Brandl85eb8c12007-08-31 16:33:38 +0000108 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].
Georg Brandl116aa622007-08-15 14:28:22 +0000112 :exc:`ValueError` will be raised if *i* is outside that range.
113
114
115.. function:: classmethod(function)
116
117 Return a class method for *function*.
118
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
121 idiom::
122
123 class C:
124 @classmethod
125 def f(cls, arg1, arg2, ...): ...
126
Christian Heimesd8654cf2007-12-02 15:22:16 +0000127 The ``@classmethod`` form is a function :term:`decorator` -- see the description
128 of function definitions in :ref:`function` for details.
Georg Brandl116aa622007-08-15 14:28:22 +0000129
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.
134
135 Class methods are different than C++ or Java static methods. If you want those,
136 see :func:`staticmethod` in this section.
137
138 For more information on class methods, consult the documentation on the standard
139 type hierarchy in :ref:`types`.
140
Georg Brandl116aa622007-08-15 14:28:22 +0000141
Georg Brandl036490d2009-05-17 13:00:36 +0000142.. function:: compile(source, filename, mode, flags=0, dont_inherit=False)
Georg Brandl116aa622007-08-15 14:28:22 +0000143
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000144 Compile the *source* into a code or AST object. Code objects can be executed
Ezio Melotti6e40e272010-01-04 09:29:10 +0000145 by :func:`exec` or :func:`eval`. *source* can either be a string or an AST
Benjamin Peterson45abfbc2009-12-13 00:32:14 +0000146 object. Refer to the :mod:`ast` module documentation for information on how
147 to work with AST objects.
Georg Brandl116aa622007-08-15 14:28:22 +0000148
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000149 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
151 commonly used).
152
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
R. David Murray66011262009-06-25 17:37:57 +0000157 evaluate to something other than ``None`` will be printed).
Georg Brandl116aa622007-08-15 14:28:22 +0000158
Georg Brandle06de8b2008-05-05 21:42:51 +0000159 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
Georg Brandl116aa622007-08-15 14:28:22 +0000164 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
Georg Brandle06de8b2008-05-05 21:42:51 +0000166 the *flags* argument is it -- the future statements in effect around the call
167 to compile are ignored.
Georg Brandl116aa622007-08-15 14:28:22 +0000168
Christian Heimesfaf2f632008-01-06 16:59:19 +0000169 Future statements are specified by bits which can be bitwise ORed together to
Georg Brandl116aa622007-08-15 14:28:22 +0000170 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.
173
Christian Heimes7f044312008-01-06 17:05:40 +0000174 This function raises :exc:`SyntaxError` if the compiled source is invalid,
175 and :exc:`TypeError` if the source contains null bytes.
176
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000177 .. note::
178
Benjamin Peterson20211002009-11-25 18:34:42 +0000179 When compiling a string with multi-line code in ``'single'`` or
Benjamin Petersonaeaa5922009-11-13 00:17:59 +0000180 ``'eval'`` mode, input must be terminated by at least one newline
181 character. This is to facilitate detection of incomplete and complete
182 statements in the :mod:`code` module.
183
184
185 .. versionchanged:: 3.2
186 Allowed use of Windows and Mac newlines. Also input in ``'exec'`` mode
187 does not have to end in a newline anymore.
Benjamin Petersonec9199b2008-11-08 17:05:00 +0000188
Georg Brandl116aa622007-08-15 14:28:22 +0000189
190.. function:: complex([real[, imag]])
191
192 Create a complex number with the value *real* + *imag*\*j or convert a string or
193 number to a complex number. If the first parameter is a string, it will be
194 interpreted as a complex number and the function must be called without a second
195 parameter. The second parameter can never be a string. Each argument may be any
196 numeric type (including complex). If *imag* is omitted, it defaults to zero and
Georg Brandl5c106642007-11-29 17:41:05 +0000197 the function serves as a numeric conversion function like :func:`int`
198 and :func:`float`. If both arguments are omitted, returns ``0j``.
Georg Brandl116aa622007-08-15 14:28:22 +0000199
200 The complex type is described in :ref:`typesnumeric`.
201
202
203.. function:: delattr(object, name)
204
205 This is a relative of :func:`setattr`. The arguments are an object and a
206 string. The string must be the name of one of the object's attributes. The
207 function deletes the named attribute, provided the object allows it. For
208 example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
209
210
211.. function:: dict([arg])
212 :noindex:
213
214 Create a new data dictionary, optionally with items taken from *arg*.
215 The dictionary type is described in :ref:`typesmapping`.
216
217 For other containers see the built in :class:`list`, :class:`set`, and
218 :class:`tuple` classes, and the :mod:`collections` module.
219
220
221.. function:: dir([object])
222
223 Without arguments, return the list of names in the current local scope. With an
224 argument, attempt to return a list of valid attributes for that object.
225
226 If the object has a method named :meth:`__dir__`, this method will be called and
227 must return the list of attributes. This allows objects that implement a custom
228 :func:`__getattr__` or :func:`__getattribute__` function to customize the way
229 :func:`dir` reports their attributes.
230
231 If the object does not provide :meth:`__dir__`, the function tries its best to
232 gather information from the object's :attr:`__dict__` attribute, if defined, and
233 from its type object. The resulting list is not necessarily complete, and may
234 be inaccurate when the object has a custom :func:`__getattr__`.
235
236 The default :func:`dir` mechanism behaves differently with different types of
237 objects, as it attempts to produce the most relevant, rather than complete,
238 information:
239
240 * If the object is a module object, the list contains the names of the module's
241 attributes.
242
243 * If the object is a type or class object, the list contains the names of its
244 attributes, and recursively of the attributes of its bases.
245
246 * Otherwise, the list contains the object's attributes' names, the names of its
247 class's attributes, and recursively of the attributes of its class's base
248 classes.
249
Christian Heimesfe337bf2008-03-23 21:54:12 +0000250 The resulting list is sorted alphabetically. For example:
251
252 >>> import struct
253 >>> dir() # doctest: +SKIP
254 ['__builtins__', '__doc__', '__name__', 'struct']
255 >>> dir(struct) # doctest: +NORMALIZE_WHITESPACE
256 ['Struct', '__builtins__', '__doc__', '__file__', '__name__',
257 '__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
258 'unpack', 'unpack_from']
259 >>> class Foo(object):
260 ... def __dir__(self):
261 ... return ["kan", "ga", "roo"]
262 ...
263 >>> f = Foo()
264 >>> dir(f)
265 ['ga', 'kan', 'roo']
Georg Brandl116aa622007-08-15 14:28:22 +0000266
267 .. note::
268
269 Because :func:`dir` is supplied primarily as a convenience for use at an
Georg Brandl036490d2009-05-17 13:00:36 +0000270 interactive prompt, it tries to supply an interesting set of names more
271 than it tries to supply a rigorously or consistently defined set of names,
272 and its detailed behavior may change across releases. For example,
273 metaclass attributes are not in the result list when the argument is a
274 class.
Georg Brandl116aa622007-08-15 14:28:22 +0000275
276
277.. function:: divmod(a, b)
278
279 Take two (non complex) numbers as arguments and return a pair of numbers
Georg Brandl036490d2009-05-17 13:00:36 +0000280 consisting of their quotient and remainder when using integer division. With
281 mixed operand types, the rules for binary arithmetic operators apply. For
282 integers, the result is the same as ``(a // b, a % b)``. For floating point
283 numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a /
284 b)`` but may be 1 less than that. In any case ``q * b + a % b`` is very
285 close to *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0
286 <= abs(a % b) < abs(b)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000287
Georg Brandl116aa622007-08-15 14:28:22 +0000288
Georg Brandl036490d2009-05-17 13:00:36 +0000289.. function:: enumerate(iterable, start=0)
Georg Brandl116aa622007-08-15 14:28:22 +0000290
Georg Brandld11ae5d2008-05-16 13:27:32 +0000291 Return an enumerate object. *iterable* must be a sequence, an
Alexandre Vassalottieca20b62008-05-16 02:54:33 +0000292 :term:`iterator`, or some other object which supports iteration. The
293 :meth:`__next__` method of the iterator returned by :func:`enumerate` returns a
Alexandre Vassalottie9f305f2008-05-16 04:39:54 +0000294 tuple containing a count (from *start* which defaults to 0) and the
295 corresponding value obtained from iterating over *iterable*.
296 :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``,
297 ``(1, seq[1])``, ``(2, seq[2])``, .... For example:
Georg Brandl116aa622007-08-15 14:28:22 +0000298
Benjamin Petersonc9928cc2008-12-20 03:20:23 +0000299 >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter']):
Christian Heimesfe337bf2008-03-23 21:54:12 +0000300 ... print(i, season)
Georg Brandl116aa622007-08-15 14:28:22 +0000301 0 Spring
302 1 Summer
303 2 Fall
304 3 Winter
305
Georg Brandl116aa622007-08-15 14:28:22 +0000306
Georg Brandl036490d2009-05-17 13:00:36 +0000307.. function:: eval(expression, globals=None, locals=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000308
309 The arguments are a string and optional globals and locals. If provided,
310 *globals* must be a dictionary. If provided, *locals* can be any mapping
311 object.
312
Georg Brandl116aa622007-08-15 14:28:22 +0000313 The *expression* argument is parsed and evaluated as a Python expression
314 (technically speaking, a condition list) using the *globals* and *locals*
Georg Brandl9afde1c2007-11-01 20:32:30 +0000315 dictionaries as global and local namespace. If the *globals* dictionary is
Georg Brandl116aa622007-08-15 14:28:22 +0000316 present and lacks '__builtins__', the current globals are copied into *globals*
317 before *expression* is parsed. This means that *expression* normally has full
Georg Brandl1a3284e2007-12-02 09:40:06 +0000318 access to the standard :mod:`builtins` module and restricted environments are
Georg Brandl116aa622007-08-15 14:28:22 +0000319 propagated. If the *locals* dictionary is omitted it defaults to the *globals*
320 dictionary. If both dictionaries are omitted, the expression is executed in the
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000321 environment where :func:`eval` is called. The return value is the result of
Christian Heimesfe337bf2008-03-23 21:54:12 +0000322 the evaluated expression. Syntax errors are reported as exceptions. Example:
Georg Brandl116aa622007-08-15 14:28:22 +0000323
324 >>> x = 1
Georg Brandl6911e3c2007-09-04 07:15:32 +0000325 >>> eval('x+1')
Georg Brandl116aa622007-08-15 14:28:22 +0000326 2
327
Benjamin Peterson3e4f0552008-09-02 00:31:15 +0000328 This function can also be used to execute arbitrary code objects (such as
329 those created by :func:`compile`). In this case pass a code object instead
330 of a string. If the code object has been compiled with ``'exec'`` as the
Georg Brandl1f70cdf2010-03-21 09:04:24 +0000331 *mode* argument, :func:`eval`\'s return value will be ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000332
333 Hints: dynamic execution of statements is supported by the :func:`exec`
334 function. The :func:`globals` and :func:`locals` functions
335 returns the current global and local dictionary, respectively, which may be
336 useful to pass around for use by :func:`eval` or :func:`exec`.
337
Georg Brandl05bfcc52010-07-11 09:42:10 +0000338 See :func:`ast.literal_eval` for a function that can safely evaluate strings
339 with expressions containing only literals.
340
Georg Brandl116aa622007-08-15 14:28:22 +0000341
342.. function:: exec(object[, globals[, locals]])
343
Benjamin Petersond3013ff2008-11-11 21:43:42 +0000344 This function supports dynamic execution of Python code. *object* must be
345 either a string or a code object. If it is a string, the string is parsed as
346 a suite of Python statements which is then executed (unless a syntax error
Georg Brandl47f27a32009-03-31 16:57:13 +0000347 occurs). [#]_ If it is a code object, it is simply executed. In all cases,
348 the code that's executed is expected to be valid as file input (see the
349 section "File input" in the Reference Manual). Be aware that the
350 :keyword:`return` and :keyword:`yield` statements may not be used outside of
351 function definitions even within the context of code passed to the
352 :func:`exec` function. The return value is ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000353
354 In all cases, if the optional parts are omitted, the code is executed in the
355 current scope. If only *globals* is provided, it must be a dictionary, which
356 will be used for both the global and the local variables. If *globals* and
357 *locals* are given, they are used for the global and local variables,
358 respectively. If provided, *locals* can be any mapping object.
359
360 If the *globals* dictionary does not contain a value for the key
361 ``__builtins__``, a reference to the dictionary of the built-in module
Georg Brandl1a3284e2007-12-02 09:40:06 +0000362 :mod:`builtins` is inserted under that key. That way you can control what
Georg Brandl116aa622007-08-15 14:28:22 +0000363 builtins are available to the executed code by inserting your own
364 ``__builtins__`` dictionary into *globals* before passing it to :func:`exec`.
365
366 .. note::
367
368 The built-in functions :func:`globals` and :func:`locals` return the current
369 global and local dictionary, respectively, which may be useful to pass around
370 for use as the second and third argument to :func:`exec`.
371
Georg Brandle720c0a2009-04-27 16:20:50 +0000372 .. note::
Georg Brandl116aa622007-08-15 14:28:22 +0000373
374 The default *locals* act as described for function :func:`locals` below:
Georg Brandlf6945182008-02-01 11:56:49 +0000375 modifications to the default *locals* dictionary should not be attempted.
376 Pass an explicit *locals* dictionary if you need to see effects of the
377 code on *locals* after function :func:`exec` returns.
Georg Brandl116aa622007-08-15 14:28:22 +0000378
379
380.. function:: filter(function, iterable)
381
Georg Brandl952aea22007-09-04 17:50:40 +0000382 Construct an iterator from those elements of *iterable* for which *function*
383 returns true. *iterable* may be either a sequence, a container which
Georg Brandl9afde1c2007-11-01 20:32:30 +0000384 supports iteration, or an iterator. If *function* is ``None``, the identity
385 function is assumed, that is, all elements of *iterable* that are false are
386 removed.
Georg Brandl116aa622007-08-15 14:28:22 +0000387
Georg Brandl952aea22007-09-04 17:50:40 +0000388 Note that ``filter(function, iterable)`` is equivalent to the generator
389 expression ``(item for item in iterable if function(item))`` if function is
390 not ``None`` and ``(item for item in iterable if item)`` if function is
391 ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000392
Raymond Hettingercdf8ba32009-02-19 04:45:07 +0000393 See :func:`itertools.filterfalse` for the complementary function that returns
394 elements of *iterable* for which *function* returns false.
395
Georg Brandl116aa622007-08-15 14:28:22 +0000396
397.. function:: float([x])
398
Georg Brandl95817b32008-05-11 14:30:18 +0000399 Convert a string or a number to floating point. If the argument is a string,
400 it must contain a possibly signed decimal or floating point number, possibly
401 embedded in whitespace. The argument may also be ``'[+|-]nan'`` or
402 ``'[+|-]inf'``. Otherwise, the argument may be an integer or a floating
403 point number, and a floating point number with the same value (within
404 Python's floating point precision) is returned. If no argument is given,
405 ``0.0`` is returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000406
407 .. note::
408
409 .. index::
410 single: NaN
411 single: Infinity
412
Georg Brandl95817b32008-05-11 14:30:18 +0000413 When passing in a string, values for NaN and Infinity may be returned,
414 depending on the underlying C library. Float accepts the strings
415 ``'nan'``, ``'inf'`` and ``'-inf'`` for NaN and positive or negative
416 infinity. The case and a leading + are ignored as well as a leading - is
417 ignored for NaN. Float always represents NaN and infinity as ``nan``,
418 ``inf`` or ``-inf``.
Georg Brandl116aa622007-08-15 14:28:22 +0000419
420 The float type is described in :ref:`typesnumeric`.
421
Georg Brandl4b491312007-08-31 09:22:56 +0000422.. function:: format(value[, format_spec])
423
424 .. index::
425 pair: str; format
426 single: __format__
Georg Brandl48310cd2009-01-03 21:18:54 +0000427
Georg Brandl5579ba92009-02-23 10:24:05 +0000428 Convert a *value* to a "formatted" representation, as controlled by
429 *format_spec*. The interpretation of *format_spec* will depend on the type
430 of the *value* argument, however there is a standard formatting syntax that
431 is used by most built-in types: :ref:`formatspec`.
Georg Brandl48310cd2009-01-03 21:18:54 +0000432
Georg Brandl4b491312007-08-31 09:22:56 +0000433 .. note::
434
Georg Brandl5579ba92009-02-23 10:24:05 +0000435 ``format(value, format_spec)`` merely calls
436 ``value.__format__(format_spec)``.
Georg Brandl4b491312007-08-31 09:22:56 +0000437
438
Georg Brandl116aa622007-08-15 14:28:22 +0000439.. function:: frozenset([iterable])
440 :noindex:
441
442 Return a frozenset object, optionally with elements taken from *iterable*.
443 The frozenset type is described in :ref:`types-set`.
444
445 For other containers see the built in :class:`dict`, :class:`list`, and
446 :class:`tuple` classes, and the :mod:`collections` module.
447
Georg Brandl116aa622007-08-15 14:28:22 +0000448
449.. function:: getattr(object, name[, default])
450
451 Return the value of the named attributed of *object*. *name* must be a string.
452 If the string is the name of one of the object's attributes, the result is the
453 value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
454 ``x.foobar``. If the named attribute does not exist, *default* is returned if
455 provided, otherwise :exc:`AttributeError` is raised.
456
457
458.. function:: globals()
459
460 Return a dictionary representing the current global symbol table. This is always
461 the dictionary of the current module (inside a function or method, this is the
462 module where it is defined, not the module from which it is called).
463
464
465.. function:: hasattr(object, name)
466
467 The arguments are an object and a string. The result is ``True`` if the string
468 is the name of one of the object's attributes, ``False`` if not. (This is
469 implemented by calling ``getattr(object, name)`` and seeing whether it raises an
470 exception or not.)
471
472
473.. function:: hash(object)
474
475 Return the hash value of the object (if it has one). Hash values are integers.
476 They are used to quickly compare dictionary keys during a dictionary lookup.
477 Numeric values that compare equal have the same hash value (even if they are of
478 different types, as is the case for 1 and 1.0).
479
480
481.. function:: help([object])
482
483 Invoke the built-in help system. (This function is intended for interactive
484 use.) If no argument is given, the interactive help system starts on the
485 interpreter console. If the argument is a string, then the string is looked up
486 as the name of a module, function, class, method, keyword, or documentation
487 topic, and a help page is printed on the console. If the argument is any other
488 kind of object, a help page on the object is generated.
489
Christian Heimes9bd667a2008-01-20 15:14:11 +0000490 This function is added to the built-in namespace by the :mod:`site` module.
491
Georg Brandl116aa622007-08-15 14:28:22 +0000492
493.. function:: hex(x)
494
495 Convert an integer number to a hexadecimal string. The result is a valid Python
496 expression. If *x* is not a Python :class:`int` object, it has to define an
497 :meth:`__index__` method that returns an integer.
498
Mark Dickinson36cea392009-10-03 10:18:40 +0000499 .. note::
500
501 To obtain a hexadecimal string representation for a float, use the
502 :meth:`float.hex` method.
503
Georg Brandl116aa622007-08-15 14:28:22 +0000504
505.. function:: id(object)
506
Georg Brandlba956ae2007-11-29 17:24:34 +0000507 Return the "identity" of an object. This is an integer which
Georg Brandl116aa622007-08-15 14:28:22 +0000508 is guaranteed to be unique and constant for this object during its lifetime.
Georg Brandl495f7b52009-10-27 15:28:25 +0000509 Two objects with non-overlapping lifetimes may have the same :func:`id`
510 value.
511
512 .. impl-detail:: This is the address of the object.
Georg Brandl116aa622007-08-15 14:28:22 +0000513
514
Georg Brandlc0902982007-09-12 21:29:27 +0000515.. function:: input([prompt])
516
517 If the *prompt* argument is present, it is written to standard output without
518 a trailing newline. The function then reads a line from input, converts it
519 to a string (stripping a trailing newline), and returns that. When EOF is
520 read, :exc:`EOFError` is raised. Example::
521
Georg Brandl7b469422007-09-12 21:32:27 +0000522 >>> s = input('--> ')
Georg Brandlc0902982007-09-12 21:29:27 +0000523 --> Monty Python's Flying Circus
524 >>> s
525 "Monty Python's Flying Circus"
526
Georg Brandl7b469422007-09-12 21:32:27 +0000527 If the :mod:`readline` module was loaded, then :func:`input` will use it
Georg Brandlc0902982007-09-12 21:29:27 +0000528 to provide elaborate line editing and history features.
529
530
Georg Brandl1b5ab452009-08-13 07:56:35 +0000531.. function:: int([number | string[, base]])
Georg Brandl116aa622007-08-15 14:28:22 +0000532
Georg Brandl225d3c82008-04-09 18:45:14 +0000533 Convert a number or string to an integer. If no arguments are given, return
534 ``0``. If a number is given, return ``number.__int__()``. Conversion of
535 floating point numbers to integers truncates towards zero. A string must be
536 a base-radix integer literal optionally preceded by '+' or '-' (with no space
537 in between) and optionally surrounded by whitespace. A base-n literal
538 consists of the digits 0 to n-1, with 'a' to 'z' (or 'A' to 'Z') having
Georg Brandl1b5ab452009-08-13 07:56:35 +0000539 values 10 to 35. The default *base* is 10. The allowed values are 0 and 2-36.
Georg Brandl225d3c82008-04-09 18:45:14 +0000540 Base-2, -8, and -16 literals can be optionally prefixed with ``0b``/``0B``,
Georg Brandl1b5ab452009-08-13 07:56:35 +0000541 ``0o``/``0O``, or ``0x``/``0X``, as with integer literals in code. Base 0
542 means to interpret exactly as a code literal, so that the actual base is 2,
Georg Brandl225d3c82008-04-09 18:45:14 +0000543 8, 10, or 16, and so that ``int('010', 0)`` is not legal, while
544 ``int('010')`` is, as well as ``int('010', 8)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000545
546 The integer type is described in :ref:`typesnumeric`.
547
548
549.. function:: isinstance(object, classinfo)
550
Georg Brandl85eb8c12007-08-31 16:33:38 +0000551 Return true if the *object* argument is an instance of the *classinfo*
552 argument, or of a (direct or indirect) subclass thereof. If *object* is not
553 an object of the given type, the function always returns false. If
554 *classinfo* is not a class (type object), it may be a tuple of type objects,
555 or may recursively contain other such tuples (other sequence types are not
556 accepted). If *classinfo* is not a type or tuple of types and such tuples,
557 a :exc:`TypeError` exception is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000558
Georg Brandl116aa622007-08-15 14:28:22 +0000559
560.. function:: issubclass(class, classinfo)
561
562 Return true if *class* is a subclass (direct or indirect) of *classinfo*. A
563 class is considered a subclass of itself. *classinfo* may be a tuple of class
564 objects, in which case every entry in *classinfo* will be checked. In any other
565 case, a :exc:`TypeError` exception is raised.
566
Georg Brandl116aa622007-08-15 14:28:22 +0000567
Georg Brandl036490d2009-05-17 13:00:36 +0000568.. function:: iter(object[, sentinel])
Georg Brandl116aa622007-08-15 14:28:22 +0000569
Georg Brandl036490d2009-05-17 13:00:36 +0000570 Return an :term:`iterator` object. The first argument is interpreted very
571 differently depending on the presence of the second argument. Without a
572 second argument, *object* must be a collection object which supports the
573 iteration protocol (the :meth:`__iter__` method), or it must support the
574 sequence protocol (the :meth:`__getitem__` method with integer arguments
575 starting at ``0``). If it does not support either of those protocols,
576 :exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
577 then *object* must be a callable object. The iterator created in this case
578 will call *object* with no arguments for each call to its :meth:`__next__`
579 method; if the value returned is equal to *sentinel*, :exc:`StopIteration`
580 will be raised, otherwise the value will be returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000581
Benjamin Petersonf07d0022009-03-21 17:31:58 +0000582 One useful application of the second form of :func:`iter` is to read lines of
583 a file until a certain line is reached. The following example reads a file
584 until ``"STOP"`` is reached: ::
585
586 with open("mydata.txt") as fp:
587 for line in iter(fp.readline, "STOP"):
588 process_line(line)
589
Georg Brandl116aa622007-08-15 14:28:22 +0000590
591.. function:: len(s)
592
593 Return the length (the number of items) of an object. The argument may be a
594 sequence (string, tuple or list) or a mapping (dictionary).
595
596
597.. function:: list([iterable])
598
599 Return a list whose items are the same and in the same order as *iterable*'s
600 items. *iterable* may be either a sequence, a container that supports
601 iteration, or an iterator object. If *iterable* is already a list, a copy is
602 made and returned, similar to ``iterable[:]``. For instance, ``list('abc')``
Georg Brandl036490d2009-05-17 13:00:36 +0000603 returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``.
604 If no argument is given, returns a new empty list, ``[]``.
Georg Brandl116aa622007-08-15 14:28:22 +0000605
Georg Brandl48310cd2009-01-03 21:18:54 +0000606 :class:`list` is a mutable sequence type, as documented in :ref:`typesseq`.
Georg Brandl116aa622007-08-15 14:28:22 +0000607
Georg Brandl036490d2009-05-17 13:00:36 +0000608
Georg Brandl116aa622007-08-15 14:28:22 +0000609.. function:: locals()
610
611 Update and return a dictionary representing the current local symbol table.
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000612 Free variables are returned by :func:`locals` when it is called in function
613 blocks, but not in class blocks.
Georg Brandl116aa622007-08-15 14:28:22 +0000614
Georg Brandle720c0a2009-04-27 16:20:50 +0000615 .. note::
Georg Brandl036490d2009-05-17 13:00:36 +0000616 The contents of this dictionary should not be modified; changes may not
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000617 affect the values of local and free variables used by the interpreter.
Georg Brandl116aa622007-08-15 14:28:22 +0000618
619.. function:: map(function, iterable, ...)
620
Georg Brandl952aea22007-09-04 17:50:40 +0000621 Return an iterator that applies *function* to every item of *iterable*,
622 yielding the results. If additional *iterable* arguments are passed,
623 *function* must take that many arguments and is applied to the items from all
Georg Brandlde2b00e2008-05-05 21:04:12 +0000624 iterables in parallel. With multiple iterables, the iterator stops when the
Raymond Hettingercdf8ba32009-02-19 04:45:07 +0000625 shortest iterable is exhausted. For cases where the function inputs are
626 already arranged into argument tuples, see :func:`itertools.starmap`\.
Georg Brandlde2b00e2008-05-05 21:04:12 +0000627
Georg Brandl116aa622007-08-15 14:28:22 +0000628
Georg Brandl55ac8f02007-09-01 13:51:09 +0000629.. function:: max(iterable[, args...], *[, key])
Georg Brandl116aa622007-08-15 14:28:22 +0000630
631 With a single argument *iterable*, return the largest item of a non-empty
632 iterable (such as a string, tuple or list). With more than one argument, return
633 the largest of the arguments.
634
Georg Brandl55ac8f02007-09-01 13:51:09 +0000635 The optional keyword-only *key* argument specifies a one-argument ordering
636 function like that used for :meth:`list.sort`.
Georg Brandl116aa622007-08-15 14:28:22 +0000637
638
Georg Brandl85eb8c12007-08-31 16:33:38 +0000639.. function:: memoryview(obj)
Benjamin Peterson6dfcb022008-09-10 21:02:02 +0000640 :noindex:
Georg Brandl85eb8c12007-08-31 16:33:38 +0000641
Benjamin Peterson1b25b922008-09-09 22:15:27 +0000642 Return a "memory view" object created from the given argument. See
643 :ref:`typememoryview` for more information.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000644
645
Georg Brandl55ac8f02007-09-01 13:51:09 +0000646.. function:: min(iterable[, args...], *[, key])
Georg Brandl116aa622007-08-15 14:28:22 +0000647
648 With a single argument *iterable*, return the smallest item of a non-empty
649 iterable (such as a string, tuple or list). With more than one argument, return
650 the smallest of the arguments.
651
Georg Brandl55ac8f02007-09-01 13:51:09 +0000652 The optional keyword-only *key* argument specifies a one-argument ordering
653 function like that used for :meth:`list.sort`.
Georg Brandl116aa622007-08-15 14:28:22 +0000654
655
656.. function:: next(iterator[, default])
657
Georg Brandlc14bb752008-04-29 21:00:18 +0000658 Retrieve the next item from the *iterator* by calling its :meth:`__next__`
Georg Brandl116aa622007-08-15 14:28:22 +0000659 method. If *default* is given, it is returned if the iterator is exhausted,
660 otherwise :exc:`StopIteration` is raised.
661
662
663.. function:: object()
664
Georg Brandl85eb8c12007-08-31 16:33:38 +0000665 Return a new featureless object. :class:`object` is a base for all classes.
Georg Brandl55ac8f02007-09-01 13:51:09 +0000666 It has the methods that are common to all instances of Python classes. This
667 function does not accept any arguments.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000668
669 .. note::
670
671 :class:`object` does *not* have a :attr:`__dict__`, so you can't assign
672 arbitrary attributes to an instance of the :class:`object` class.
Georg Brandl116aa622007-08-15 14:28:22 +0000673
Georg Brandl116aa622007-08-15 14:28:22 +0000674
675.. function:: oct(x)
676
677 Convert an integer number to an octal string. The result is a valid Python
678 expression. If *x* is not a Python :class:`int` object, it has to define an
679 :meth:`__index__` method that returns an integer.
680
Georg Brandl116aa622007-08-15 14:28:22 +0000681
Georg Brandle40ee502010-07-11 09:33:39 +0000682.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True)
Georg Brandl116aa622007-08-15 14:28:22 +0000683
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000684 Open *file* and return a corresponding stream. If the file cannot be opened,
685 an :exc:`IOError` is raised.
Georg Brandl48310cd2009-01-03 21:18:54 +0000686
Georg Brandl76e55382008-10-08 16:34:57 +0000687 *file* is either a string or bytes object giving the name (and the path if
688 the file isn't in the current working directory) of the file to be opened or
689 an integer file descriptor of the file to be wrapped. (If a file descriptor
690 is given, it is closed when the returned I/O object is closed, unless
691 *closefd* is set to ``False``.)
Georg Brandl116aa622007-08-15 14:28:22 +0000692
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000693 *mode* is an optional string that specifies the mode in which the file is
Georg Brandl7b6ca4a2009-04-27 06:13:55 +0000694 opened. The available modes are:
Georg Brandl116aa622007-08-15 14:28:22 +0000695
Benjamin Petersondd219122008-04-11 21:17:32 +0000696 ========= ===============================================================
697 Character Meaning
698 --------- ---------------------------------------------------------------
699 ``'r'`` open for reading (default)
Georg Brandl7b6ca4a2009-04-27 06:13:55 +0000700 ``'w'`` open for writing, truncating the file first if it exists
Benjamin Petersondd219122008-04-11 21:17:32 +0000701 ``'a'`` open for writing, appending to the end of the file if it exists
Georg Brandl7b6ca4a2009-04-27 06:13:55 +0000702 ========= ===============================================================
703
704 Several characters can be appended that modify the given mode:
705
706 ========= ===============================================================
Benjamin Petersondd219122008-04-11 21:17:32 +0000707 ``'t'`` text mode (default)
Georg Brandl7b6ca4a2009-04-27 06:13:55 +0000708 ``'b'`` binary mode
709 ``'+'`` open for updating (reading and writing)
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000710 ``'U'`` universal newline mode (for backwards compatibility; should
711 not be used in new code)
Benjamin Petersondd219122008-04-11 21:17:32 +0000712 ========= ===============================================================
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000713
Georg Brandl7b6ca4a2009-04-27 06:13:55 +0000714 The mode ``'w+'`` opens and truncates the file to 0 bytes, while ``'r+'``
715 opens the file without truncation. On *some* Unix systems, append mode means
716 that *all* writes append to the end of the file regardless of the current
717 seek position.
Skip Montanaro1c639602007-09-23 19:49:54 +0000718
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000719 Python distinguishes between files opened in binary and text modes, even when
720 the underlying operating system doesn't. Files opened in binary mode
721 (including ``'b'`` in the *mode* argument) return contents as ``bytes``
722 objects without any decoding. In text mode (the default, or when ``'t'`` is
723 included in the *mode* argument), the contents of the file are returned as
Georg Brandl7b6ca4a2009-04-27 06:13:55 +0000724 strings, the bytes having been first decoded using the specified *encoding*.
725 If *encoding* is not specified, a platform-dependent default encoding is
726 used, see below.
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000727
Benjamin Petersondd219122008-04-11 21:17:32 +0000728 *buffering* is an optional integer used to set the buffering policy. By
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000729 default full buffering is on. Pass 0 to switch buffering off (only allowed
Benjamin Peterson810a80a2009-10-20 21:56:16 +0000730 in binary mode), 1 to set line buffering, and an integer > 1 to indicate the
731 size of the buffer.
Georg Brandl48310cd2009-01-03 21:18:54 +0000732
Benjamin Petersondd219122008-04-11 21:17:32 +0000733 *encoding* is the name of the encoding used to decode or encode the file.
734 This should only be used in text mode. The default encoding is platform
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000735 dependent (whatever :func:`locale.getpreferredencoding` returns), but any
736 encoding supported by Python can be used. See the :mod:`codecs` module for
737 the list of supported encodings.
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000738
Benjamin Peterson52c3bf12009-03-23 02:44:58 +0000739 *errors* is an optional string that specifies how encoding and decoding
740 errors are to be handled--this cannot be used in binary mode. Pass
741 ``'strict'`` to raise a :exc:`ValueError` exception if there is an encoding
742 error (the default of ``None`` has the same effect), or pass ``'ignore'`` to
743 ignore errors. (Note that ignoring encoding errors can lead to data loss.)
744 ``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted
745 where there is malformed data. When writing, ``'xmlcharrefreplace'``
746 (replace with the appropriate XML character reference) or
747 ``'backslashreplace'`` (replace with backslashed escape sequences) can be
748 used. Any other error handling name that has been registered with
749 :func:`codecs.register_error` is also valid.
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000750
Benjamin Petersondd219122008-04-11 21:17:32 +0000751 *newline* controls how universal newlines works (it only applies to text
752 mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It
753 works as follows:
Mark Summerfieldecff60e2007-12-14 10:07:44 +0000754
Benjamin Petersondd219122008-04-11 21:17:32 +0000755 * On input, if *newline* is ``None``, universal newlines mode is enabled.
756 Lines in the input can end in ``'\n'``, ``'\r'``, or ``'\r\n'``, and these
757 are translated into ``'\n'`` before being returned to the caller. If it is
758 ``''``, universal newline mode is enabled, but line endings are returned to
759 the caller untranslated. If it has any of the other legal values, input
760 lines are only terminated by the given string, and the line ending is
761 returned to the caller untranslated.
762
763 * On output, if *newline* is ``None``, any ``'\n'`` characters written are
764 translated to the system default line separator, :data:`os.linesep`. If
765 *newline* is ``''``, no translation takes place. If *newline* is any of
766 the other legal values, any ``'\n'`` characters written are translated to
767 the given string.
768
Benjamin Peterson8cad9c72009-03-23 02:38:01 +0000769 If *closefd* is ``False`` and a file descriptor rather than a filename was
770 given, the underlying file descriptor will be kept open when the file is
771 closed. If a filename is given *closefd* has no effect and must be ``True``
772 (the default).
773
774 The type of file object returned by the :func:`open` function depends on the
775 mode. When :func:`open` is used to open a file in a text mode (``'w'``,
776 ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
777 :class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used
778 to open a file in a binary mode with buffering, the returned class is a
779 subclass of :class:`io.BufferedIOBase`. The exact class varies: in read
780 binary mode, it returns a :class:`io.BufferedReader`; in write binary and
781 append binary modes, it returns a :class:`io.BufferedWriter`, and in
782 read/write mode, it returns a :class:`io.BufferedRandom`. When buffering is
783 disabled, the raw stream, a subclass of :class:`io.RawIOBase`,
784 :class:`io.FileIO`, is returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000785
786 .. index::
787 single: line-buffered I/O
788 single: unbuffered I/O
789 single: buffer size, I/O
790 single: I/O control; buffering
Skip Montanaro4d8c1932007-09-23 21:13:45 +0000791 single: binary mode
792 single: text mode
793 module: sys
Georg Brandl116aa622007-08-15 14:28:22 +0000794
Benjamin Petersondd219122008-04-11 21:17:32 +0000795 See also the file handling modules, such as, :mod:`fileinput`, :mod:`io`
Benjamin Peterson8cad9c72009-03-23 02:38:01 +0000796 (where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:`tempfile`,
797 and :mod:`shutil`.
Georg Brandl116aa622007-08-15 14:28:22 +0000798
Georg Brandlf6945182008-02-01 11:56:49 +0000799
800.. XXX works for bytes too, but should it?
Georg Brandl116aa622007-08-15 14:28:22 +0000801.. function:: ord(c)
802
803 Given a string of length one, return an integer representing the Unicode code
Georg Brandlf6945182008-02-01 11:56:49 +0000804 point of the character. For example, ``ord('a')`` returns the integer ``97``
805 and ``ord('\u2020')`` returns ``8224``. This is the inverse of :func:`chr`.
806
807 If the argument length is not one, a :exc:`TypeError` will be raised. (If
808 Python was built with UCS2 Unicode, then the character's code point must be
809 in the range [0..65535] inclusive; otherwise the string length is two!)
Georg Brandl116aa622007-08-15 14:28:22 +0000810
811
812.. function:: pow(x, y[, z])
813
814 Return *x* to the power *y*; if *z* is present, return *x* to the power *y*,
815 modulo *z* (computed more efficiently than ``pow(x, y) % z``). The two-argument
816 form ``pow(x, y)`` is equivalent to using the power operator: ``x**y``.
817
Georg Brandle06de8b2008-05-05 21:42:51 +0000818 The arguments must have numeric types. With mixed operand types, the
819 coercion rules for binary arithmetic operators apply. For :class:`int`
820 operands, the result has the same type as the operands (after coercion)
821 unless the second argument is negative; in that case, all arguments are
822 converted to float and a float result is delivered. For example, ``10**2``
823 returns ``100``, but ``10**-2`` returns ``0.01``. If the second argument is
824 negative, the third argument must be omitted. If *z* is present, *x* and *y*
825 must be of integer types, and *y* must be non-negative.
Georg Brandl116aa622007-08-15 14:28:22 +0000826
827
Georg Brandl036490d2009-05-17 13:00:36 +0000828.. function:: print([object, ...], *, sep=' ', end='\\n', file=sys.stdout)
Georg Brandlf6945182008-02-01 11:56:49 +0000829
830 Print *object*\(s) to the stream *file*, separated by *sep* and followed by
831 *end*. *sep*, *end* and *file*, if present, must be given as keyword
832 arguments.
833
834 All non-keyword arguments are converted to strings like :func:`str` does and
835 written to the stream, separated by *sep* and followed by *end*. Both *sep*
836 and *end* must be strings; they can also be ``None``, which means to use the
837 default values. If no *object* is given, :func:`print` will just write
838 *end*.
839
840 The *file* argument must be an object with a ``write(string)`` method; if it
841 is not present or ``None``, :data:`sys.stdout` will be used.
842
843
Georg Brandl036490d2009-05-17 13:00:36 +0000844.. function:: property(fget=None, fset=None, fdel=None, doc=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000845
Georg Brandl85eb8c12007-08-31 16:33:38 +0000846 Return a property attribute.
Georg Brandl116aa622007-08-15 14:28:22 +0000847
848 *fget* is a function for getting an attribute value, likewise *fset* is a
849 function for setting, and *fdel* a function for del'ing, an attribute. Typical
Georg Brandl7528b9b2010-08-02 19:23:34 +0000850 use is to define a managed attribute ``x``::
Georg Brandl116aa622007-08-15 14:28:22 +0000851
852 class C(object):
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +0000853 def __init__(self):
854 self._x = None
855
856 def getx(self):
857 return self._x
858 def setx(self, value):
859 self._x = value
860 def delx(self):
861 del self._x
Georg Brandl116aa622007-08-15 14:28:22 +0000862 x = property(getx, setx, delx, "I'm the 'x' property.")
863
Georg Brandl7528b9b2010-08-02 19:23:34 +0000864 If then *c* is an instance of *C*, ``c.x`` will invoke the getter,
865 ``c.x = value`` will invoke the setter and ``del c.x`` the deleter.
866
Georg Brandl116aa622007-08-15 14:28:22 +0000867 If given, *doc* will be the docstring of the property attribute. Otherwise, the
868 property will copy *fget*'s docstring (if it exists). This makes it possible to
Christian Heimesd8654cf2007-12-02 15:22:16 +0000869 create read-only properties easily using :func:`property` as a :term:`decorator`::
Georg Brandl116aa622007-08-15 14:28:22 +0000870
871 class Parrot(object):
872 def __init__(self):
873 self._voltage = 100000
874
875 @property
876 def voltage(self):
877 """Get the current voltage."""
878 return self._voltage
879
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +0000880 turns the :meth:`voltage` method into a "getter" for a read-only attribute
881 with the same name.
882
883 A property object has :attr:`getter`, :attr:`setter`, and :attr:`deleter`
884 methods usable as decorators that create a copy of the property with the
885 corresponding accessor function set to the decorated function. This is
886 best explained with an example::
887
888 class C(object):
Benjamin Peterson206e3072008-10-19 14:07:49 +0000889 def __init__(self):
890 self._x = None
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +0000891
892 @property
893 def x(self):
894 """I'm the 'x' property."""
895 return self._x
896
897 @x.setter
898 def x(self, value):
899 self._x = value
900
901 @x.deleter
902 def x(self):
903 del self._x
904
905 This code is exactly equivalent to the first example. Be sure to give the
906 additional functions the same name as the original property (``x`` in this
907 case.)
908
909 The returned property also has the attributes ``fget``, ``fset``, and
910 ``fdel`` corresponding to the constructor arguments.
Georg Brandl116aa622007-08-15 14:28:22 +0000911
Georg Brandl116aa622007-08-15 14:28:22 +0000912
Georg Brandl952aea22007-09-04 17:50:40 +0000913.. XXX does accept objects with __index__ too
Georg Brandl116aa622007-08-15 14:28:22 +0000914.. function:: range([start,] stop[, step])
915
Georg Brandlbf086a12008-05-12 16:53:56 +0000916 This is a versatile function to create iterables yielding arithmetic
Georg Brandl95817b32008-05-11 14:30:18 +0000917 progressions. It is most often used in :keyword:`for` loops. The arguments
918 must be integers. If the *step* argument is omitted, it defaults to ``1``.
919 If the *start* argument is omitted, it defaults to ``0``. The full form
Georg Brandlbf086a12008-05-12 16:53:56 +0000920 returns an iterable of integers ``[start, start + step, start + 2 * step,
Georg Brandl95817b32008-05-11 14:30:18 +0000921 ...]``. If *step* is positive, the last element is the largest ``start + i *
922 step`` less than *stop*; if *step* is negative, the last element is the
923 smallest ``start + i * step`` greater than *stop*. *step* must not be zero
924 (or else :exc:`ValueError` is raised). Example:
Georg Brandl116aa622007-08-15 14:28:22 +0000925
926 >>> list(range(10))
927 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
928 >>> list(range(1, 11))
929 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
930 >>> list(range(0, 30, 5))
931 [0, 5, 10, 15, 20, 25]
932 >>> list(range(0, 10, 3))
933 [0, 3, 6, 9]
934 >>> list(range(0, -10, -1))
935 [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
936 >>> list(range(0))
937 []
938 >>> list(range(1, 0))
939 []
940
Mark Dickinson3e124ae2009-09-22 21:47:24 +0000941 .. versionchanged:: 3.2
942 Testing integers for membership takes constant time instead of
943 iterating through all items.
944
Georg Brandl116aa622007-08-15 14:28:22 +0000945
946.. function:: repr(object)
947
Georg Brandl68ee3a52008-03-25 07:21:32 +0000948 Return a string containing a printable representation of an object. For many
949 types, this function makes an attempt to return a string that would yield an
950 object with the same value when passed to :func:`eval`, otherwise the
951 representation is a string enclosed in angle brackets that contains the name
952 of the type of the object together with additional information often
953 including the name and address of the object. A class can control what this
954 function returns for its instances by defining a :meth:`__repr__` method.
Georg Brandl116aa622007-08-15 14:28:22 +0000955
956
957.. function:: reversed(seq)
958
Christian Heimes7f044312008-01-06 17:05:40 +0000959 Return a reverse :term:`iterator`. *seq* must be an object which has
960 a :meth:`__reversed__` method or supports the sequence protocol (the
961 :meth:`__len__` method and the :meth:`__getitem__` method with integer
962 arguments starting at ``0``).
Georg Brandl116aa622007-08-15 14:28:22 +0000963
Georg Brandl116aa622007-08-15 14:28:22 +0000964
965.. function:: round(x[, n])
966
967 Return the floating point value *x* rounded to *n* digits after the decimal
Georg Brandl809ddaa2008-07-01 20:39:59 +0000968 point. If *n* is omitted, it defaults to zero. Delegates to
969 ``x.__round__(n)``.
970
971 For the built-in types supporting :func:`round`, values are rounded to the
Christian Heimes072c0f12008-01-03 23:01:04 +0000972 closest multiple of 10 to the power minus *n*; if two multiples are equally
973 close, rounding is done toward the even choice (so, for example, both
Georg Brandl809ddaa2008-07-01 20:39:59 +0000974 ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is ``2``).
975 The return value is an integer if called with one argument, otherwise of the
976 same type as *x*.
Christian Heimes072c0f12008-01-03 23:01:04 +0000977
Mark Dickinsonc4fbcdc2010-07-30 13:13:02 +0000978 .. note::
979
980 The behavior of :func:`round` for floats can be surprising: for example,
981 ``round(2.675, 2)`` gives ``2.67`` instead of the expected ``2.68``.
982 This is not a bug: it's a result of the fact that most decimal fractions
983 can't be represented exactly as a float. See :ref:`tut-fp-issues` for
984 more information.
Georg Brandl116aa622007-08-15 14:28:22 +0000985
986.. function:: set([iterable])
987 :noindex:
988
Benjamin Peterson97dd9872009-12-13 01:23:39 +0000989 Return a new set, optionally with elements taken from *iterable*.
Georg Brandl116aa622007-08-15 14:28:22 +0000990 The set type is described in :ref:`types-set`.
991
Georg Brandl116aa622007-08-15 14:28:22 +0000992
993.. function:: setattr(object, name, value)
994
995 This is the counterpart of :func:`getattr`. The arguments are an object, a
996 string and an arbitrary value. The string may name an existing attribute or a
997 new attribute. The function assigns the value to the attribute, provided the
998 object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to
999 ``x.foobar = 123``.
1000
1001
1002.. function:: slice([start,] stop[, step])
1003
1004 .. index:: single: Numerical Python
1005
Christian Heimesd8654cf2007-12-02 15:22:16 +00001006 Return a :term:`slice` object representing the set of indices specified by
Georg Brandl116aa622007-08-15 14:28:22 +00001007 ``range(start, stop, step)``. The *start* and *step* arguments default to
1008 ``None``. Slice objects have read-only data attributes :attr:`start`,
1009 :attr:`stop` and :attr:`step` which merely return the argument values (or their
1010 default). They have no other explicit functionality; however they are used by
1011 Numerical Python and other third party extensions. Slice objects are also
1012 generated when extended indexing syntax is used. For example:
Raymond Hettingercdf8ba32009-02-19 04:45:07 +00001013 ``a[start:stop:step]`` or ``a[start:stop, i]``. See :func:`itertools.islice`
1014 for an alternate version that returns an iterator.
Georg Brandl116aa622007-08-15 14:28:22 +00001015
1016
Georg Brandl036490d2009-05-17 13:00:36 +00001017.. function:: sorted(iterable[, key][, reverse])
Georg Brandl116aa622007-08-15 14:28:22 +00001018
1019 Return a new sorted list from the items in *iterable*.
1020
Raymond Hettinger51b9c242008-02-14 13:52:24 +00001021 Has two optional arguments which must be specified as keyword arguments.
Georg Brandl116aa622007-08-15 14:28:22 +00001022
Georg Brandl116aa622007-08-15 14:28:22 +00001023 *key* specifies a function of one argument that is used to extract a comparison
Georg Brandl1f70cdf2010-03-21 09:04:24 +00001024 key from each list element: ``key=str.lower``. The default value is ``None``
1025 (compare the elements directly).
Georg Brandl116aa622007-08-15 14:28:22 +00001026
1027 *reverse* is a boolean value. If set to ``True``, then the list elements are
1028 sorted as if each comparison were reversed.
1029
Raymond Hettingerc50846a2010-04-05 18:56:31 +00001030 Use :func:`functools.cmp_to_key` to convert an
1031 old-style *cmp* function to a *key* function.
Georg Brandl116aa622007-08-15 14:28:22 +00001032
Raymond Hettinger46fca072010-04-02 00:25:45 +00001033 For sorting examples and a brief sorting tutorial, see `Sorting HowTo
1034 <http://wiki.python.org/moin/HowTo/Sorting/>`_\.
1035
Georg Brandl116aa622007-08-15 14:28:22 +00001036.. function:: staticmethod(function)
1037
1038 Return a static method for *function*.
1039
1040 A static method does not receive an implicit first argument. To declare a static
1041 method, use this idiom::
1042
1043 class C:
1044 @staticmethod
1045 def f(arg1, arg2, ...): ...
1046
Christian Heimesd8654cf2007-12-02 15:22:16 +00001047 The ``@staticmethod`` form is a function :term:`decorator` -- see the
1048 description of function definitions in :ref:`function` for details.
Georg Brandl116aa622007-08-15 14:28:22 +00001049
1050 It can be called either on the class (such as ``C.f()``) or on an instance (such
1051 as ``C().f()``). The instance is ignored except for its class.
1052
1053 Static methods in Python are similar to those found in Java or C++. For a more
1054 advanced concept, see :func:`classmethod` in this section.
1055
1056 For more information on static methods, consult the documentation on the
1057 standard type hierarchy in :ref:`types`.
1058
Georg Brandl116aa622007-08-15 14:28:22 +00001059
1060.. function:: str([object[, encoding[, errors]]])
1061
1062 Return a string version of an object, using one of the following modes:
Georg Brandl48310cd2009-01-03 21:18:54 +00001063
Georg Brandl116aa622007-08-15 14:28:22 +00001064 If *encoding* and/or *errors* are given, :func:`str` will decode the
1065 *object* which can either be a byte string or a character buffer using
1066 the codec for *encoding*. The *encoding* parameter is a string giving
1067 the name of an encoding; if the encoding is not known, :exc:`LookupError`
1068 is raised. Error handling is done according to *errors*; this specifies the
1069 treatment of characters which are invalid in the input encoding. If
1070 *errors* is ``'strict'`` (the default), a :exc:`ValueError` is raised on
1071 errors, while a value of ``'ignore'`` causes errors to be silently ignored,
1072 and a value of ``'replace'`` causes the official Unicode replacement character,
1073 U+FFFD, to be used to replace input characters which cannot be decoded.
Georg Brandl48310cd2009-01-03 21:18:54 +00001074 See also the :mod:`codecs` module.
Georg Brandl116aa622007-08-15 14:28:22 +00001075
1076 When only *object* is given, this returns its nicely printable representation.
1077 For strings, this is the string itself. The difference with ``repr(object)``
1078 is that ``str(object)`` does not always attempt to return a string that is
1079 acceptable to :func:`eval`; its goal is to return a printable string.
1080 With no arguments, this returns the empty string.
1081
1082 Objects can specify what ``str(object)`` returns by defining a :meth:`__str__`
1083 special method.
1084
1085 For more information on strings see :ref:`typesseq` which describes sequence
1086 functionality (strings are sequences), and also the string-specific methods
Georg Brandl4b491312007-08-31 09:22:56 +00001087 described in the :ref:`string-methods` section. To output formatted strings,
1088 see the :ref:`string-formatting` section. In addition see the
1089 :ref:`stringservices` section.
Georg Brandl116aa622007-08-15 14:28:22 +00001090
1091
1092.. function:: sum(iterable[, start])
1093
1094 Sums *start* and the items of an *iterable* from left to right and returns the
1095 total. *start* defaults to ``0``. The *iterable*'s items are normally numbers,
1096 and are not allowed to be strings. The fast, correct way to concatenate a
Raymond Hettingercdf8ba32009-02-19 04:45:07 +00001097 sequence of strings is by calling ``''.join(sequence)``. To add floating
1098 point values with extended precision, see :func:`math.fsum`\.
Georg Brandl116aa622007-08-15 14:28:22 +00001099
Georg Brandl116aa622007-08-15 14:28:22 +00001100
Mark Summerfield1041f742008-02-26 13:27:00 +00001101.. function:: super([type[, object-or-type]])
Georg Brandl116aa622007-08-15 14:28:22 +00001102
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001103 Return a proxy object that delegates method calls to a parent or sibling
1104 class of *type*. This is useful for accessing inherited methods that have
1105 been overridden in a class. The search order is same as that used by
1106 :func:`getattr` except that the *type* itself is skipped.
1107
Raymond Hettinger0a68b012009-02-25 00:58:47 +00001108 The :attr:`__mro__` attribute of the *type* lists the method resolution
1109 search order used by both :func:`getattr` and :func:`super`. The attribute
1110 is dynamic and can change whenever the inheritance hierarchy is updated.
Benjamin Peterson3e4f0552008-09-02 00:31:15 +00001111
Raymond Hettinger79d04342009-02-25 00:32:51 +00001112 If the second argument is omitted, the super object returned is unbound. If
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001113 the second argument is an object, ``isinstance(obj, type)`` must be true. If
Benjamin Petersond75fcb42009-02-19 04:22:03 +00001114 the second argument is a type, ``issubclass(type2, type)`` must be true (this
1115 is useful for classmethods).
Georg Brandl116aa622007-08-15 14:28:22 +00001116
Raymond Hettinger0a68b012009-02-25 00:58:47 +00001117 There are two typical use cases for *super*. In a class hierarchy with
1118 single inheritance, *super* can be used to refer to parent classes without
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001119 naming them explicitly, thus making the code more maintainable. This use
Raymond Hettinger0a68b012009-02-25 00:58:47 +00001120 closely parallels the use of *super* in other programming languages.
Georg Brandl48310cd2009-01-03 21:18:54 +00001121
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001122 The second use case is to support cooperative multiple inheritance in a
Georg Brandl48310cd2009-01-03 21:18:54 +00001123 dynamic execution environment. This use case is unique to Python and is
1124 not found in statically compiled languages or languages that only support
Raymond Hettingerd1258452009-02-26 00:27:18 +00001125 single inheritance. This makes it possible to implement "diamond diagrams"
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001126 where multiple base classes implement the same method. Good design dictates
1127 that this method have the same calling signature in every case (because the
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001128 order of calls is determined at runtime, because that order adapts
1129 to changes in the class hierarchy, and because that order can include
1130 sibling classes that are unknown prior to runtime).
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001131
1132 For both use cases, a typical superclass call looks like this::
Georg Brandl116aa622007-08-15 14:28:22 +00001133
1134 class C(B):
Mark Summerfield1041f742008-02-26 13:27:00 +00001135 def method(self, arg):
Georg Brandl036490d2009-05-17 13:00:36 +00001136 super().method(arg) # This does the same thing as:
1137 # super(C, self).method(arg)
Georg Brandl116aa622007-08-15 14:28:22 +00001138
1139 Note that :func:`super` is implemented as part of the binding process for
Mark Summerfield1041f742008-02-26 13:27:00 +00001140 explicit dotted attribute lookups such as ``super().__getitem__(name)``.
Benjamin Peterson9bc93512008-09-22 22:10:59 +00001141 It does so by implementing its own :meth:`__getattribute__` method for searching
Raymond Hettinger4d9a8232009-02-24 23:30:43 +00001142 classes in a predictable order that supports cooperative multiple inheritance.
Georg Brandl116aa622007-08-15 14:28:22 +00001143 Accordingly, :func:`super` is undefined for implicit lookups using statements or
Raymond Hettinger518d8da2008-12-06 11:44:00 +00001144 operators such as ``super()[name]``.
1145
Raymond Hettinger79d04342009-02-25 00:32:51 +00001146 Also note that :func:`super` is not limited to use inside methods. The two
1147 argument form specifies the arguments exactly and makes the appropriate
Raymond Hettinger518d8da2008-12-06 11:44:00 +00001148 references. The zero argument form automatically searches the stack frame
1149 for the class (``__class__``) and the first argument.
Georg Brandl116aa622007-08-15 14:28:22 +00001150
Georg Brandl116aa622007-08-15 14:28:22 +00001151
1152.. function:: tuple([iterable])
1153
1154 Return a tuple whose items are the same and in the same order as *iterable*'s
1155 items. *iterable* may be a sequence, a container that supports iteration, or an
1156 iterator object. If *iterable* is already a tuple, it is returned unchanged.
1157 For instance, ``tuple('abc')`` returns ``('a', 'b', 'c')`` and ``tuple([1, 2,
1158 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty
1159 tuple, ``()``.
1160
Georg Brandl48310cd2009-01-03 21:18:54 +00001161 :class:`tuple` is an immutable sequence type, as documented in :ref:`typesseq`.
Georg Brandl116aa622007-08-15 14:28:22 +00001162
1163
1164.. function:: type(object)
1165
1166 .. index:: object: type
1167
Georg Brandl85eb8c12007-08-31 16:33:38 +00001168 Return the type of an *object*. The return value is a type object and
1169 generally the same object as returned by ``object.__class__``.
Georg Brandl116aa622007-08-15 14:28:22 +00001170
Georg Brandl85eb8c12007-08-31 16:33:38 +00001171 The :func:`isinstance` built-in function is recommended for testing the type
1172 of an object, because it takes subclasses into account.
1173
1174 With three arguments, :func:`type` functions as a constructor as detailed
1175 below.
Georg Brandl116aa622007-08-15 14:28:22 +00001176
1177
1178.. function:: type(name, bases, dict)
1179 :noindex:
1180
1181 Return a new type object. This is essentially a dynamic form of the
Christian Heimesfe337bf2008-03-23 21:54:12 +00001182 :keyword:`class` statement. The *name* string is the class name and becomes the
1183 :attr:`__name__` attribute; the *bases* tuple itemizes the base classes and
1184 becomes the :attr:`__bases__` attribute; and the *dict* dictionary is the
1185 namespace containing definitions for class body and becomes the :attr:`__dict__`
1186 attribute. For example, the following two statements create identical
1187 :class:`type` objects:
Georg Brandl116aa622007-08-15 14:28:22 +00001188
1189 >>> class X(object):
1190 ... a = 1
Georg Brandl48310cd2009-01-03 21:18:54 +00001191 ...
Georg Brandl116aa622007-08-15 14:28:22 +00001192 >>> X = type('X', (object,), dict(a=1))
1193
Georg Brandl116aa622007-08-15 14:28:22 +00001194
1195.. function:: vars([object])
1196
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +00001197 Without an argument, act like :func:`locals`.
1198
1199 With a module, class or class instance object as argument (or anything else that
1200 has a :attr:`__dict__` attribute), return that attribute.
Georg Brandl116aa622007-08-15 14:28:22 +00001201
Georg Brandle720c0a2009-04-27 16:20:50 +00001202 .. note::
Benjamin Petersond23f8222009-04-05 19:13:16 +00001203 The returned dictionary should not be modified:
1204 the effects on the corresponding symbol table are undefined. [#]_
Georg Brandl116aa622007-08-15 14:28:22 +00001205
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001206.. function:: zip(*iterables)
Georg Brandl116aa622007-08-15 14:28:22 +00001207
Georg Brandl48310cd2009-01-03 21:18:54 +00001208 Make an iterator that aggregates elements from each of the iterables.
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001209
1210 Returns an iterator of tuples, where the *i*-th tuple contains
Georg Brandl952aea22007-09-04 17:50:40 +00001211 the *i*-th element from each of the argument sequences or iterables. The
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001212 iterator stops when the shortest input iterable is exhausted. With a single
Georg Brandl48310cd2009-01-03 21:18:54 +00001213 iterable argument, it returns an iterator of 1-tuples. With no arguments,
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001214 it returns an empty iterator. Equivalent to::
1215
1216 def zip(*iterables):
1217 # zip('ABCD', 'xy') --> Ax By
1218 iterables = map(iter, iterables)
1219 while iterables:
Raymond Hettingercdf8ba32009-02-19 04:45:07 +00001220 yield tuple(map(next, iterables))
Georg Brandl116aa622007-08-15 14:28:22 +00001221
Christian Heimes1af737c2008-01-23 08:24:23 +00001222 The left-to-right evaluation order of the iterables is guaranteed. This
1223 makes possible an idiom for clustering a data series into n-length groups
1224 using ``zip(*[iter(s)]*n)``.
1225
Raymond Hettingerdd1150e2008-03-13 02:39:40 +00001226 :func:`zip` should only be used with unequal length inputs when you don't
1227 care about trailing, unmatched values from the longer iterables. If those
1228 values are important, use :func:`itertools.zip_longest` instead.
Georg Brandl116aa622007-08-15 14:28:22 +00001229
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001230 :func:`zip` in conjunction with the ``*`` operator can be used to unzip a
1231 list::
1232
1233 >>> x = [1, 2, 3]
1234 >>> y = [4, 5, 6]
1235 >>> zipped = zip(x, y)
Georg Brandl17fe3642008-12-06 14:28:56 +00001236 >>> list(zipped)
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001237 [(1, 4), (2, 5), (3, 6)]
Georg Brandl17fe3642008-12-06 14:28:56 +00001238 >>> x2, y2 = zip(*zip(x, y))
Benjamin Petersonfa0d7032009-06-01 22:42:33 +00001239 >>> x == list(x2) and y == list(y2)
Benjamin Petersonf10a79a2008-10-11 00:49:57 +00001240 True
1241
Georg Brandl2ee470f2008-07-16 12:55:28 +00001242
Benjamin Peterson25503462010-05-27 22:32:22 +00001243.. function:: __import__(name, globals={}, locals={}, fromlist=[], level=0)
Georg Brandl48367812008-12-05 15:55:41 +00001244
1245 .. index::
1246 statement: import
1247 module: imp
1248
1249 .. note::
1250
1251 This is an advanced function that is not needed in everyday Python
1252 programming.
1253
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001254 This function is invoked by the :keyword:`import` statement. It can be
1255 replaced (by importing the :mod:`builtins` module and assigning to
1256 ``builtins.__import__``) in order to change semantics of the
1257 :keyword:`import` statement, but nowadays it is usually simpler to use import
1258 hooks (see :pep:`302`). Direct use of :func:`__import__` is rare, except in
1259 cases where you want to import a module whose name is only known at runtime.
Georg Brandl48367812008-12-05 15:55:41 +00001260
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001261 The function imports the module *name*, potentially using the given *globals*
1262 and *locals* to determine how to interpret the name in a package context.
1263 The *fromlist* gives the names of objects or submodules that should be
1264 imported from the module given by *name*. The standard implementation does
1265 not use its *locals* argument at all, and uses its *globals* only to
1266 determine the package context of the :keyword:`import` statement.
1267
Brett Cannon2b9fd472009-03-15 02:18:41 +00001268 *level* specifies whether to use absolute or relative imports. ``0`` (the
1269 default) means only perform absolute imports. Positive values for
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001270 *level* indicate the number of parent directories to search relative to the
1271 directory of the module calling :func:`__import__`.
Georg Brandl48367812008-12-05 15:55:41 +00001272
1273 When the *name* variable is of the form ``package.module``, normally, the
1274 top-level package (the name up till the first dot) is returned, *not* the
1275 module named by *name*. However, when a non-empty *fromlist* argument is
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001276 given, the module named by *name* is returned.
Georg Brandl48367812008-12-05 15:55:41 +00001277
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001278 For example, the statement ``import spam`` results in bytecode resembling the
1279 following code::
Georg Brandl48310cd2009-01-03 21:18:54 +00001280
Brett Cannon2b9fd472009-03-15 02:18:41 +00001281 spam = __import__('spam', globals(), locals(), [], 0)
Georg Brandl48367812008-12-05 15:55:41 +00001282
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001283 The statement ``import spam.ham`` results in this call::
Georg Brandl48367812008-12-05 15:55:41 +00001284
Brett Cannon2b9fd472009-03-15 02:18:41 +00001285 spam = __import__('spam.ham', globals(), locals(), [], 0)
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001286
1287 Note how :func:`__import__` returns the toplevel module here because this is
1288 the object that is bound to a name by the :keyword:`import` statement.
1289
1290 On the other hand, the statement ``from spam.ham import eggs, sausage as
1291 saus`` results in ::
1292
Brett Cannon2b9fd472009-03-15 02:18:41 +00001293 _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001294 eggs = _temp.eggs
1295 saus = _temp.sausage
1296
1297 Here, the ``spam.ham`` module is returned from :func:`__import__`. From this
1298 object, the names to import are retrieved and assigned to their respective
1299 names.
1300
1301 If you simply want to import a module (potentially within a package) by name,
Benjamin Petersonfa0d7032009-06-01 22:42:33 +00001302 you can call :func:`__import__` and then look it up in :data:`sys.modules`::
Benjamin Peterson6ebe78f2008-12-21 00:06:59 +00001303
1304 >>> import sys
1305 >>> name = 'foo.bar.baz'
1306 >>> __import__(name)
1307 <module 'foo' from ...>
1308 >>> baz = sys.modules[name]
1309 >>> baz
1310 <module 'foo.bar.baz' from ...>
Georg Brandl48367812008-12-05 15:55:41 +00001311
Georg Brandl116aa622007-08-15 14:28:22 +00001312.. rubric:: Footnotes
1313
Georg Brandl47f27a32009-03-31 16:57:13 +00001314.. [#] Note that the parser only accepts the Unix-style end of line convention.
1315 If you are reading the code from a file, make sure to use newline conversion
1316 mode to convert Windows or Mac-style newlines.
Georg Brandl116aa622007-08-15 14:28:22 +00001317
1318.. [#] In the current implementation, local variable bindings cannot normally be
1319 affected this way, but variables retrieved from other scopes (such as modules)
1320 can be. This may change.