GNU Info
(python2.1-ref.info)standard type hierarchy
The standard type hierarchy
===========================
Below is a list of the types that are built into Python. Extension
modules written in C can define additional types. Future versions of
Python may add types to the type hierarchy (e.g., rational numbers,
efficiently stored arrays of integers, etc.).
Some of the type descriptions below contain a paragraph listing
`special attributes.' These are attributes that provide access to the
implementation and are not intended for general use. Their definition
may change in the future. There are also some `generic' special
attributes, not listed with the individual objects: `__methods__' is a
list of the method names of a built-in object, if it has any;
`__members__' is a list of the data attribute names of a built-in
object, if it has any.
`None'
This type has a single value. There is a single object with this
value. This object is accessed through the built-in name `None'.
It is used to signify the absence of a value in many situations,
e.g., it is returned from functions that don't explicitly return
anything. Its truth value is false.
`NotImplemented'
This type has a single value. There is a single object with this
value. This object is accessed through the built-in name
`NotImplemented'. Numeric methods and rich comparison methods may
return this value if they do not implement the operation for the
operands provided. (The interpreter will then try the reflected
operation, or some other fallback, depending on the operator.)
Its truth value is true.
`Ellipsis'
This type has a single value. There is a single object with this
value. This object is accessed through the built-in name
`Ellipsis'. It is used to indicate the presence of the `...'
syntax in a slice. Its truth value is true.
`Numbers'
These are created by numeric literals and returned as results by
arithmetic operators and arithmetic built-in functions. Numeric
objects are immutable; once created their value never changes.
Python numbers are of course strongly related to mathematical
numbers, but subject to the limitations of numerical
representation in computers.
Python distinguishes between integers, floating point numbers, and
complex numbers:
`Integers'
These represent elements from the mathematical set of whole
numbers.
There are two types of integers:
`Plain integers'
These represent numbers in the range -2147483648 through
2147483647. (The range may be larger on machines with a
larger natural word size, but not smaller.) When the
result of an operation would fall outside this range, the
exception `OverflowError' is raised. For the purpose of
shift and mask operations, integers are assumed to have
a binary, 2's complement notation using 32 or more bits,
and hiding no bits from the user (i.e., all 4294967296
different bit patterns correspond to different values).
`Long integers'
These represent numbers in an unlimited range, subject
to available (virtual) memory only. For the purpose of
shift and mask operations, a binary representation is
assumed, and negative numbers are represented in a
variant of 2's complement which gives the illusion of an
infinite string of sign bits extending to the left.
The rules for integer representation are intended to give the
most meaningful interpretation of shift and mask operations
involving negative integers and the least surprises when
switching between the plain and long integer domains. For
any operation except left shift, if it yields a result in the
plain integer domain without causing overflow, it will yield
the same result in the long integer domain or when using
mixed operands.
`Floating point numbers'
These represent machine-level double precision floating point
numbers. You are at the mercy of the underlying machine
architecture and C implementation for the accepted range and
handling of overflow. Python does not support
single-precision floating point numbers; the savings in CPU
and memory usage that are usually the reason for using these
is dwarfed by the overhead of using objects in Python, so
there is no reason to complicate the language with two kinds
of floating point numbers.
`Complex numbers'
These represent complex numbers as a pair of machine-level
double precision floating point numbers. The same caveats
apply as for floating point numbers. The real and imaginary
value of a complex number `z' can be retrieved through the
attributes `z.real' and `z.imag'.
`Sequences'
These represent finite ordered sets indexed by non-negative
numbers. The built-in function `len()' returns the number of
items of a sequence. When the length of a sequence is N, the
index set contains the numbers 0, 1, ..., N-1. Item I of sequence
A is selected by `A[I]'.
Sequences also support slicing: `A[I:J]' selects all items with
index K such that I `<=' K `<' J. When used as an expression, a
slice is a sequence of the same type. This implies that the index
set is renumbered so that it starts at 0.
Sequences are distinguished according to their mutability:
`Immutable sequences'
An object of an immutable sequence type cannot change once it
is created. (If the object contains references to other
objects, these other objects may be mutable and may be
changed; however, the collection of objects directly
referenced by an immutable object cannot change.)
The following types are immutable sequences:
`Strings'
The items of a string are characters. There is no
separate character type; a character is represented by a
string of one item. Characters represent (at least)
8-bit bytes. The built-in functions `chr()' and `ord()'
convert between characters and nonnegative integers
representing the byte values. Bytes with the values
0-127 usually represent the corresponding ASCII values,
but the interpretation of values is up to the program.
The string data type is also used to represent arrays of
bytes, e.g., to hold data read from a file.
(On systems whose native character set is not ASCII,
strings may use EBCDIC in their internal representation,
provided the functions `chr()' and `ord()' implement a
mapping between ASCII and EBCDIC, and string comparison
preserves the ASCII order. Or perhaps someone can
propose a better rule?)
`Unicode'
The items of a Unicode object are Unicode characters. A
Unicode character is represented by a Unicode object of
one item and can hold a 16-bit value representing a
Unicode ordinal. The built-in functions `unichr()' and
`ord()' convert between characters and nonnegative
integers representing the Unicode ordinals as defined in
the Unicode Standard 3.0. Conversion from and to other
encodings are possible through the Unicode method
`encode' and the built-in function `unicode()' .
`Tuples'
The items of a tuple are arbitrary Python objects.
Tuples of two or more items are formed by
comma-separated lists of expressions. A tuple of one
item (a `singleton') can be formed by affixing a comma
to an expression (an expression by itself does not
create a tuple, since parentheses must be usable for
grouping of expressions). An empty tuple can be formed
by an empty pair of parentheses.
`Mutable sequences'
Mutable sequences can be changed after they are created. The
subscription and slicing notations can be used as the target
of assignment and `del' (delete) statements.
There is currently a single mutable sequence type:
`Lists'
The items of a list are arbitrary Python objects. Lists
are formed by placing a comma-separated list of
expressions in square brackets. (Note that there are no
special cases needed to form lists of length 0 or 1.)
The extension module `array' provides an additional example
of a mutable sequence type.
`Mappings'
These represent finite sets of objects indexed by arbitrary index
sets. The subscript notation `a[k]' selects the item indexed by
`k' from the mapping `a'; this can be used in expressions and as
the target of assignments or `del' statements. The built-in
function `len()' returns the number of items in a mapping.
There is currently a single intrinsic mapping type:
`Dictionaries'
These represent finite sets of objects indexed by nearly
arbitrary values. The only types of values not acceptable as
keys are values containing lists or dictionaries or other
mutable types that are compared by value rather than by
object identity, the reason being that the efficient
implementation of dictionaries requires a key's hash value to
remain constant. Numeric types used for keys obey the normal
rules for numeric comparison: if two numbers compare equal
(e.g., `1' and `1.0') then they can be used interchangeably
to index the same dictionary entry.
Dictionaries are mutable; they are created by the `{...}'
notation (see section Note: Dictionary displays, "Dictionary
Displays").
The extension modules `dbm' , `gdbm' , `bsddb' provide
additional examples of mapping types.
`Callable types'
These are the types to which the function call operation (see
section Note: Calls, "Calls") can be applied:
`User-defined functions'
A user-defined function object is created by a function
definition (see section Note: Function definitions,
"Function definitions"). It should be called with an argument
list containing the same number of items as the function's
formal parameter list.
Special attributes: `func_doc' or `__doc__' is the function's
documentation string, or None if unavailable; `func_name' or
`__name__' is the function's name; `func_defaults' is a tuple
containing default argument values for those arguments that
have defaults, or `None' if no arguments have a default
value; `func_code' is the code object representing the
compiled function body; `func_globals' is (a reference to)
the dictionary that holds the function's global variables --
it defines the global namespace of the module in which the
function was defined; `func_dict' or `__dict__' contains the
namespace supporting arbitrary function attributes;
`func_closure' is `None' or a tuple of cells that contain
binding for the function's free variables.
Of these, `func_code', `func_defaults', `func_closure',
`func_doc'/`__doc__', and `func_dict'/`__dict__' may be
writable; the others can never be changed. Additional
information about a function's definition can be retrieved
from its code object; see the description of internal types
below.
In Python 2.1, the `func_closure' slot is always `None'
unless nested scopes are enabled. (See the appendix.)
`User-defined methods'
A user-defined method object combines a class, a class
instance (or `None') and a user-defined function.
Special read-only attributes: `im_self' is the class instance
object, `im_func' is the function object; `im_class' is the
class that defined the method (which may be a base class of
the class of which `im_self' is an instance); `__doc__' is
the method's documentation (same as `im_func.__doc__');
`__name__' is the method name (same as `im_func.__name__').
Methods also support accessing (but not setting) the arbitrary
function attributes on the underlying function object.
User-defined method objects are created in two ways: when
getting an attribute of a class that is a user-defined
function object, or when getting an attribute of a class
instance that is a user-defined function object defined by
the class of the instance. In the former case (class
attribute), the `im_self' attribute is `None', and the method
object is said to be unbound; in the latter case (instance
attribute), `im_self' is the instance, and the method object
is said to be bound. For instance, when `C' is a class which
contains a definition for a function `f()', `C.f' does not
yield the function object `f'; rather, it yields an unbound
method object `m' where `m.im_class' is `C', `m.im_func' is
`f()', and `m.im_self' is `None'. When `x' is a `C'
instance, `x.f' yields a bound method object `m' where
`m.im_class' is `C', `m.im_func' is `f()', and `m.im_self' is
`x'.
When an unbound user-defined method object is called, the
underlying function (`im_func') is called, with the
restriction that the first argument must be an instance of
the proper class (`im_class') or of a derived class thereof.
When a bound user-defined method object is called, the
underlying function (`im_func') is called, inserting the
class instance (`im_self') in front of the argument list.
For instance, when `C' is a class which contains a definition
for a function `f()', and `x' is an instance of `C', calling
`x.f(1)' is equivalent to calling `C.f(x, 1)'.
Note that the transformation from function object to (unbound
or bound) method object happens each time the attribute is
retrieved from the class or instance. In some cases, a
fruitful optimization is to assign the attribute to a local
variable and call that local variable. Also notice that this
transformation only happens for user-defined functions; other
callable objects (and all non-callable objects) are retrieved
without transformation. It is also important to note that
user-defined functions which are attributes of a class
instance are not converted to bound methods; this _only_
happens when the function is an attribute of the class.
`Built-in functions'
A built-in function object is a wrapper around a C function.
Examples of built-in functions are `len()' and `math.sin()'
(`math' is a standard built-in module). The number and type
of the arguments are determined by the C function. Special
read-only attributes: `__doc__' is the function's
documentation string, or `None' if unavailable; `__name__' is
the function's name; `__self__' is set to `None' (but see the
next item).
`Built-in methods'
This is really a different disguise of a built-in function,
this time containing an object passed to the C function as an
implicit extra argument. An example of a built-in method is
`LIST.append()', assuming LIST is a list object. In this
case, the special read-only attribute `__self__' is set to
the object denoted by `list'.
`Classes'
Class objects are described below. When a class object is
called, a new class instance (also described below) is
created and returned. This implies a call to the class's
`__init__()' method if it has one. Any arguments are passed
on to the `__init__()' method. If there is no `__init__()'
method, the class must be called without arguments.
`Class instances'
Class instances are described below. Class instances are
callable only when the class has a `__call__()' method;
`x(arguments)' is a shorthand for `x.__call__(arguments)'.
`Modules'
Modules are imported by the `import' statement (see section Note:
import statement, "The `import' statement"). A module object
has a namespace implemented by a dictionary object (this is the
dictionary referenced by the func_globals attribute of functions
defined in the module). Attribute references are translated to
lookups in this dictionary, e.g., `m.x' is equivalent to
`m.__dict__["x"]'. A module object does not contain the code
object used to initialize the module (since it isn't needed once
the initialization is done).
Attribute assignment updates the module's namespace dictionary,
e.g., `m.x = 1' is equivalent to `m.__dict__["x"] = 1'.
Special read-only attribute: `__dict__' is the module's namespace
as a dictionary object.
Predefined (writable) attributes: `__name__' is the module's name;
`__doc__' is the module's documentation string, or `None' if
unavailable; `__file__' is the pathname of the file from which the
module was loaded, if it was loaded from a file. The `__file__'
attribute is not present for C{} modules that are statically
linked into the interpreter; for extension modules loaded
dynamically from a shared library, it is the pathname of the shared
library file.
`Classes'
Class objects are created by class definitions (see section Note:
Class definitions, "Class definitions"). A class has a
namespace implemented by a dictionary object. Class attribute
references are translated to lookups in this dictionary, e.g.,
`C.x' is translated to `C.__dict__["x"]'. When the attribute name
is not found there, the attribute search continues in the base
classes. The search is depth-first, left-to-right in the order of
occurrence in the base class list. When a class attribute
reference would yield a user-defined function object, it is
transformed into an unbound user-defined method object (see
above). The `im_class' attribute of this method object is the
class in which the function object was found, not necessarily the
class for which the attribute reference was initiated.
Class attribute assignments update the class's dictionary, never
the dictionary of a base class.
A class object can be called (see above) to yield a class instance
(see below).
Special attributes: `__name__' is the class name; `__module__' is
the module name in which the class was defined; `__dict__' is the
dictionary containing the class's namespace; `__bases__' is a
tuple (possibly empty or a singleton) containing the base classes,
in the order of their occurrence in the base class list; `__doc__'
is the class's documentation string, or None if undefined.
`Class instances'
A class instance is created by calling a class object (see above).
A class instance has a namespace implemented as a dictionary which
is the first place in which attribute references are searched.
When an attribute is not found there, and the instance's class has
an attribute by that name, the search continues with the class
attributes. If a class attribute is found that is a user-defined
function object (and in no other case), it is transformed into an
unbound user-defined method object (see above). The `im_class'
attribute of this method object is the class in which the function
object was found, not necessarily the class of the instance for
which the attribute reference was initiated. If no class
attribute is found, and the object's class has a `__getattr__()'
method, that is called to satisfy the lookup.
Attribute assignments and deletions update the instance's
dictionary, never a class's dictionary. If the class has a
`__setattr__()' or `__delattr__()' method, this is called instead
of updating the instance dictionary directly.
Class instances can pretend to be numbers, sequences, or mappings
if they have methods with certain special names. See section
Note: Special method names, "Special method names."
Special attributes: `__dict__' is the attribute dictionary;
`__class__' is the instance's class.
`Files'
A file object represents an open file. File objects are created
by the `open()' built-in function, and also by `os.popen()',
`os.fdopen()', and the `makefile()' method of socket objects (and
perhaps by other functions or methods provided by extension
modules). The objects `sys.stdin', `sys.stdout' and `sys.stderr'
are initialized to file objects corresponding to the interpreter's
standard input, output and error streams. See the for complete
documentation of file objects.
`Internal types'
A few types used internally by the interpreter are exposed to the
user. Their definitions may change with future versions of the
interpreter, but they are mentioned here for completeness.
`Code objects'
Code objects represent _byte-compiled_ executable Python
code, or _bytecode_. The difference between a code object
and a function object is that the function object contains an
explicit reference to the function's globals (the module in
which it was defined), while a code object contains no
context; also the default argument values are stored in the
function object, not in the code object (because they
represent values calculated at run-time). Unlike function
objects, code objects are immutable and contain no references
(directly or indirectly) to mutable objects.
Special read-only attributes: `co_name' gives the function
name; `co_argcount' is the number of positional arguments
(including arguments with default values); `co_nlocals' is the
number of local variables used by the function (including
arguments); `co_varnames' is a tuple containing the names of
the local variables (starting with the argument names);
`co_cellvars' is a tuple containing the names of local
variables that are referenced by nested functions;
`co_freevars' is a tuple containing the names of local
variables that are neither local nor global; `co_code' is a
string representing the sequence of bytecode instructions;
`co_consts' is a tuple containing the literals used by the
bytecode; `co_names' is a tuple containing the names used by
the bytecode; `co_filename' is the filename from which the
code was compiled; `co_firstlineno' is the first line number
of the function; `co_lnotab' is a string encoding the mapping
from byte code offsets to line numbers (for details see the
source code of the interpreter); `co_stacksize' is the
required stack size (including local variables); `co_flags'
is an integer encoding a number of flags for the interpreter.
The `co_cellvars' and `co_freevars' are present in Python 2.1
when nested scopes are not enabled, but the code itself does
not use or create cells.
The following flag bits are defined for `co_flags': bit
`0x04' is set if the function uses the `*arguments' syntax to
accept an arbitrary number of positional arguments; bit
`0x08' is set if the function uses the `**keywords' syntax to
accept arbitrary keyword arguments; other bits are used
internally or reserved for future use; bit `0x10' is set if
the function was compiled with nested scopes enabled. If a
code object represents a function, the first item in
`co_consts' is the documentation string of the function, or
`None' if undefined.
`Frame objects'
Frame objects represent execution frames. They may occur in
traceback objects (see below).
Special read-only attributes: `f_back' is to the previous
stack frame (towards the caller), or `None' if this is the
bottom stack frame; `f_code' is the code object being
executed in this frame; `f_locals' is the dictionary used to
look up local variables; `f_globals' is used for global
variables; `f_builtins' is used for built-in (intrinsic)
names; `f_restricted' is a flag indicating whether the
function is executing in restricted execution mode;
`f_lineno' gives the line number and `f_lasti' gives the
precise instruction (this is an index into the bytecode
string of the code object).
Special writable attributes: `f_trace', if not `None', is a
function called at the start of each source code line (this
is used by the debugger); `f_exc_type', `f_exc_value',
`f_exc_traceback' represent the most recent exception caught
in this frame.
`Traceback objects'
Traceback objects represent a stack trace of an exception. A
traceback object is created when an exception occurs. When
the search for an exception handler unwinds the execution
stack, at each unwound level a traceback object is inserted
in front of the current traceback. When an exception handler
is entered, the stack trace is made available to the program.
(See section Note: try statement, "The `try' statement.")
It is accessible as `sys.exc_traceback', and also as the third
item of the tuple returned by `sys.exc_info()'. The latter is
the preferred interface, since it works correctly when the
program is using multiple threads. When the program contains
no suitable handler, the stack trace is written (nicely
formatted) to the standard error stream; if the interpreter is
interactive, it is also made available to the user as
`sys.last_traceback'.
Special read-only attributes: `tb_next' is the next level in
the stack trace (towards the frame where the exception
occurred), or `None' if there is no next level; `tb_frame'
points to the execution frame of the current level;
`tb_lineno' gives the line number where the exception
occurred; `tb_lasti' indicates the precise instruction. The
line number and last instruction in the traceback may differ
from the line number of its frame object if the exception
occurred in a `try' statement with no matching except clause
or with a finally clause.
`Slice objects'
Slice objects are used to represent slices when _extended
slice syntax_ is used. This is a slice using two colons, or
multiple slices or ellipses separated by commas, e.g.,
`a[i:j:step]', `a[i:j, k:l]', or `a[..., i:j])'. They are
also created by the built-in `slice()' function.
Special read-only attributes: `start' is the lower bound;
`stop' is the upper bound; `step' is the step value; each is
`None' if omitted. These attributes can have any type.
automatically generated by info2www version 1.2.2.9