blob: 68601e5e9c81429fa3990d853812d2d7b1f34b00 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001
2.. _built-in-funcs:
3
4Built-in Functions
5==================
6
7The Python interpreter has a number of functions built into it that are always
8available. They are listed here in alphabetical order.
9
10
11.. function:: __import__(name[, globals[, locals[, fromlist[, level]]]])
12
13 .. index::
14 statement: import
Georg Brandl116aa622007-08-15 14:28:22 +000015 module: imp
16
17 .. note::
18
19 This is an advanced function that is not needed in everyday Python
20 programming.
21
22 The function is invoked by the :keyword:`import` statement. It mainly exists
23 so that you can replace it with another function that has a compatible
Georg Brandl55ac8f02007-09-01 13:51:09 +000024 interface, in order to change the semantics of the :keyword:`import`
25 statement. For examples of why and how you would do this, see the standard
26 library module :mod:`ihooks`. See also the built-in module :mod:`imp`, which
Georg Brandl116aa622007-08-15 14:28:22 +000027 defines some useful operations out of which you can build your own
28 :func:`__import__` function.
29
30 For example, the statement ``import spam`` results in the following call:
31 ``__import__('spam',`` ``globals(),`` ``locals(), [], -1)``; the statement
32 ``from spam.ham import eggs`` results in ``__import__('spam.ham', globals(),
33 locals(), ['eggs'], -1)``. Note that even though ``locals()`` and ``['eggs']``
34 are passed in as arguments, the :func:`__import__` function does not set the
35 local variable named ``eggs``; this is done by subsequent code that is generated
36 for the import statement. (In fact, the standard implementation does not use
37 its *locals* argument at all, and uses its *globals* only to determine the
38 package context of the :keyword:`import` statement.)
39
40 When the *name* variable is of the form ``package.module``, normally, the
41 top-level package (the name up till the first dot) is returned, *not* the
42 module named by *name*. However, when a non-empty *fromlist* argument is
43 given, the module named by *name* is returned. This is done for
Georg Brandl9afde1c2007-11-01 20:32:30 +000044 compatibility with the :term:`bytecode` generated for the different kinds of import
Georg Brandl116aa622007-08-15 14:28:22 +000045 statement; when using ``import spam.ham.eggs``, the top-level package
46 :mod:`spam` must be placed in the importing namespace, but when using ``from
47 spam.ham import eggs``, the ``spam.ham`` subpackage must be used to find the
48 ``eggs`` variable. As a workaround for this behavior, use :func:`getattr` to
49 extract the desired components. For example, you could define the following
50 helper::
51
52 def my_import(name):
53 mod = __import__(name)
54 components = name.split('.')
55 for comp in components[1:]:
56 mod = getattr(mod, comp)
57 return mod
58
59 *level* specifies whether to use absolute or relative imports. The default is
60 ``-1`` which indicates both absolute and relative imports will be attempted.
61 ``0`` means only perform absolute imports. Positive values for *level* indicate
62 the number of parent directories to search relative to the directory of the
63 module calling :func:`__import__`.
64
Georg Brandl116aa622007-08-15 14:28:22 +000065
66.. function:: abs(x)
67
Georg Brandlba956ae2007-11-29 17:24:34 +000068 Return the absolute value of a number. The argument may be an
Georg Brandl116aa622007-08-15 14:28:22 +000069 integer or a floating point number. If the argument is a complex number, its
70 magnitude is returned.
71
72
73.. function:: all(iterable)
74
75 Return True if all elements of the *iterable* are true. Equivalent to::
76
77 def all(iterable):
78 for element in iterable:
79 if not element:
80 return False
81 return True
82
Georg Brandl116aa622007-08-15 14:28:22 +000083
84.. function:: any(iterable)
85
86 Return True if any element of the *iterable* is true. Equivalent to::
87
88 def any(iterable):
89 for element in iterable:
90 if element:
91 return True
92 return False
93
Georg Brandl116aa622007-08-15 14:28:22 +000094
95.. function:: basestring()
96
97 This abstract type is the superclass for :class:`str`. It
98 cannot be called or instantiated, but it can be used to test whether an object
99 is an instance of :class:`str` (or a user-defined type inherited from
100 :class:`basestring`).
101
Georg Brandl116aa622007-08-15 14:28:22 +0000102
103.. function:: bin(x)
104
105 Convert an integer number to a binary string. The result is a valid Python
106 expression. If *x* is not a Python :class:`int` object, it has to define an
107 :meth:`__index__` method that returns an integer.
108
Georg Brandl116aa622007-08-15 14:28:22 +0000109
110.. function:: bool([x])
111
112 Convert a value to a Boolean, using the standard truth testing procedure. If
113 *x* is false or omitted, this returns :const:`False`; otherwise it returns
114 :const:`True`. :class:`bool` is also a class, which is a subclass of
115 :class:`int`. Class :class:`bool` cannot be subclassed further. Its only
116 instances are :const:`False` and :const:`True`.
117
118 .. index:: pair: Boolean; type
119
Georg Brandl116aa622007-08-15 14:28:22 +0000120
Georg Brandl95414632007-11-22 11:00:28 +0000121.. function:: bytearray([arg[, encoding[, errors]]])
Georg Brandl85eb8c12007-08-31 16:33:38 +0000122
Georg Brandl24eac032007-11-22 14:16:00 +0000123 Return a new array of bytes. The :class:`bytearray` type is a mutable
Georg Brandl95414632007-11-22 11:00:28 +0000124 sequence of integers in the range 0 <= x < 256. It has most of the usual
125 methods of mutable sequences, described in :ref:`typesseq-mutable`, as well
126 as most methods that the :class:`str` type has, see :ref:`bytes-methods`.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000127
128 The optional *arg* parameter can be used to initialize the array in a few
129 different ways:
130
131 * If it is a *string*, you must also give the *encoding* (and optionally,
Georg Brandl95414632007-11-22 11:00:28 +0000132 *errors*) parameters; :func:`bytearray` then converts the Unicode string to
Guido van Rossum98297ee2007-11-06 21:34:58 +0000133 bytes using :meth:`str.encode`.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000134
135 * If it is an *integer*, the array will have that size and will be
136 initialized with null bytes.
137
138 * If it is an object conforming to the *buffer* interface, a read-only buffer
139 of the object will be used to initialize the bytes array.
140
Guido van Rossum98297ee2007-11-06 21:34:58 +0000141 * If it is an *iterable*, it must be an iterable of integers in the range
142 ``0 <= x < 256``, which are used as the initial contents of the array.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000143
144 Without an argument, an array of size 0 is created.
145
146
Guido van Rossum98297ee2007-11-06 21:34:58 +0000147.. function:: bytes([arg[, encoding[, errors]]])
148
149 Return a new "bytes" object, which is an immutable sequence of integers in
150 the range ``0 <= x < 256``. :class:`bytes` is an immutable version of
Georg Brandl95414632007-11-22 11:00:28 +0000151 :class:`bytearray` -- it has the same non-mutating methods and the same
152 indexing and slicing behavior.
Guido van Rossum98297ee2007-11-06 21:34:58 +0000153
154 Accordingly, constructor arguments are interpreted as for :func:`buffer`.
155
156 Bytes objects can also be created with literals, see :ref:`strings`.
157
158
Georg Brandl116aa622007-08-15 14:28:22 +0000159.. function:: chr(i)
160
Georg Brandl85eb8c12007-08-31 16:33:38 +0000161 Return the string of one character whose Unicode codepoint is the integer
162 *i*. For example, ``chr(97)`` returns the string ``'a'``. This is the
163 inverse of :func:`ord`. The valid range for the argument depends how Python
164 was configured -- it may be either UCS2 [0..0xFFFF] or UCS4 [0..0x10FFFF].
Georg Brandl116aa622007-08-15 14:28:22 +0000165 :exc:`ValueError` will be raised if *i* is outside that range.
166
167
168.. function:: classmethod(function)
169
170 Return a class method for *function*.
171
172 A class method receives the class as implicit first argument, just like an
173 instance method receives the instance. To declare a class method, use this
174 idiom::
175
176 class C:
177 @classmethod
178 def f(cls, arg1, arg2, ...): ...
179
180 The ``@classmethod`` form is a function decorator -- see the description of
181 function definitions in :ref:`function` for details.
182
183 It can be called either on the class (such as ``C.f()``) or on an instance (such
184 as ``C().f()``). The instance is ignored except for its class. If a class
185 method is called for a derived class, the derived class object is passed as the
186 implied first argument.
187
188 Class methods are different than C++ or Java static methods. If you want those,
189 see :func:`staticmethod` in this section.
190
191 For more information on class methods, consult the documentation on the standard
192 type hierarchy in :ref:`types`.
193
Georg Brandl116aa622007-08-15 14:28:22 +0000194
195.. function:: cmp(x, y)
196
197 Compare the two objects *x* and *y* and return an integer according to the
198 outcome. The return value is negative if ``x < y``, zero if ``x == y`` and
199 strictly positive if ``x > y``.
200
201
202.. function:: compile(source, filename, mode[, flags[, dont_inherit]])
203
204 Compile the *source* into a code object. Code objects can be executed by a call
205 to :func:`exec` or evaluated by a call to :func:`eval`. The *filename* argument
206 should give the file from which the code was read; pass some recognizable value
207 if it wasn't read from a file (``'<string>'`` is commonly used). The *mode*
208 argument specifies what kind of code must be compiled; it can be ``'exec'`` if
209 *source* consists of a sequence of statements, ``'eval'`` if it consists of a
210 single expression, or ``'single'`` if it consists of a single interactive
211 statement (in the latter case, expression statements that evaluate to something
212 else than ``None`` will be printed).
213
214 When compiling multi-line statements, two caveats apply: line endings must be
215 represented by a single newline character (``'\n'``), and the input must be
216 terminated by at least one newline character. If line endings are represented
217 by ``'\r\n'``, use the string :meth:`replace` method to change them into
218 ``'\n'``.
219
220 The optional arguments *flags* and *dont_inherit* (which are new in Python 2.2)
221 control which future statements (see :pep:`236`) affect the compilation of
222 *source*. If neither is present (or both are zero) the code is compiled with
223 those future statements that are in effect in the code that is calling compile.
224 If the *flags* argument is given and *dont_inherit* is not (or is zero) then the
225 future statements specified by the *flags* argument are used in addition to
226 those that would be used anyway. If *dont_inherit* is a non-zero integer then
227 the *flags* argument is it -- the future statements in effect around the call to
228 compile are ignored.
229
230 Future statements are specified by bits which can be bitwise or-ed together to
231 specify multiple statements. The bitfield required to specify a given feature
232 can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
233 instance in the :mod:`__future__` module.
234
235
236.. function:: complex([real[, imag]])
237
238 Create a complex number with the value *real* + *imag*\*j or convert a string or
239 number to a complex number. If the first parameter is a string, it will be
240 interpreted as a complex number and the function must be called without a second
241 parameter. The second parameter can never be a string. Each argument may be any
242 numeric type (including complex). If *imag* is omitted, it defaults to zero and
Georg Brandl5c106642007-11-29 17:41:05 +0000243 the function serves as a numeric conversion function like :func:`int`
244 and :func:`float`. If both arguments are omitted, returns ``0j``.
Georg Brandl116aa622007-08-15 14:28:22 +0000245
246 The complex type is described in :ref:`typesnumeric`.
247
248
249.. function:: delattr(object, name)
250
251 This is a relative of :func:`setattr`. The arguments are an object and a
252 string. The string must be the name of one of the object's attributes. The
253 function deletes the named attribute, provided the object allows it. For
254 example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
255
256
257.. function:: dict([arg])
258 :noindex:
259
260 Create a new data dictionary, optionally with items taken from *arg*.
261 The dictionary type is described in :ref:`typesmapping`.
262
263 For other containers see the built in :class:`list`, :class:`set`, and
264 :class:`tuple` classes, and the :mod:`collections` module.
265
266
267.. function:: dir([object])
268
269 Without arguments, return the list of names in the current local scope. With an
270 argument, attempt to return a list of valid attributes for that object.
271
272 If the object has a method named :meth:`__dir__`, this method will be called and
273 must return the list of attributes. This allows objects that implement a custom
274 :func:`__getattr__` or :func:`__getattribute__` function to customize the way
275 :func:`dir` reports their attributes.
276
277 If the object does not provide :meth:`__dir__`, the function tries its best to
278 gather information from the object's :attr:`__dict__` attribute, if defined, and
279 from its type object. The resulting list is not necessarily complete, and may
280 be inaccurate when the object has a custom :func:`__getattr__`.
281
282 The default :func:`dir` mechanism behaves differently with different types of
283 objects, as it attempts to produce the most relevant, rather than complete,
284 information:
285
286 * If the object is a module object, the list contains the names of the module's
287 attributes.
288
289 * If the object is a type or class object, the list contains the names of its
290 attributes, and recursively of the attributes of its bases.
291
292 * Otherwise, the list contains the object's attributes' names, the names of its
293 class's attributes, and recursively of the attributes of its class's base
294 classes.
295
296 The resulting list is sorted alphabetically. For example::
297
298 >>> import struct
299 >>> dir()
300 ['__builtins__', '__doc__', '__name__', 'struct']
301 >>> dir(struct)
302 ['__doc__', '__name__', 'calcsize', 'error', 'pack', 'unpack']
303 >>> class Foo(object):
304 ... def __dir__(self):
305 ... return ["kan", "ga", "roo"]
306 ...
307 >>> f = Foo()
308 >>> dir(f)
309 ['ga', 'kan', 'roo']
310
311 .. note::
312
313 Because :func:`dir` is supplied primarily as a convenience for use at an
314 interactive prompt, it tries to supply an interesting set of names more than it
315 tries to supply a rigorously or consistently defined set of names, and its
316 detailed behavior may change across releases.
317
318
319.. function:: divmod(a, b)
320
321 Take two (non complex) numbers as arguments and return a pair of numbers
Georg Brandl5c106642007-11-29 17:41:05 +0000322 consisting of their quotient and remainder when using integer division. With mixed
Georg Brandlba956ae2007-11-29 17:24:34 +0000323 operand types, the rules for binary arithmetic operators apply. For integers,
324 the result is the same as ``(a // b, a % b)``. For floating point
Georg Brandl116aa622007-08-15 14:28:22 +0000325 numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a / b)``
326 but may be 1 less than that. In any case ``q * b + a % b`` is very close to
327 *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0 <= abs(a % b)
328 < abs(b)``.
329
Georg Brandl116aa622007-08-15 14:28:22 +0000330
331.. function:: enumerate(iterable)
332
Georg Brandl9afde1c2007-11-01 20:32:30 +0000333 Return an enumerate object. *iterable* must be a sequence, an :term:`iterator`, or some
Georg Brandl116aa622007-08-15 14:28:22 +0000334 other object which supports iteration. The :meth:`__next__` method of the
335 iterator returned by :func:`enumerate` returns a tuple containing a count (from
336 zero) and the corresponding value obtained from iterating over *iterable*.
337 :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``,
338 ``(1, seq[1])``, ``(2, seq[2])``, .... For example::
339
340 >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter')]:
Georg Brandl6911e3c2007-09-04 07:15:32 +0000341 >>> print(i, season)
Georg Brandl116aa622007-08-15 14:28:22 +0000342 0 Spring
343 1 Summer
344 2 Fall
345 3 Winter
346
Georg Brandl116aa622007-08-15 14:28:22 +0000347
348.. function:: eval(expression[, globals[, locals]])
349
350 The arguments are a string and optional globals and locals. If provided,
351 *globals* must be a dictionary. If provided, *locals* can be any mapping
352 object.
353
Georg Brandl116aa622007-08-15 14:28:22 +0000354 The *expression* argument is parsed and evaluated as a Python expression
355 (technically speaking, a condition list) using the *globals* and *locals*
Georg Brandl9afde1c2007-11-01 20:32:30 +0000356 dictionaries as global and local namespace. If the *globals* dictionary is
Georg Brandl116aa622007-08-15 14:28:22 +0000357 present and lacks '__builtins__', the current globals are copied into *globals*
358 before *expression* is parsed. This means that *expression* normally has full
359 access to the standard :mod:`__builtin__` module and restricted environments are
360 propagated. If the *locals* dictionary is omitted it defaults to the *globals*
361 dictionary. If both dictionaries are omitted, the expression is executed in the
362 environment where :keyword:`eval` is called. The return value is the result of
363 the evaluated expression. Syntax errors are reported as exceptions. Example::
364
365 >>> x = 1
Georg Brandl6911e3c2007-09-04 07:15:32 +0000366 >>> eval('x+1')
Georg Brandl116aa622007-08-15 14:28:22 +0000367 2
368
369 This function can also be used to execute arbitrary code objects (such as those
370 created by :func:`compile`). In this case pass a code object instead of a
371 string. The code object must have been compiled passing ``'eval'`` as the
372 *kind* argument.
373
374 Hints: dynamic execution of statements is supported by the :func:`exec`
375 function. The :func:`globals` and :func:`locals` functions
376 returns the current global and local dictionary, respectively, which may be
377 useful to pass around for use by :func:`eval` or :func:`exec`.
378
379
380.. function:: exec(object[, globals[, locals]])
381
382 This function supports dynamic execution of Python code. *object* must be either
383 a string, an open file object, or a code object. If it is a string, the string
384 is parsed as a suite of Python statements which is then executed (unless a
385 syntax error occurs). If it is an open file, the file is parsed until EOF and
386 executed. If it is a code object, it is simply executed. In all cases, the
387 code that's executed is expected to be valid as file input (see the section
388 "File input" in the Reference Manual). Be aware that the :keyword:`return` and
389 :keyword:`yield` statements may not be used outside of function definitions even
390 within the context of code passed to the :func:`exec` function. The return value
391 is ``None``.
392
393 In all cases, if the optional parts are omitted, the code is executed in the
394 current scope. If only *globals* is provided, it must be a dictionary, which
395 will be used for both the global and the local variables. If *globals* and
396 *locals* are given, they are used for the global and local variables,
397 respectively. If provided, *locals* can be any mapping object.
398
399 If the *globals* dictionary does not contain a value for the key
400 ``__builtins__``, a reference to the dictionary of the built-in module
401 :mod:`__builtin__` is inserted under that key. That way you can control what
402 builtins are available to the executed code by inserting your own
403 ``__builtins__`` dictionary into *globals* before passing it to :func:`exec`.
404
405 .. note::
406
407 The built-in functions :func:`globals` and :func:`locals` return the current
408 global and local dictionary, respectively, which may be useful to pass around
409 for use as the second and third argument to :func:`exec`.
410
411 .. warning::
412
413 The default *locals* act as described for function :func:`locals` below:
414 modifications to the default *locals* dictionary should not be attempted. Pass
415 an explicit *locals* dictionary if you need to see effects of the code on
416 *locals* after function :func:`execfile` returns. :func:`exec` cannot be
417 used reliably to modify a function's locals.
418
419
420.. function:: filter(function, iterable)
421
Georg Brandl952aea22007-09-04 17:50:40 +0000422 Construct an iterator from those elements of *iterable* for which *function*
423 returns true. *iterable* may be either a sequence, a container which
Georg Brandl9afde1c2007-11-01 20:32:30 +0000424 supports iteration, or an iterator. If *function* is ``None``, the identity
425 function is assumed, that is, all elements of *iterable* that are false are
426 removed.
Georg Brandl116aa622007-08-15 14:28:22 +0000427
Georg Brandl952aea22007-09-04 17:50:40 +0000428 Note that ``filter(function, iterable)`` is equivalent to the generator
429 expression ``(item for item in iterable if function(item))`` if function is
430 not ``None`` and ``(item for item in iterable if item)`` if function is
431 ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000432
433
434.. function:: float([x])
435
436 Convert a string or a number to floating point. If the argument is a string, it
437 must contain a possibly signed decimal or floating point number, possibly
Georg Brandlba956ae2007-11-29 17:24:34 +0000438 embedded in whitespace. Otherwise, the argument may be an integer
Georg Brandl116aa622007-08-15 14:28:22 +0000439 or a floating point number, and a floating point number with the same value
440 (within Python's floating point precision) is returned. If no argument is
441 given, returns ``0.0``.
442
443 .. note::
444
445 .. index::
446 single: NaN
447 single: Infinity
448
449 When passing in a string, values for NaN and Infinity may be returned, depending
450 on the underlying C library. The specific set of strings accepted which cause
451 these values to be returned depends entirely on the C library and is known to
452 vary.
453
454 The float type is described in :ref:`typesnumeric`.
455
Georg Brandl4b491312007-08-31 09:22:56 +0000456.. function:: format(value[, format_spec])
457
458 .. index::
459 pair: str; format
460 single: __format__
461
462 Convert a string or a number to a "formatted" representation, as controlled
463 by *format_spec*. The interpretation of *format_spec* will depend on the
464 type of the *value* argument, however there is a standard formatting syntax
465 that is used by most built-in types: :ref:`formatspec`.
466
467 .. note::
468
469 ``format(value, format_spec)`` merely calls ``value.__format__(format_spec)``.
470
471
Georg Brandl116aa622007-08-15 14:28:22 +0000472.. function:: frozenset([iterable])
473 :noindex:
474
475 Return a frozenset object, optionally with elements taken from *iterable*.
476 The frozenset type is described in :ref:`types-set`.
477
478 For other containers see the built in :class:`dict`, :class:`list`, and
479 :class:`tuple` classes, and the :mod:`collections` module.
480
Georg Brandl116aa622007-08-15 14:28:22 +0000481
482.. function:: getattr(object, name[, default])
483
484 Return the value of the named attributed of *object*. *name* must be a string.
485 If the string is the name of one of the object's attributes, the result is the
486 value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
487 ``x.foobar``. If the named attribute does not exist, *default* is returned if
488 provided, otherwise :exc:`AttributeError` is raised.
489
490
491.. function:: globals()
492
493 Return a dictionary representing the current global symbol table. This is always
494 the dictionary of the current module (inside a function or method, this is the
495 module where it is defined, not the module from which it is called).
496
497
498.. function:: hasattr(object, name)
499
500 The arguments are an object and a string. The result is ``True`` if the string
501 is the name of one of the object's attributes, ``False`` if not. (This is
502 implemented by calling ``getattr(object, name)`` and seeing whether it raises an
503 exception or not.)
504
505
506.. function:: hash(object)
507
508 Return the hash value of the object (if it has one). Hash values are integers.
509 They are used to quickly compare dictionary keys during a dictionary lookup.
510 Numeric values that compare equal have the same hash value (even if they are of
511 different types, as is the case for 1 and 1.0).
512
513
514.. function:: help([object])
515
516 Invoke the built-in help system. (This function is intended for interactive
517 use.) If no argument is given, the interactive help system starts on the
518 interpreter console. If the argument is a string, then the string is looked up
519 as the name of a module, function, class, method, keyword, or documentation
520 topic, and a help page is printed on the console. If the argument is any other
521 kind of object, a help page on the object is generated.
522
Georg Brandl116aa622007-08-15 14:28:22 +0000523
524.. function:: hex(x)
525
526 Convert an integer number to a hexadecimal string. The result is a valid Python
527 expression. If *x* is not a Python :class:`int` object, it has to define an
528 :meth:`__index__` method that returns an integer.
529
Georg Brandl116aa622007-08-15 14:28:22 +0000530
531.. function:: id(object)
532
Georg Brandlba956ae2007-11-29 17:24:34 +0000533 Return the "identity" of an object. This is an integer which
Georg Brandl116aa622007-08-15 14:28:22 +0000534 is guaranteed to be unique and constant for this object during its lifetime.
535 Two objects with non-overlapping lifetimes may have the same :func:`id` value.
536 (Implementation note: this is the address of the object.)
537
538
Georg Brandlc0902982007-09-12 21:29:27 +0000539.. function:: input([prompt])
540
541 If the *prompt* argument is present, it is written to standard output without
542 a trailing newline. The function then reads a line from input, converts it
543 to a string (stripping a trailing newline), and returns that. When EOF is
544 read, :exc:`EOFError` is raised. Example::
545
Georg Brandl7b469422007-09-12 21:32:27 +0000546 >>> s = input('--> ')
Georg Brandlc0902982007-09-12 21:29:27 +0000547 --> Monty Python's Flying Circus
548 >>> s
549 "Monty Python's Flying Circus"
550
Georg Brandl7b469422007-09-12 21:32:27 +0000551 If the :mod:`readline` module was loaded, then :func:`input` will use it
Georg Brandlc0902982007-09-12 21:29:27 +0000552 to provide elaborate line editing and history features.
553
554
Georg Brandl116aa622007-08-15 14:28:22 +0000555.. function:: int([x[, radix]])
556
557 Convert a string or number to an integer. If the argument is a string, it
Georg Brandl9afde1c2007-11-01 20:32:30 +0000558 must contain a possibly signed number of arbitrary size, possibly embedded in
559 whitespace. The *radix* parameter gives the base for the conversion (which
560 is 10 by default) and may be any integer in the range [2, 36], or zero. If
561 *radix* is zero, the interpretation is the same as for integer literals. If
562 *radix* is specified and *x* is not a string, :exc:`TypeError` is raised.
563 Otherwise, the argument may be another integer, a floating point number or
564 any other object that has an :meth:`__int__` method. Conversion of floating
565 point numbers to integers truncates (towards zero). If no arguments are
566 given, returns ``0``.
Georg Brandl116aa622007-08-15 14:28:22 +0000567
568 The integer type is described in :ref:`typesnumeric`.
569
570
571.. function:: isinstance(object, classinfo)
572
Georg Brandl85eb8c12007-08-31 16:33:38 +0000573 Return true if the *object* argument is an instance of the *classinfo*
574 argument, or of a (direct or indirect) subclass thereof. If *object* is not
575 an object of the given type, the function always returns false. If
576 *classinfo* is not a class (type object), it may be a tuple of type objects,
577 or may recursively contain other such tuples (other sequence types are not
578 accepted). If *classinfo* is not a type or tuple of types and such tuples,
579 a :exc:`TypeError` exception is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000580
Georg Brandl116aa622007-08-15 14:28:22 +0000581
582.. function:: issubclass(class, classinfo)
583
584 Return true if *class* is a subclass (direct or indirect) of *classinfo*. A
585 class is considered a subclass of itself. *classinfo* may be a tuple of class
586 objects, in which case every entry in *classinfo* will be checked. In any other
587 case, a :exc:`TypeError` exception is raised.
588
Georg Brandl116aa622007-08-15 14:28:22 +0000589
590.. function:: iter(o[, sentinel])
591
Georg Brandl9afde1c2007-11-01 20:32:30 +0000592 Return an :term:`iterator` object. The first argument is interpreted very differently
Georg Brandl116aa622007-08-15 14:28:22 +0000593 depending on the presence of the second argument. Without a second argument, *o*
594 must be a collection object which supports the iteration protocol (the
595 :meth:`__iter__` method), or it must support the sequence protocol (the
596 :meth:`__getitem__` method with integer arguments starting at ``0``). If it
597 does not support either of those protocols, :exc:`TypeError` is raised. If the
598 second argument, *sentinel*, is given, then *o* must be a callable object. The
599 iterator created in this case will call *o* with no arguments for each call to
600 its :meth:`__next__` method; if the value returned is equal to *sentinel*,
601 :exc:`StopIteration` will be raised, otherwise the value will be returned.
602
Georg Brandl116aa622007-08-15 14:28:22 +0000603
604.. function:: len(s)
605
606 Return the length (the number of items) of an object. The argument may be a
607 sequence (string, tuple or list) or a mapping (dictionary).
608
609
610.. function:: list([iterable])
611
612 Return a list whose items are the same and in the same order as *iterable*'s
613 items. *iterable* may be either a sequence, a container that supports
614 iteration, or an iterator object. If *iterable* is already a list, a copy is
615 made and returned, similar to ``iterable[:]``. For instance, ``list('abc')``
616 returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. If
617 no argument is given, returns a new empty list, ``[]``.
618
619 :class:`list` is a mutable sequence type, as documented in
620 :ref:`typesseq`. For other containers see the built in :class:`dict`,
621 :class:`set`, and :class:`tuple` classes, and the :mod:`collections` module.
622
623
624.. function:: locals()
625
626 Update and return a dictionary representing the current local symbol table.
627
628 .. warning::
629
630 The contents of this dictionary should not be modified; changes may not affect
631 the values of local variables used by the interpreter.
632
633 Free variables are returned by *locals* when it is called in a function block.
634 Modifications of free variables may not affect the values used by the
635 interpreter. Free variables are not returned in class blocks.
636
637
638.. function:: map(function, iterable, ...)
639
Georg Brandl952aea22007-09-04 17:50:40 +0000640 Return an iterator that applies *function* to every item of *iterable*,
641 yielding the results. If additional *iterable* arguments are passed,
642 *function* must take that many arguments and is applied to the items from all
643 iterables in parallel. If one iterable is shorter than another it is assumed
644 to be extended with ``None`` items. If *function* is ``None``, the identity
645 function is assumed; if there are multiple arguments, :func:`map` returns a
646 list consisting of tuples containing the corresponding items from all
647 iterables (a kind of transpose operation). The *iterable* arguments may be a
648 sequence or any iterable object; the result is always a list.
649
650 Note that for only one *iterable* argument, ``map(function, iterable)`` is
651 equivalent to the generator expression ``(function(item) for item in
652 iterable)`` if *function* is not ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000653
654
Georg Brandl55ac8f02007-09-01 13:51:09 +0000655.. function:: max(iterable[, args...], *[, key])
Georg Brandl116aa622007-08-15 14:28:22 +0000656
657 With a single argument *iterable*, return the largest item of a non-empty
658 iterable (such as a string, tuple or list). With more than one argument, return
659 the largest of the arguments.
660
Georg Brandl55ac8f02007-09-01 13:51:09 +0000661 The optional keyword-only *key* argument specifies a one-argument ordering
662 function like that used for :meth:`list.sort`.
Georg Brandl116aa622007-08-15 14:28:22 +0000663
664
Georg Brandl85eb8c12007-08-31 16:33:38 +0000665.. function:: memoryview(obj)
666
667 Return a "memory view" object created from the given argument.
668
669 XXX: To be documented.
670
671
Georg Brandl55ac8f02007-09-01 13:51:09 +0000672.. function:: min(iterable[, args...], *[, key])
Georg Brandl116aa622007-08-15 14:28:22 +0000673
674 With a single argument *iterable*, return the smallest item of a non-empty
675 iterable (such as a string, tuple or list). With more than one argument, return
676 the smallest of the arguments.
677
Georg Brandl55ac8f02007-09-01 13:51:09 +0000678 The optional keyword-only *key* argument specifies a one-argument ordering
679 function like that used for :meth:`list.sort`.
Georg Brandl116aa622007-08-15 14:28:22 +0000680
681
682.. function:: next(iterator[, default])
683
684 Retrieve the next item from the *iterable* by calling its :meth:`__next__`
685 method. If *default* is given, it is returned if the iterator is exhausted,
686 otherwise :exc:`StopIteration` is raised.
687
688
689.. function:: object()
690
Georg Brandl85eb8c12007-08-31 16:33:38 +0000691 Return a new featureless object. :class:`object` is a base for all classes.
Georg Brandl55ac8f02007-09-01 13:51:09 +0000692 It has the methods that are common to all instances of Python classes. This
693 function does not accept any arguments.
Georg Brandl85eb8c12007-08-31 16:33:38 +0000694
695 .. note::
696
697 :class:`object` does *not* have a :attr:`__dict__`, so you can't assign
698 arbitrary attributes to an instance of the :class:`object` class.
Georg Brandl116aa622007-08-15 14:28:22 +0000699
Georg Brandl116aa622007-08-15 14:28:22 +0000700
701.. function:: oct(x)
702
703 Convert an integer number to an octal string. The result is a valid Python
704 expression. If *x* is not a Python :class:`int` object, it has to define an
705 :meth:`__index__` method that returns an integer.
706
Georg Brandl116aa622007-08-15 14:28:22 +0000707
708.. function:: open(filename[, mode[, bufsize]])
709
710 Open a file, returning an object of the :class:`file` type described in
711 section :ref:`bltin-file-objects`. If the file cannot be opened,
712 :exc:`IOError` is raised. When opening a file, it's preferable to use
713 :func:`open` instead of invoking the :class:`file` constructor directly.
714
715 The first two arguments are the same as for ``stdio``'s :cfunc:`fopen`:
Skip Montanaro1c639602007-09-23 19:49:54 +0000716 *filename* is the file name to be opened, and *mode* is a string
717 indicating how the file is to be opened.
Georg Brandl116aa622007-08-15 14:28:22 +0000718
Skip Montanaro1c639602007-09-23 19:49:54 +0000719 The most commonly-used values of *mode* are ``'r'`` for reading, ``'w'``
720 for writing (truncating the file if it already exists), and ``'a'`` for
721 appending (which on *some* Unix systems means that *all* writes append to
722 the end of the file regardless of the current seek position). If *mode*
Skip Montanaro4d8c1932007-09-23 21:13:45 +0000723 is omitted, it defaults to ``'r'``. See below for more possible values
724 of *mode*.
Skip Montanaro1c639602007-09-23 19:49:54 +0000725
Skip Montanaro4d8c1932007-09-23 21:13:45 +0000726 Python distinguishes between files opened in binary and text modes, even
727 when the underlying operating system doesn't. Files opened in binary
728 mode (appending ``'b'`` to the *mode* argument to :func:``open``) return
729 contents as bytes objects without any decoding. In text mode (the
730 default, or when ``'t'`` is appended to the *mode* argument) the contents
731 of the file are returned as strings, the bytes having been first decoded
732 using the encoding specified by :func:`sys.getfilesystemencoding`.
Georg Brandl116aa622007-08-15 14:28:22 +0000733
734 .. index::
735 single: line-buffered I/O
736 single: unbuffered I/O
737 single: buffer size, I/O
738 single: I/O control; buffering
Skip Montanaro4d8c1932007-09-23 21:13:45 +0000739 single: binary mode
740 single: text mode
741 module: sys
Georg Brandl116aa622007-08-15 14:28:22 +0000742
Skip Montanaro1c639602007-09-23 19:49:54 +0000743 The optional *bufsize* argument specifies the file's desired buffer size:
744 0 means unbuffered, 1 means line buffered, any other positive value means
745 use a buffer of (approximately) that size. A negative *bufsize* means to
746 use the system default, which is usually line buffered for tty devices
747 and fully buffered for other files. If omitted, the system default is
748 used. [#]_
Georg Brandl116aa622007-08-15 14:28:22 +0000749
Skip Montanaro1c639602007-09-23 19:49:54 +0000750 Modes ``'r+'``, ``'w+'`` and ``'a+'`` open the file for updating (note
Skip Montanaro4d8c1932007-09-23 21:13:45 +0000751 that ``'w+'`` truncates the file).
Georg Brandl116aa622007-08-15 14:28:22 +0000752
Skip Montanaro4d8c1932007-09-23 21:13:45 +0000753 When a file is opened in text mode it is also opened in universal
754 newlines mode. Unlike earlier versions of Python it's no longer
755 necessary to add a ``'U'`` value to the *mode* argument to enable this
756 mode. Consequently, in files opened in text mode lines may be terminated
757 with ``'\n'``, ``'\r'``, or ``'\r\n'``. All three external
758 representations are seen as ``'\n'`` by the Python program. File objects
759 opened in text mode also have a :attr:`newlines` attribute which has a
760 value of ``None`` (if no newlines have been seen yet), ``'\n'``,
Skip Montanaro1c639602007-09-23 19:49:54 +0000761 ``'\r'``, ``'\r\n'``, or a tuple containing all the newline types seen.
Georg Brandl116aa622007-08-15 14:28:22 +0000762
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000763 Python provides many file handling modules including
764 :mod:`fileinput`, :mod:`os`, :mod:`os.path`, :mod:`tempfile`, and
765 :mod:`shutil`.
Georg Brandl116aa622007-08-15 14:28:22 +0000766
767.. function:: ord(c)
768
769 Given a string of length one, return an integer representing the Unicode code
770 point of the character when the argument is a unicode object, or the value of
771 the byte when the argument is an 8-bit string. For example, ``ord('a')`` returns
772 the integer ``97``, ``ord(u'\u2020')`` returns ``8224``. This is the inverse of
773 :func:`chr` for 8-bit strings and of :func:`unichr` for unicode objects. If a
774 unicode argument is given and Python was built with UCS2 Unicode, then the
775 character's code point must be in the range [0..65535] inclusive; otherwise the
776 string length is two, and a :exc:`TypeError` will be raised.
777
778
779.. function:: pow(x, y[, z])
780
781 Return *x* to the power *y*; if *z* is present, return *x* to the power *y*,
782 modulo *z* (computed more efficiently than ``pow(x, y) % z``). The two-argument
783 form ``pow(x, y)`` is equivalent to using the power operator: ``x**y``.
784
785 The arguments must have numeric types. With mixed operand types, the coercion
Georg Brandlba956ae2007-11-29 17:24:34 +0000786 rules for binary arithmetic operators apply. For :class:`int` operands, the
Georg Brandl116aa622007-08-15 14:28:22 +0000787 result has the same type as the operands (after coercion) unless the second
788 argument is negative; in that case, all arguments are converted to float and a
789 float result is delivered. For example, ``10**2`` returns ``100``, but
790 ``10**-2`` returns ``0.01``. (This last feature was added in Python 2.2. In
791 Python 2.1 and before, if both arguments were of integer types and the second
792 argument was negative, an exception was raised.) If the second argument is
793 negative, the third argument must be omitted. If *z* is present, *x* and *y*
794 must be of integer types, and *y* must be non-negative. (This restriction was
795 added in Python 2.2. In Python 2.1 and before, floating 3-argument ``pow()``
796 returned platform-dependent results depending on floating-point rounding
797 accidents.)
798
799
800.. function:: property([fget[, fset[, fdel[, doc]]]])
801
Georg Brandl85eb8c12007-08-31 16:33:38 +0000802 Return a property attribute.
Georg Brandl116aa622007-08-15 14:28:22 +0000803
804 *fget* is a function for getting an attribute value, likewise *fset* is a
805 function for setting, and *fdel* a function for del'ing, an attribute. Typical
806 use is to define a managed attribute x::
807
808 class C(object):
809 def __init__(self): self._x = None
810 def getx(self): return self._x
811 def setx(self, value): self._x = value
812 def delx(self): del self._x
813 x = property(getx, setx, delx, "I'm the 'x' property.")
814
815 If given, *doc* will be the docstring of the property attribute. Otherwise, the
816 property will copy *fget*'s docstring (if it exists). This makes it possible to
817 create read-only properties easily using :func:`property` as a decorator::
818
819 class Parrot(object):
820 def __init__(self):
821 self._voltage = 100000
822
823 @property
824 def voltage(self):
825 """Get the current voltage."""
826 return self._voltage
827
828 turns the :meth:`voltage` method into a "getter" for a read-only attribute with
829 the same name.
830
Georg Brandl116aa622007-08-15 14:28:22 +0000831
Georg Brandl952aea22007-09-04 17:50:40 +0000832.. XXX does accept objects with __index__ too
Georg Brandl116aa622007-08-15 14:28:22 +0000833.. function:: range([start,] stop[, step])
834
Georg Brandl952aea22007-09-04 17:50:40 +0000835 This is a versatile function to create iterators containing arithmetic
Georg Brandl116aa622007-08-15 14:28:22 +0000836 progressions. It is most often used in :keyword:`for` loops. The arguments
Georg Brandl952aea22007-09-04 17:50:40 +0000837 must be integers. If the *step* argument is omitted, it defaults to ``1``.
838 If the *start* argument is omitted, it defaults to ``0``. The full form
839 returns an iterator of plain integers ``[start, start + step, start + 2 *
840 step, ...]``. If *step* is positive, the last element is the largest ``start
841 + i * step`` less than *stop*; if *step* is negative, the last element is the
842 smallest ``start + i * step`` greater than *stop*. *step* must not be zero
843 (or else :exc:`ValueError` is raised). Example::
Georg Brandl116aa622007-08-15 14:28:22 +0000844
845 >>> list(range(10))
846 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
847 >>> list(range(1, 11))
848 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
849 >>> list(range(0, 30, 5))
850 [0, 5, 10, 15, 20, 25]
851 >>> list(range(0, 10, 3))
852 [0, 3, 6, 9]
853 >>> list(range(0, -10, -1))
854 [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
855 >>> list(range(0))
856 []
857 >>> list(range(1, 0))
858 []
859
860
861.. function:: repr(object)
862
863 Return a string containing a printable representation of an object. This is the
864 same value yielded by conversions (reverse quotes). It is sometimes useful to be
865 able to access this operation as an ordinary function. For many types, this
866 function makes an attempt to return a string that would yield an object with the
867 same value when passed to :func:`eval`.
868
869
870.. function:: reversed(seq)
871
Georg Brandl9afde1c2007-11-01 20:32:30 +0000872 Return a reverse :term:`iterator`. *seq* must be an object which supports
873 the sequence protocol (the :meth:`__len__` method and the :meth:`__getitem__`
874 method with integer arguments starting at ``0``).
Georg Brandl116aa622007-08-15 14:28:22 +0000875
Georg Brandl116aa622007-08-15 14:28:22 +0000876
877.. function:: round(x[, n])
878
879 Return the floating point value *x* rounded to *n* digits after the decimal
880 point. If *n* is omitted, it defaults to zero. The result is a floating point
881 number. Values are rounded to the closest multiple of 10 to the power minus
882 *n*; if two multiples are equally close, rounding is done away from 0 (so. for
883 example, ``round(0.5)`` is ``1.0`` and ``round(-0.5)`` is ``-1.0``).
884
885
886.. function:: set([iterable])
887 :noindex:
888
889 Return a new set, optionally with elements are taken from *iterable*.
890 The set type is described in :ref:`types-set`.
891
892 For other containers see the built in :class:`dict`, :class:`list`, and
893 :class:`tuple` classes, and the :mod:`collections` module.
894
Georg Brandl116aa622007-08-15 14:28:22 +0000895
896.. function:: setattr(object, name, value)
897
898 This is the counterpart of :func:`getattr`. The arguments are an object, a
899 string and an arbitrary value. The string may name an existing attribute or a
900 new attribute. The function assigns the value to the attribute, provided the
901 object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to
902 ``x.foobar = 123``.
903
904
905.. function:: slice([start,] stop[, step])
906
907 .. index:: single: Numerical Python
908
909 Return a slice object representing the set of indices specified by
910 ``range(start, stop, step)``. The *start* and *step* arguments default to
911 ``None``. Slice objects have read-only data attributes :attr:`start`,
912 :attr:`stop` and :attr:`step` which merely return the argument values (or their
913 default). They have no other explicit functionality; however they are used by
914 Numerical Python and other third party extensions. Slice objects are also
915 generated when extended indexing syntax is used. For example:
916 ``a[start:stop:step]`` or ``a[start:stop, i]``.
917
918
919.. function:: sorted(iterable[, cmp[, key[, reverse]]])
920
921 Return a new sorted list from the items in *iterable*.
922
923 The optional arguments *cmp*, *key*, and *reverse* have the same meaning as
924 those for the :meth:`list.sort` method (described in section
925 :ref:`typesseq-mutable`).
926
927 *cmp* specifies a custom comparison function of two arguments (iterable
928 elements) which should return a negative, zero or positive number depending on
929 whether the first argument is considered smaller than, equal to, or larger than
930 the second argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``
931
932 *key* specifies a function of one argument that is used to extract a comparison
933 key from each list element: ``key=str.lower``
934
935 *reverse* is a boolean value. If set to ``True``, then the list elements are
936 sorted as if each comparison were reversed.
937
938 In general, the *key* and *reverse* conversion processes are much faster than
939 specifying an equivalent *cmp* function. This is because *cmp* is called
940 multiple times for each list element while *key* and *reverse* touch each
941 element only once.
942
Georg Brandl116aa622007-08-15 14:28:22 +0000943
944.. function:: staticmethod(function)
945
946 Return a static method for *function*.
947
948 A static method does not receive an implicit first argument. To declare a static
949 method, use this idiom::
950
951 class C:
952 @staticmethod
953 def f(arg1, arg2, ...): ...
954
955 The ``@staticmethod`` form is a function decorator -- see the description of
956 function definitions in :ref:`function` for details.
957
958 It can be called either on the class (such as ``C.f()``) or on an instance (such
959 as ``C().f()``). The instance is ignored except for its class.
960
961 Static methods in Python are similar to those found in Java or C++. For a more
962 advanced concept, see :func:`classmethod` in this section.
963
964 For more information on static methods, consult the documentation on the
965 standard type hierarchy in :ref:`types`.
966
Georg Brandl116aa622007-08-15 14:28:22 +0000967
968.. function:: str([object[, encoding[, errors]]])
969
970 Return a string version of an object, using one of the following modes:
971
972 If *encoding* and/or *errors* are given, :func:`str` will decode the
973 *object* which can either be a byte string or a character buffer using
974 the codec for *encoding*. The *encoding* parameter is a string giving
975 the name of an encoding; if the encoding is not known, :exc:`LookupError`
976 is raised. Error handling is done according to *errors*; this specifies the
977 treatment of characters which are invalid in the input encoding. If
978 *errors* is ``'strict'`` (the default), a :exc:`ValueError` is raised on
979 errors, while a value of ``'ignore'`` causes errors to be silently ignored,
980 and a value of ``'replace'`` causes the official Unicode replacement character,
981 U+FFFD, to be used to replace input characters which cannot be decoded.
982 See also the :mod:`codecs` module.
983
984 When only *object* is given, this returns its nicely printable representation.
985 For strings, this is the string itself. The difference with ``repr(object)``
986 is that ``str(object)`` does not always attempt to return a string that is
987 acceptable to :func:`eval`; its goal is to return a printable string.
988 With no arguments, this returns the empty string.
989
990 Objects can specify what ``str(object)`` returns by defining a :meth:`__str__`
991 special method.
992
993 For more information on strings see :ref:`typesseq` which describes sequence
994 functionality (strings are sequences), and also the string-specific methods
Georg Brandl4b491312007-08-31 09:22:56 +0000995 described in the :ref:`string-methods` section. To output formatted strings,
996 see the :ref:`string-formatting` section. In addition see the
997 :ref:`stringservices` section.
Georg Brandl116aa622007-08-15 14:28:22 +0000998
999
1000.. function:: sum(iterable[, start])
1001
1002 Sums *start* and the items of an *iterable* from left to right and returns the
1003 total. *start* defaults to ``0``. The *iterable*'s items are normally numbers,
1004 and are not allowed to be strings. The fast, correct way to concatenate a
1005 sequence of strings is by calling ``''.join(sequence)``.
1006
Georg Brandl116aa622007-08-15 14:28:22 +00001007
1008.. function:: super(type[, object-or-type])
1009
Georg Brandl85eb8c12007-08-31 16:33:38 +00001010 .. XXX need to document PEP "new super"
1011
Georg Brandl116aa622007-08-15 14:28:22 +00001012 Return the superclass of *type*. If the second argument is omitted the super
1013 object returned is unbound. If the second argument is an object,
1014 ``isinstance(obj, type)`` must be true. If the second argument is a type,
Georg Brandl85eb8c12007-08-31 16:33:38 +00001015 ``issubclass(type2, type)`` must be true.
Georg Brandl116aa622007-08-15 14:28:22 +00001016
1017 A typical use for calling a cooperative superclass method is::
1018
1019 class C(B):
1020 def meth(self, arg):
1021 super(C, self).meth(arg)
1022
1023 Note that :func:`super` is implemented as part of the binding process for
1024 explicit dotted attribute lookups such as ``super(C, self).__getitem__(name)``.
1025 Accordingly, :func:`super` is undefined for implicit lookups using statements or
1026 operators such as ``super(C, self)[name]``.
1027
Georg Brandl116aa622007-08-15 14:28:22 +00001028
1029.. function:: tuple([iterable])
1030
1031 Return a tuple whose items are the same and in the same order as *iterable*'s
1032 items. *iterable* may be a sequence, a container that supports iteration, or an
1033 iterator object. If *iterable* is already a tuple, it is returned unchanged.
1034 For instance, ``tuple('abc')`` returns ``('a', 'b', 'c')`` and ``tuple([1, 2,
1035 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty
1036 tuple, ``()``.
1037
1038 :class:`tuple` is an immutable sequence type, as documented in
1039 :ref:`typesseq`. For other containers see the built in :class:`dict`,
1040 :class:`list`, and :class:`set` classes, and the :mod:`collections` module.
1041
1042
1043.. function:: type(object)
1044
1045 .. index:: object: type
1046
Georg Brandl85eb8c12007-08-31 16:33:38 +00001047 Return the type of an *object*. The return value is a type object and
1048 generally the same object as returned by ``object.__class__``.
Georg Brandl116aa622007-08-15 14:28:22 +00001049
Georg Brandl85eb8c12007-08-31 16:33:38 +00001050 The :func:`isinstance` built-in function is recommended for testing the type
1051 of an object, because it takes subclasses into account.
1052
1053 With three arguments, :func:`type` functions as a constructor as detailed
1054 below.
Georg Brandl116aa622007-08-15 14:28:22 +00001055
1056
1057.. function:: type(name, bases, dict)
1058 :noindex:
1059
1060 Return a new type object. This is essentially a dynamic form of the
Georg Brandl85eb8c12007-08-31 16:33:38 +00001061 :keyword:`class` statement. The *name* string is the class name and becomes
1062 the :attr:`__name__` attribute; the *bases* tuple itemizes the base classes
1063 and becomes the :attr:`__bases__` attribute; and the *dict* dictionary is the
1064 namespace containing definitions for class body and becomes the
1065 :attr:`__dict__` attribute. For example, the following two statements create
1066 identical :class:`type` objects::
Georg Brandl116aa622007-08-15 14:28:22 +00001067
1068 >>> class X(object):
1069 ... a = 1
1070 ...
1071 >>> X = type('X', (object,), dict(a=1))
1072
Georg Brandl116aa622007-08-15 14:28:22 +00001073
1074.. function:: vars([object])
1075
1076 Without arguments, return a dictionary corresponding to the current local symbol
1077 table. With a module, class or class instance object as argument (or anything
1078 else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
1079 to the object's symbol table. The returned dictionary should not be modified:
1080 the effects on the corresponding symbol table are undefined. [#]_
1081
1082
1083.. function:: zip([iterable, ...])
1084
Georg Brandl952aea22007-09-04 17:50:40 +00001085 This function returns an iterator of tuples, where the *i*-th tuple contains
1086 the *i*-th element from each of the argument sequences or iterables. The
1087 iterator stops when the shortest argument sequence is exhausted. When there
1088 are multiple arguments which are all of the same length, :func:`zip` is
1089 similar to :func:`map` with an initial argument of ``None``. With a single
1090 sequence argument, it returns an iterator of 1-tuples. With no arguments, it
1091 returns an empty iterator.
Georg Brandl116aa622007-08-15 14:28:22 +00001092
Georg Brandl116aa622007-08-15 14:28:22 +00001093
Georg Brandl116aa622007-08-15 14:28:22 +00001094.. rubric:: Footnotes
1095
1096.. [#] Specifying a buffer size currently has no effect on systems that don't have
1097 :cfunc:`setvbuf`. The interface to specify the buffer size is not done using a
1098 method that calls :cfunc:`setvbuf`, because that may dump core when called after
1099 any I/O has been performed, and there's no reliable way to determine whether
1100 this is the case.
1101
1102.. [#] In the current implementation, local variable bindings cannot normally be
1103 affected this way, but variables retrieved from other scopes (such as modules)
1104 can be. This may change.
1105