This is /home/pdm/install/Python-2.1/Doc/lib/python-lib.info, produced by makeinfo version 4.0 from lib.texi. April 15, 2001 2.1  File: python-lib.info, Node: Top, Next: Front Matter, Prev: (dir), Up: (dir) Python Library Reference ************************ * Menu: * Front Matter:: * Introduction:: * Built-in Objects:: * Python Runtime Services:: * String Services:: * Miscellaneous Services:: * Generic Operating System Services:: * Optional Operating System Services:: * Unix Specific Services:: * Python Debugger:: * Python Profiler:: * Internet Protocols and Support:: * Internet Data Handling:: * Structured Markup Processing Tools:: * Multimedia Services:: * Cryptographic Services:: * Restricted Execution:: * Python Language Services:: * SGI IRIX Specific Services:: * SunOS Specific Services:: * MS Windows Specific Services:: * Undocumented Modules:: * Reporting Bugs:: * Module Index:: * Class-Exception-Object Index:: * Function-Method-Variable Index:: * Miscellaneous Index::  File: python-lib.info, Node: Front Matter, Next: Introduction, Prev: Top, Up: Top Front Matter ************ Copyright (C) 2001 Python Software Foundation. All rights reserved. Copyright (C) 2000 BeOpen.com. All rights reserved. Copyright (C) 1995-2000 Corporation for National Research Initiatives. All rights reserved. Copyright (C) 1991-1995 Stichting Mathematisch Centrum. All rights reserved. *BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1* 1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization ("Licensee") accessing and otherwise using this software in source or binary form and its associated documentation ("the Software"). 2. Subject to the terms and conditions of this BeOpen Python License Agreement, BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use the Software alone or in any derivative version, provided, however, that the BeOpen Python License is retained in the Software, alone or in any derivative version prepared by Licensee. 3. BeOpen is making the Software available to Licensee on an "AS IS" basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. 4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. 5. This License Agreement will automatically terminate upon a material breach of its terms and conditions. 6. This License Agreement shall be governed by and interpreted in all respects by the law of the State of California, excluding conflict of law provisions. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between BeOpen and Licensee. This License Agreement does not grant permission to use BeOpen trademarks or trade names in a trademark sense to endorse or promote products or services of Licensee, or any third party. As an exception, the "BeOpen Python" logos available at http://www.pythonlabs.com/logos.html may be used according to the permissions granted on that web page. 7. By copying, installing or otherwise using the software, Licensee agrees to be bound by the terms and conditions of this License Agreement. *CNRI OPEN SOURCE GPL-COMPATIBLE LICENSE AGREEMENT* Python 1.6.1 is made available subject to the terms and conditions in CNRI's License Agreement. This Agreement together with Python 1.6.1 may be located on the Internet using the following unique, persistent identifier (known as a handle): 1895.22/1013. This Agreement may also be obtained from a proxy server on the Internet using the following URL: . *CWI PERMISSIONS STATEMENT AND DISCLAIMER* Copyright (C) 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The Netherlands. All rights reserved. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Stichting Mathematisch Centrum or CWI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Python is an extensible, interpreted, object-oriented programming language. It supports a wide range of applications, from simple text processing scripts to interactive WWW browsers. While the describes the exact syntax and semantics of the language, it does not describe the standard library that is distributed with the language, and which greatly enhances its immediate usability. This library contains built-in modules (written in C) that provide access to system functionality such as file I/O that would otherwise be inaccessible to Python programmers, as well as modules written in Python that provide standardized solutions for many problems that occur in everyday programming. Some of these modules are explicitly designed to encourage and enhance the portability of Python programs. This library reference manual documents Python's standard library, as well as many optional library modules (which may or may not be available, depending on whether the underlying platform supports them and on the configuration choices made at compile time). It also documents the standard types of the language and its built-in functions and exceptions, many of which are not or incompletely documented in the Reference Manual. This manual assumes basic knowledge about the Python language. For an informal introduction to Python, see the ; the remains the highest authority on syntactic and semantic questions. Finally, the manual entitled describes how to add new extensions to Python and how to embed it in other applications.  File: python-lib.info, Node: Introduction, Next: Built-in Objects, Prev: Front Matter, Up: Top Introduction ************ The "Python library" contains several different kinds of components. It contains data types that would normally be considered part of the "core" of a language, such as numbers and lists. For these types, the Python language core defines the form of literals and places some constraints on their semantics, but does not fully define the semantics. (On the other hand, the language core does define syntactic properties like the spelling and priorities of operators.) The library also contains built-in functions and exceptions -- objects that can be used by all Python code without the need of an `import' statement. Some of these are defined by the core language, but many are not essential for the core semantics and are only described here. The bulk of the library, however, consists of a collection of modules. There are many ways to dissect this collection. Some modules are written in C and built in to the Python interpreter; others are written in Python and imported in source form. Some modules provide interfaces that are highly specific to Python, like printing a stack trace; some provide interfaces that are specific to particular operating systems, such as access to specific hardware; others provide interfaces that are specific to a particular application domain, like the World-Wide Web. Some modules are available in all versions and ports of Python; others are only available when the underlying system supports or requires them; yet others are available only when a particular configuration option was chosen at the time when Python was compiled and installed. This manual is organized "from the inside out:" it first describes the built-in data types, then the built-in functions and exceptions, and finally the modules, grouped in chapters of related modules. The ordering of the chapters as well as the ordering of the modules within each chapter is roughly from most relevant to least important. This means that if you start reading this manual from the start, and skip to the next chapter when you get bored, you will get a reasonable overview of the available modules and application areas that are supported by the Python library. Of course, you don't _have_ to read it like a novel -- you can also browse the table of contents (in front of the manual), or look for a specific function, module or term in the index (in the back). And finally, if you enjoy learning about random subjects, you choose a random page number (see module `random') and read a section or two. Regardless of the order in which you read the sections of this manual, it helps to start with chapter *Note Built-in Objects::, "Built-in Types, Exceptions and Functions," as the remainder of the manual assumes familiarity with this material. Let the show begin!  File: python-lib.info, Node: Built-in Objects, Next: Python Runtime Services, Prev: Introduction, Up: Top Built-in Types, Exceptions and Functions **************************************** Names for built-in exceptions and functions are found in a separate symbol table. This table is searched last when the interpreter looks up the meaning of a name, so local and global user-defined names can override built-in names. Built-in types are described together here for easy reference.(1) The tables in this chapter document the priorities of operators by listing them in order of ascending priority (within a table) and grouping operators that have the same priority in the same box. Binary operators of the same priority group from left to right. (Unary operators group from right to left, but there you have no real choice.) See chapter 5 of the for the complete picture on operator priorities. * Menu: * Built-in Types:: * Built-in Exceptions:: * Built-in Functions:: ---------- Footnotes ---------- (1) Most descriptions sorely lack explanations of the exceptions that may be raised -- this will be fixed in a future version of this manual.  File: python-lib.info, Node: Built-in Types, Next: Built-in Exceptions, Prev: Built-in Objects, Up: Built-in Objects Built-in Types ============== The following sections describe the standard types that are built into the interpreter. These are the numeric types, sequence types, and several others, including types themselves. There is no explicit Boolean type; use integers instead. Some operations are supported by several object types; in particular, all objects can be compared, tested for truth value, and converted to a string (with the ``...`' notation). The latter conversion is implicitly used when an object is written by the `print' statement. * Menu: * Truth Value Testing:: * Boolean Operations:: * Comparisons:: * Numeric Types:: * Sequence Types:: * Mapping Types:: * Other Built-in Types:: * Special Attributes::  File: python-lib.info, Node: Truth Value Testing, Next: Boolean Operations, Prev: Built-in Types, Up: Built-in Types Truth Value Testing ------------------- Any object can be tested for truth value, for use in an `if' or `while' condition or as operand of the Boolean operations below. The following values are considered false: * `None' * zero of any numeric type, for example, `0', `0L', `0.0', `0j'. * any empty sequence, for example, `''', `()', `[]'. * any empty mapping, for example, `{}'. * instances of user-defined classes, if the class defines a `__nonzero__()' or `__len__()' method, when that method returns zero.(1) All other values are considered true -- so objects of many types are always true. Operations and built-in functions that have a Boolean result always return `0' for false and `1' for true, unless otherwise stated. (Important exception: the Boolean operations `or' and `and' always return one of their operands.) ---------- Footnotes ---------- (1) Additional information on these special methods may be found in the .  File: python-lib.info, Node: Boolean Operations, Next: Comparisons, Prev: Truth Value Testing, Up: Built-in Types Boolean Operations ------------------ These are the Boolean operations, ordered by ascending priority: Operation Result Notes ------ ----- ----- X or Y if X is false, then Y, (1) else X X and Y if X is false, then X, (1) else Y not X if X is false, then (2) `1', else `0' Notes: `(1)' These only evaluate their second argument if needed for their outcome. `(2)' `not' has a lower priority than non-Boolean operators, so `not A == B' is interpreted as `not (A == B)', and `A == not B' is a syntax error.  File: python-lib.info, Node: Comparisons, Next: Numeric Types, Prev: Boolean Operations, Up: Built-in Types Comparisons ----------- Comparison operations are supported by all objects. They all have the same priority (which is higher than that of the Boolean operations). Comparisons can be chained arbitrarily; for example, `X < Y <= Z' is equivalent to `X < Y and Y <= Z', except that Y is evaluated only once (but in both cases Z is not evaluated at all when `X < Y' is found to be false). This table summarizes the comparison operations: Operation Meaning Notes ------ ----- ----- < strictly less than <= less than or equal > strictly greater than >= greater than or equal == equal != not equal (1) <> not equal (1) is object identity is not negated object identity Notes: `(1)' `<>' and `!=' are alternate spellings for the same operator. (I couldn't choose between ABC and C! :-) `!=' is the preferred spelling; `<>' is obsolescent. Objects of different types, except different numeric types, never compare equal; such objects are ordered consistently but arbitrarily (so that sorting a heterogeneous array yields a consistent result). Furthermore, some types (for example, file objects) support only a degenerate notion of comparison where any two objects of that type are unequal. Again, such objects are ordered arbitrarily but consistently. Instances of a class normally compare as non-equal unless the class defines the `__cmp__()' method. Refer to the for information on the use of this method to effect object comparisons. *Implementation note:* Objects of different types except numbers are ordered by their type names; objects of the same types that don't support proper comparison are ordered by their address. Two more operations with the same syntactic priority, `in' and `not in', are supported only by sequence types (below).  File: python-lib.info, Node: Numeric Types, Next: Sequence Types, Prev: Comparisons, Up: Built-in Types Numeric Types ------------- There are four numeric types: "plain integers", "long integers", "floating point numbers", and "complex numbers". Plain integers (also just called "integers") are implemented using `long' in C, which gives them at least 32 bits of precision. Long integers have unlimited precision. Floating point numbers are implemented using `double' in C. All bets on their precision are off unless you happen to know the machine you are working with. Complex numbers have a real and imaginary part, which are both implemented using `double' in C. To extract these parts from a complex number Z, use `Z.real' and `Z.imag'. Numbers are created by numeric literals or as the result of built-in functions and operators. Unadorned integer literals (including hex and octal numbers) yield plain integers. Integer literals with an `L' or `l' suffix yield long integers (`L' is preferred because `1l' looks too much like eleven!). Numeric literals containing a decimal point or an exponent sign yield floating point numbers. Appending `j' or `J' to a numeric literal yields a complex number. Python fully supports mixed arithmetic: when a binary arithmetic operator has operands of different numeric types, the operand with the "smaller" type is converted to that of the other, where plain integer is smaller than long integer is smaller than floating point is smaller than complex. Comparisons between numbers of mixed type use the same rule.(1) The functions `int()', `long()', `float()', and `complex()' can be used to coerce numbers to a specific type. All numeric types support the following operations, sorted by ascending priority (operations in the same box have the same priority; all numeric operations have a higher priority than comparison operations): Operation Result Notes ------ ----- ----- X + Y sum of X and Y X - Y difference of X and Y X * Y product of X and Y X / Y quotient of X and Y (1) X %{} Y remainder of `X / Y' -X X negated +X X unchanged abs(X) absolute value or magnitude of X int(X) X converted to integer (2) long(X) X converted to long (2) integer float(X) X converted to floating point complex(RE,IM) a complex number with real part RE, imaginary part IM. IM defaults to zero. C.conjugate() conjugate of the complex number C divmod(X, Y) the pair `(X / Y, X %{} (3) Y)' pow(X, Y) X to the power Y X ** Y X to the power Y Notes: `(1)' For (plain or long) integer division, the result is an integer. The result is always rounded towards minus infinity: 1/2 is 0, (-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0. Note that the result is a long integer if either operand is a long integer, regardless of the numeric value. `(2)' Conversion from floating point to (long or plain) integer may round or truncate as in C; see functions `floor()' and `ceil()' in the `math' module for well-defined conversions. `(3)' See section *Note Built-in Functions::, "Built-in Functions," for a full description. * Menu: * Bit-string Operations:: ---------- Footnotes ---------- (1) As a consequence, the list `[1, 2]' is considered equal to `[1.0, 2.0]', and similar for tuples.  File: python-lib.info, Node: Bit-string Operations, Prev: Numeric Types, Up: Numeric Types Bit-string Operations on Integer Types ...................................... Plain and long integer types support additional operations that make sense only for bit-strings. Negative numbers are treated as their 2's complement value (for long integers, this assumes a sufficiently large number of bits that no overflow occurs during the operation). The priorities of the binary bit-wise operations are all lower than the numeric operations and higher than the comparisons; the unary operation `~' has the same priority as the other unary numeric operations (`+' and `-'). This table lists the bit-string operations sorted in ascending priority (operations in the same box have the same priority): Operation Result Notes ------ ----- ----- X | Y bitwise "or" of X and Y X ^{} Y bitwise "exclusive or" of X and Y X &{} Y bitwise "and" of X and Y X << N X shifted left by N (1), (2) bits X >> N X shifted right by N (1), (3) bits ~X the bits of X inverted Notes: `(1)' Negative shift counts are illegal and cause a `ValueError' to be raised. `(2)' A left shift by N bits is equivalent to multiplication by `pow(2, N)' without overflow check. `(3)' A right shift by N bits is equivalent to division by `pow(2, N)' without overflow check.  File: python-lib.info, Node: Sequence Types, Next: Mapping Types, Prev: Numeric Types, Up: Built-in Types Sequence Types -------------- There are six sequence types: strings, Unicode strings, lists, tuples, buffers, and xrange objects. Strings literals are written in single or double quotes: `'xyzzy'', `"frobozz"'. See chapter 2 of the for more about string literals. Unicode strings are much like strings, but are specified in the syntax using a preceeding `u' character: `u'abc'', `u"def"'. Lists are constructed with square brackets, separating items with commas: `[a, b, c]'. Tuples are constructed by the comma operator (not within square brackets), with or without enclosing parentheses, but an empty tuple must have the enclosing parentheses, e.g., `a, b, c' or `()'. A single item tuple must have a trailing comma, e.g., `(d,)'. Buffers are not directly supported by Python syntax, but can be created by calling the builtin function `buffer()'. XRanges objects are similar to buffers in that there is no specific syntax to create them, but they are created using the `xrange()' function. Sequence types support the following operations. The `in' and `not in' operations have the same priorities as the comparison operations. The `+' and `*' operations have the same priority as the corresponding numeric operations.(1) This table lists the sequence operations sorted in ascending priority (operations in the same box have the same priority). In the table, S and T are sequences of the same type; N, I and J are integers: Operation Result Notes ------ ----- ----- X in S `1' if an item of S is equal to X, else `0' X not in S `0' if an item of S is equal to X, else `1' S + T the concatenation of S and T S * N, N * S N copies of S (1) concatenated S[I] I'th item of S, origin (2) 0 S[I:J] slice of S from I to J (2), (3) len(S) length of S min(S) smallest item of S max(S) largest item of S Notes: `(1)' Values of N less than `0' are treated as `0' (which yields an empty sequence of the same type as S). `(2)' If I or J is negative, the index is relative to the end of the string, i.e., `len(S) + I' or `len(S) + J' is substituted. But note that `-0' is still `0'. `(3)' The slice of S from I to J is defined as the sequence of items with index K such that `I <= K < J'. If I or J is greater than `len(S)', use `len(S)'. If I is omitted, use `0'. If J is omitted, use `len(S)'. If I is greater than or equal to J, the slice is empty. * Menu: * String Methods:: * String Formatting Operations:: * XRange Type:: * Mutable Sequence Types:: ---------- Footnotes ---------- (1) They must have since the parser can't tell the type of the operands.  File: python-lib.info, Node: String Methods, Next: String Formatting Operations, Prev: Sequence Types, Up: Sequence Types String Methods .............. These are the string methods which both 8-bit strings and Unicode objects support: `capitalize()' Return a copy of the string with only its first character capitalized. `center(width)' Return centered in a string of length WIDTH. Padding is done using spaces. `count(sub[, start[, end]])' Return the number of occurrences of substring SUB in string S`[START:END]'. Optional arguments START and END are interpreted as in slice notation. `encode([encoding[,errors]])' Return an encoded version of the string. Default encoding is the current default string encoding. ERRORS may be given to set a different error handling scheme. The default for ERRORS is `'strict'', meaning that encoding errors raise a `ValueError'. Other possible values are `'ignore'' and `'replace''. _Added in Python version 2.0_ `endswith(suffix[, start[, end]])' Return true if the string ends with the specified SUFFIX, otherwise return false. With optional START, test beginning at that position. With optional END, stop comparing at that position. `expandtabs([tabsize])' Return a copy of the string where all tab characters are expanded using spaces. If TABSIZE is not given, a tab size of `8' characters is assumed. `find(sub[, start[, end]])' Return the lowest index in the string where substring SUB is found, such that SUB is contained in the range [START, END). Optional arguments START and END are interpreted as in slice notation. Return `-1' if SUB is not found. `index(sub[, start[, end]])' Like `find()', but raise `ValueError' when the substring is not found. `isalnum()' Return true if all characters in the string are alphanumeric and there is at least one character, false otherwise. `isalpha()' Return true if all characters in the string are alphabetic and there is at least one character, false otherwise. `isdigit()' Return true if there are only digit characters, false otherwise. `islower()' Return true if all cased characters in the string are lowercase and there is at least one cased character, false otherwise. `isspace()' Return true if there are only whitespace characters in the string and the string is not empty, false otherwise. `istitle()' Return true if the string is a titlecased string, i.e. uppercase characters may only follow uncased characters and lowercase characters only cased ones. Return false otherwise. `isupper()' Return true if all cased characters in the string are uppercase and there is at least one cased character, false otherwise. `join(seq)' Return a string which is the concatenation of the strings in the sequence SEQ. The separator between elements is the string providing this method. `ljust(width)' Return the string left justified in a string of length WIDTH. Padding is done using spaces. The original string is returned if WIDTH is less than `len(S)'. `lower()' Return a copy of the string converted to lowercase. `lstrip()' Return a copy of the string with leading whitespace removed. `replace(old, new[, maxsplit])' Return a copy of the string with all occurrences of substring OLD replaced by NEW. If the optional argument MAXSPLIT is given, only the first MAXSPLIT occurrences are replaced. `rfind(sub [,start [,end]])' Return the highest index in the string where substring SUB is found, such that SUB is contained within s[start,end]. Optional arguments START and END are interpreted as in slice notation. Return `-1' on failure. `rindex(sub[, start[, end]])' Like `rfind()' but raises `ValueError' when the substring SUB is not found. `rjust(width)' Return the string right justified in a string of length WIDTH. Padding is done using spaces. The original string is returned if WIDTH is less than `len(S)'. `rstrip()' Return a copy of the string with trailing whitespace removed. `split([sep [,maxsplit]])' Return a list of the words in the string, using SEP as the delimiter string. If MAXSPLIT is given, at most MAXSPLIT splits are done. If SEP is not specified or `None', any whitespace string is a separator. `splitlines([keepends])' Return a list of the lines in the string, breaking at line boundaries. Line breaks are not included in the resulting list unless KEEPENDS is given and true. `startswith(prefix[, start[, end]])' Return true if string starts with the PREFIX, otherwise return false. With optional START, test string beginning at that position. With optional END, stop comparing string at that position. `strip()' Return a copy of the string with leading and trailing whitespace removed. `swapcase()' Return a copy of the string with uppercase characters converted to lowercase and vice versa. `title()' Return a titlecased version of, i.e. words start with uppercase characters, all remaining cased characters are lowercase. `translate(table[, deletechars])' Return a copy of the string where all characters occurring in the optional argument DELETECHARS are removed, and the remaining characters have been mapped through the given translation table, which must be a string of length 256. `upper()' Return a copy of the string converted to uppercase.  File: python-lib.info, Node: String Formatting Operations, Next: XRange Type, Prev: String Methods, Up: Sequence Types String Formatting Operations ............................ String and Unicode objects have one unique built-in operation: the `%' operator (modulo). Given `FORMAT % VALUES' (where FORMAT is a string or Unicode object), `%' conversion specifications in FORMAT are replaced with zero or more elements of VALUES. The effect is similar to the using `sprintf()' in the C language. If FORMAT is a Unicode object, or if any of the objects being converted using the `%s' conversion are Unicode objects, the result will be a Unicode object as well. If FORMAT requires a single argument, VALUES may be a single non-tuple object. (1) Otherwise, VALUES must be a tuple with exactly the number of items specified by the format string, or a single mapping object (for example, a dictionary). A conversion specifier contains two or more characters and has the following components, which must occur in this order: 1. The `%' character, which marks the start of the specifier. 2. Mapping key value (optional), consisting of an identifier in parentheses (for example, `(somename)'). 3. Conversion flags (optional), which affect the result of some conversion types. 4. Minimum field width (optional). If specified as an `*' (asterisk), the actual width is read from the next element of the tuple in VALUES, and the object to convert comes after the minimum field width and optional precision. 5. Precision (optional), given as a `.' (dot) followed by the precision. If specified as `*' (an asterisk), the actual width is read from the next element of the tuple in VALUES, and the value to convert comes after the precision. 6. Length modifier (optional). 7. Conversion type. If the right argument is a dictionary (or any kind of mapping), then the formats in the string _must_ have a parenthesized key into that dictionary inserted immediately after the `%' character, and each format formats the corresponding entry from the mapping. For example: >>> count = 2 >>> language = 'Python' >>> print '%(language)s has %(count)03d quote types.' % vars() Python has 002 quote types. In this case no `*' specifiers may occur in a format (since they require a sequential parameter list). The conversion flag characters are: Flag Meaning ------ ----- # The value conversion will use the "alternate form" (where defined below). 0 The conversion will be zero padded. - The converted value is left adjusted (overrides `-'). {~} (a space) A blank should be left before a positive number (or empty string) produced by a signed conversion. + A sign character (`+' or `-') will precede the conversion (overrides a "space" flag). The length modifier may be `h', `l', and `L' may be present, but are ignored as they are not necessary for Python. The conversion types are: Conversion Meaning ------ ----- d Signed integer decimal. i Signed integer decimal. o Unsigned octal. u Unsigned decimal. x Unsigned hexidecimal (lowercase). X Unsigned hexidecimal (uppercase). e Floating point exponential format (lowercase). E Floating point exponential format (uppercase). f Floating point decimal format. F Floating point decimal format. g Same as `e' if exponent is greater than -4 or less than precision, `f' otherwise. G Same as `E' if exponent is greater than -4 or less than precision, `F' otherwise. c Single character (accepts integer or single character string). r String (converts any python object using `repr()'). s String (converts any python object using `str()'). % No argument is converted, results in a `%' character in the result. (The complete specification is `%%'.) Since Python strings have an explicit length, `%s' conversions do not assume that `'\0'' is the end of the string. For safety reasons, floating point precisions are clipped to 50; `%f' conversions for numbers whose absolute value is over 1e25 are replaced by `%g' conversions.(2) All other errors raise exceptions. Additional string operations are defined in standard module `string' and in built-in module `re'. ---------- Footnotes ---------- (1) A tuple object in this case should be a singleton. (2) These numbers are fairly arbitrary. They are intended to avoid printing endless strings of meaningless digits without hampering correct use and without having to know the exact precision of floating point values on a particular machine.  File: python-lib.info, Node: XRange Type, Next: Mutable Sequence Types, Prev: String Formatting Operations, Up: Sequence Types XRange Type ........... The xrange type is an immutable sequence which is commonly used for looping. The advantage of the xrange type is that an xrange object will always take the same amount of memory, no matter the size of the range it represents. There are no consistent performance advantages. XRange objects behave like tuples, and offer a single method: `tolist()' Return a list object which represents the same values as the xrange object.  File: python-lib.info, Node: Mutable Sequence Types, Prev: XRange Type, Up: Sequence Types Mutable Sequence Types ...................... List objects support additional operations that allow in-place modification of the object. These operations would be supported by other mutable sequence types (when added to the language) as well. Strings and tuples are immutable sequence types and such objects cannot be modified once created. The following operations are defined on mutable sequence types (where X is an arbitrary object): Operation Result Notes ------ ----- ----- S[I] = X item I of S is replaced by X S[I:J] = T slice of S from I to J is replaced by T del S[I:J] same as `S[I:J] = []' S.append(X) same as (1) `S[len(S):len(S)] = [X]' S.extend(X) same as (2) `S[len(S):len(S)] = X' S.count(X) return number of I's for which `S[I] == X' S.index(X) return smallest I such (3) that `S[I] == X' S.insert(I, X) same as `S[I:I] = [X]' if `I >= 0' S.pop([I]) same as `X = S[I]; del (4) S[I]; return X' S.remove(X) same as `del (3) S[S.index(X)]' S.reverse() reverses the items of S (5) in place S.sort([CMPFUNC]) sort the items of S in (5), (6) place {types} Notes: `(1)' The C implementation of Python has historically accepted multiple parameters and implicitly joined them into a tuple; this no longer works in Python 2.0. Use of this misfeature has been deprecated since Python 1.4. `(2)' Raises an exception when X is not a list object. The `extend()' method is experimental and not supported by mutable sequence types other than lists. `(3)' Raises `ValueError' when X is not found in S. `(4)' The `pop()' method is only supported by the list and array types. The optional argument I defaults to `-1', so that by default the last item is removed and returned. `(5)' The `sort()' and `reverse()' methods modify the list in place for economy of space when sorting or reversing a large list. They don't return the sorted or reversed list to remind you of this side effect. `(6)' The `sort()' method takes an optional argument specifying a comparison function of two arguments (list items) which should return `-1', `0' or `1' depending on whether the first argument is considered smaller than, equal to, or larger than the second argument. Note that this slows the sorting process down considerably; e.g. to sort a list in reverse order it is much faster to use calls to the methods `sort()' and `reverse()' than to use the built-in function `sort()' with a comparison function that reverses the ordering of the elements.  File: python-lib.info, Node: Mapping Types, Next: Other Built-in Types, Prev: Sequence Types, Up: Built-in Types Mapping Types ------------- A "mapping" object maps values of one type (the key type) to arbitrary objects. Mappings are mutable objects. There is currently only one standard mapping type, the "dictionary". A dictionary's keys are almost 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. 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 created by placing a comma-separated list of `KEY: VALUE' pairs within braces, for example: `{'jack': 4098, 'sjoerd': 4127}' or `{4098: 'jack', 4127: 'sjoerd'}'. The following operations are defined on mappings (where A and B are mappings, K is a key, and V and X are arbitrary objects): Operation Result Notes ------ ----- ----- len(A) the number of items in A A[K] the item of A with key (1) K A[K] = V set `A[K]' to V del A[K] remove `A[K]' from A (1) A.clear() remove all items from `a' A.copy() a (shallow) copy of `a' A.has_key(K) `1' if A has a key K, else `0' A.items() a copy of A's list of (2) (KEY, VALUE) pairs A.keys() a copy of A's list of (2) keys A.update(B) `for k in B.keys(): (3) A[k] = B[k]' A.values() a copy of A's list of (2) values A.get(K[, X]) `A[K]' if (4) `A.has_key(K)', else X A.setdefault(K[, X]) `A[K]' if (5) `A.has_key(K)', else X (also setting it) A.popitem() remove and return an (6) arbitrary (KEY, VALUE) pair Notes: `(1)' Raises a `KeyError' exception if K is not in the map. `(2)' Keys and values are listed in random order. If `keys()' and `values()' are called with no intervening modifications to the dictionary, the two lists will directly correspond. This allows the creation of `(VALUE, KEY)' pairs using `map()': `pairs = map(None, A.values(), A.keys())'. `(3)' B must be of the same type as A. `(4)' Never raises an exception if K is not in the map, instead it returns X. X is optional; when X is not provided and K is not in the map, `None' is returned. `(5)' `setdefault()' is like `get()', except that if K is missing, X is both returned and inserted into the dictionary as the value of K. `(6)' `popitem()' is useful to destructively iterate over a dictionary, as often used in set algorithms.  File: python-lib.info, Node: Other Built-in Types, Next: Special Attributes, Prev: Mapping Types, Up: Built-in Types Other Built-in Types -------------------- The interpreter supports several other kinds of objects. Most of these support only one or two operations. * Menu: * Modules:: * Classes and Instances:: * Functions:: * Methods:: * Code Objects:: * Type Objects:: * Null Object:: * Ellipsis Object:: * File Objectsfile:: * Internal Objects::  File: python-lib.info, Node: Modules, Next: Classes and Instances, Prev: Other Built-in Types, Up: Other Built-in Types Modules ....... The only special operation on a module is attribute access: `M.NAME', where M is a module and NAME accesses a name defined in M's symbol table. Module attributes can be assigned to. (Note that the `import' statement is not, strictly speaking, an operation on a module object; `import FOO' does not require a module object named FOO to exist, rather it requires an (external) _definition_ for a module named FOO somewhere.) A special member of every module is `__dict__'. This is the dictionary containing the module's symbol table. Modifying this dictionary will actually change the module's symbol table, but direct assignment to the `__dict__' attribute is not possible (i.e., you can write `M.__dict__['a'] = 1', which defines `M.a' to be `1', but you can't write `M.__dict__ = {}'. Modules built into the interpreter are written like this: `'. If loaded from a file, they are written as `'.  File: python-lib.info, Node: Classes and Instances, Next: Functions, Prev: Modules, Up: Other Built-in Types Classes and Class Instances ........................... See chapters 3 and 7 of the for these.  File: python-lib.info, Node: Functions, Next: Methods, Prev: Classes and Instances, Up: Other Built-in Types Functions ......... Function objects are created by function definitions. The only operation on a function object is to call it: `FUNC(ARGUMENT-LIST)'. There are really two flavors of function objects: built-in functions and user-defined functions. Both support the same operation (to call the function), but the implementation is different, hence the different object types. The implementation adds two special read-only attributes: `F.func_code' is a function's "code object" (see below) and `F.func_globals' is the dictionary used as the function's global namespace (this is the same as `M.__dict__' where M is the module in which the function F was defined). Function objects also support getting and setting arbitrary attributes, which can be used to, e.g. attach metadata to functions. Regular attribute dot-notation is used to get and set such attributes. _Note that the current implementation only supports function attributes on functions written in Python. Function attributes on built-ins may be supported in the future._ Functions have another special attribute `F.__dict__' (a.k.a. `F.func_dict') which contains the namespace used to support function attributes. `__dict__' can be accessed directly, set to a dictionary object, or `None'. It can also be deleted (but the following two lines are equivalent): del func.__dict__ func.__dict__ = None  File: python-lib.info, Node: Methods, Next: Code Objects, Prev: Functions, Up: Other Built-in Types Methods ....... Methods are functions that are called using the attribute notation. There are two flavors: built-in methods (such as `append()' on lists) and class instance methods. Built-in methods are described with the types that support them. The implementation adds two special read-only attributes to class instance methods: `M.im_self' is the object on which the method operates, and `M.im_func' is the function implementing the method. Calling `M(ARG-1, ARG-2, ..., ARG-N)' is completely equivalent to calling `M.im_func(M.im_self, ARG-1, ARG-2, ..., ARG-N)'. Class instance methods are either _bound_ or _unbound_, referring to whether the method was accessed through an instance or a class, respectively. When a method is unbound, its `im_self' attribute will be `None' and if called, an explicit `self' object must be passed as the first argument. In this case, `self' must be an instance of the unbound method's class (or a subclass of that class), otherwise a `TypeError' is raised. Like function objects, methods objects support getting arbitrary attributes. However, since method attributes are actually stored on the underlying function object (i.e. `meth.im_func'), setting method attributes on either bound or unbound methods is disallowed. Attempting to set a method attribute results in a `TypeError' being raised. In order to set a method attribute, you need to explicitly set it on the underlying function object: class C: def method(self): pass c = C() c.method.im_func.whoami = 'my name is c' See the for more information.