This is Info file /home/pdm/tmp/Python-1.5.2p1/Doc/lib/python-lib.info, produced by Makeinfo version 1.68 from the input file lib.texi. July 6, 1999 1.5.2  File: python-lib.info, Node: pprint, Next: repr, Prev: codeop, Up: Python Services Data pretty printer. ==================== Data pretty printer. This module was documented by Fred L. Drake, Jr. . This section was written by Fred L. Drake, Jr. . The `pprint' module provides a capability to "pretty-print" arbitrary Python data structures in a form which can be used as input to the interpreter. If the formatted structures include objects which are not fundamental Python types, the representation may not be loadable. This may be the case if objects such as files, sockets, classes, or instances are included, as well as many other builtin objects which are not representable as Python constants. The formatted representation keeps objects on a single line if it can, and breaks them onto multiple lines if they don't fit within the allowed width. Construct `PrettyPrinter' objects explicitly if you need to adjust the width constraint. The `pprint' module defines one class: `PrettyPrinter(...)' Construct a `PrettyPrinter' instance. This constructor understands several keyword parameters. An output stream may be set using the STREAM keyword; the only method used on the stream object is the file protocol's `write()' method. If not specified, the `PrettyPrinter' adopts `sys.stdout'. Three additional parameters may be used to control the formatted representation. The keywords are INDENT, DEPTH, and WIDTH. The amount of indentation added for each recursive level is specified by INDENT; the default is one. Other values can cause output to look a little odd, but can make nesting easier to spot. The number of levels which may be printed is controlled by DEPTH; if the data structure being printed is too deep, the next contained level is replaced by `...'. By default, there is no constraint on the depth of the objects being formatted. The desired output width is constrained using the WIDTH parameter; the default is eighty characters. If a structure cannot be formatted within the constrained width, a best effort will be made. >>> import pprint, sys >>> stuff = sys.path[:] >>> stuff.insert(0, stuff[:]) >>> pp = pprint.PrettyPrinter(indent=4) >>> pp.pprint(stuff) [ [ '', '/usr/local/lib/python1.5', '/usr/local/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter'], '', '/usr/local/lib/python1.5', '/usr/local/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter'] >>> >>> import parser >>> tup = parser.ast2tuple( ... parser.suite(open('pprint.py').read()))[1][1][1] >>> pp = pprint.PrettyPrinter(depth=6) >>> pp.pprint(tup) (266, (267, (307, (287, (288, (...)))))) The `PrettyPrinter' class supports several derivative functions: `pformat(object)' Return the formatted representation of OBJECT as a string. The default parameters for formatting are used. `pprint(object[, stream])' Prints the formatted representation of OBJECT on STREAM, followed by a newline. If STREAM is omitted, `sys.stdout' is used. This may be used in the interactive interpreter instead of a `print' statement for inspecting values. The default parameters for formatting are used. >>> stuff = sys.path[:] >>> stuff.insert(0, stuff) >>> pprint.pprint(stuff) [, '', '/usr/local/lib/python1.5', '/usr/local/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter'] `isreadable(object)' Determine if the formatted representation of OBJECT is "readable," or can be used to reconstruct the value using `eval()'. This always returns false for recursive objects. >>> pprint.isreadable(stuff) 0 `isrecursive(object)' Determine if OBJECT requires a recursive representation. One more support function is also defined: `saferepr(object)' Return a string representation of OBJECT, protected against recursive data structures. If the representation of OBJECT exposes a recursive entry, the recursive reference will be represented as `'. The representation is not otherwise formatted. >>> pprint.saferepr(stuff) "[, '', '/usr/local/lib/python1.5', '/usr/loca l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python 1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']" * Menu: * PrettyPrinter Objects::  File: python-lib.info, Node: PrettyPrinter Objects, Prev: pprint, Up: pprint PrettyPrinter Objects --------------------- `PrettyPrinter' instances have the following methods: `pformat(object)' Return the formatted representation of OBJECT. This takes into Account the options passed to the `PrettyPrinter' constructor. `pprint(object)' Print the formatted representation of OBJECT on the configured stream, followed by a newline. The following methods provide the implementations for the corresponding functions of the same names. Using these methods on an instance is slightly more efficient since new `PrettyPrinter' objects don't need to be created. `isreadable(object)' Determine if the formatted representation of the object is "readable," or can be used to reconstruct the value using `eval()'. Note that this returns false for recursive objects. If the DEPTH parameter of the `PrettyPrinter' is set and the object is deeper than allowed, this returns false. `isrecursive(object)' Determine if the object requires a recursive representation.  File: python-lib.info, Node: repr, Next: py_compile, Prev: pprint, Up: Python Services Alternate `repr()' implementation. ================================== This section was written by Fred L. Drake, Jr. . Alternate `repr()' implementation with size limits. The `repr' module provides a means for producing object representations with limits on the size of the resulting strings. This is used in the Python debugger and may be useful in other contexts as well. This module provides a class, an instance, and a function: `Repr()' Class which provides formatting services useful in implementing functions similar to the built-in `repr()'; size limits for different object types are added to avoid the generation of representations which are excessively long. `aRepr' This is an instance of `Repr' which is used to provide the `repr()' function described below. Changing the attributes of this object will affect the size limits used by `repr()' and the Python debugger. `repr(obj)' This is the `repr()' method of `aRepr'. It returns a string similar to that returned by the built-in function of the same name, but with limits on most sizes. * Menu: * Repr Objects:: * Subclassing Repr Objects::  File: python-lib.info, Node: Repr Objects, Next: Subclassing Repr Objects, Prev: repr, Up: repr Repr Objects ------------ `Repr' instances provide several members which can be used to provide size limits for the representations of different object types, and methods which format specific object types. `maxlevel' Depth limit on the creation of recursive representations. The default is `6'. `maxdict' `maxlist' `maxtuple' Limits on the number of entries represented for the named object type. The default for `maxdict' is `4', for the others, `6'. `maxlong' Maximum number of characters in the representation for a long integer. Digits are dropped from the middle. The default is `40'. `maxstring' Limit on the number of characters in the representation of the string. Note that the "normal" representation of the string is used as the character source: if escape sequences are needed in the representation, these may be mangled when the representation is shortened. The default is `30'. `maxother' This limit is used to control the size of object types for which no specific formatting method is available on the `Repr' object. It is applied in a similar manner as `maxstring'. The default is `20'. `repr(obj)' The equivalent to the built-in `repr()' that uses the formatting imposed by the instance. `repr1(obj, level)' Recursive implementation used by `repr()'. This uses the type of OBJ to determine which formatting method to call, passing it OBJ and LEVEL. The type-specific methods should call `repr1()' to perform recursive formatting, with `LEVEL - 1' for the value of LEVEL in the recursive call. `repr_TYPE(obj, level)' Formatting methods for specific types are implemented as methods with a name based on the type name. In the method name, TYPE is replaced by `string.join(string.split(type(OBJ).__name__, '_')'. Dispatch to these methods is handled by `repr1()'. Type-specific methods which need to recursively format a value should call `self.repr1(SUBOBJ, LEVEL - 1)'.  File: python-lib.info, Node: Subclassing Repr Objects, Prev: Repr Objects, Up: repr Subclassing Repr Objects ------------------------ The use of dynamic dispatching by `Repr.repr1()' allows subclasses of `Repr' to add support for additional built-in object types or to modify the handling of types already supported. This example shows how special support for file objects could be added: import repr import sys class MyRepr(repr.Repr): def repr_file(self, obj, level): if obj.name in ['', '', '']: return obj.name else: return `obj` aRepr = MyRepr() print aRepr.repr(sys.stdin) # prints ''  File: python-lib.info, Node: py_compile, Next: compileall, Prev: repr, Up: Python Services Compile Python source files. ============================ Compile Python source files to byte-code files. The `py_compile' module provides a single function to generate a byte-code file from a source file. Though not often needed, this function can be useful when installing modules for shared use, especially if some of the users may not have permission to write the byte-code cache files in the directory containing the source code. `compile(file[, cfile[, dfile]])' Compile a source file to byte-code and write out the byte-code cache file. The source code is loaded from the file name FILE. The byte-code is written to CFILE, which defaults to FILE `+' `'c'' (`'o'' if optimization is enabled in the current interpreter). If DFILE is specified, it is used as the name of the source file in error messages instead of FILE. See also: *Note compileall:: Utilities to compile all Python source files in a directory tree.  File: python-lib.info, Node: compileall, Next: dis, Prev: py_compile, Up: Python Services Byte-compile Python libraries. ============================== Tools for byte-compiling all Python source files in a directory tree. This module provides some utility functions to support installing Python libraries. These functions compile Python source files in a directory tree, allowing users without permission to write to the libraries to take advantage of cached byte-code files. The source file for this module may also be used as a script to compile Python sources in directories named on the command line or in `sys.path'. `compile_dir(dir[, maxlevels[, ddir]])' Recursively descend the directory tree named by DIR, compiling all `.py' files along the way. The MAXLEVELS parameter is used to limit the depth of the recursion; it defaults to `10'. If DDIR is given, it is used as the base path from which the filenames used in error messages will be generated. `compile_path([skip_curdir[, maxlevels]])' Byte-compile all the `.py' files found along `sys.path'. If SKIP_CURDIR is true (the default), the current directory is not included in the search. The MAXLEVELS parameter defaults to `0' and is passed to the `compile_dir()' function. See also: *Note py_compile:: Byte-compile a single source file.  File: python-lib.info, Node: dis, Next: new, Prev: compileall, Up: Python Services Disassembler. ============= Disassembler. The `dis' module supports the analysis of Python byte code by disassembling it. Since there is no Python assembler, this module defines the Python assembly language. The Python byte code which this module takes as an input is defined in the file `Include/opcode.h' and used by the compiler and the interpreter. Example: Given the function `myfunc': def myfunc(alist): return len(alist) the following command can be used to get the disassembly of `myfunc()': >>> dis.dis(myfunc) 0 SET_LINENO 1 3 SET_LINENO 2 6 LOAD_GLOBAL 0 (len) 9 LOAD_FAST 0 (alist) 12 CALL_FUNCTION 1 15 RETURN_VALUE 16 LOAD_CONST 0 (None) 19 RETURN_VALUE The `dis' module defines the following functions: `dis([bytesource])' Disassemble the BYTESOURCE object. BYTESOURCE can denote either a class, a method, a function, or a code object. For a class, it disassembles all methods. For a single code sequence, it prints one line per byte code instruction. If no object is provided, it disassembles the last traceback. `distb([tb])' Disassembles the top-of-stack function of a traceback, using the last traceback if none was passed. The instruction causing the exception is indicated. `disassemble(code[, lasti])' Disassembles a code object, indicating the last instruction if LASTI was provided. The output is divided in the following columns: 1. the current instruction, indicated as `-->', 2. a labelled instruction, indicated with `>>', 3. the address of the instruction, 4. the operation code name, 5. operation parameters, and 6. interpretation of the parameters in parentheses. The parameter interpretation recognizes local and global variable names, constant values, branch targets, and compare operators. `disco(code[, lasti])' A synonym for disassemble. It is more convenient to type, and kept for compatibility with earlier Python releases. `opname' Sequence of a operation names, indexable using the byte code. `cmp_op' Sequence of all compare operation names. `hasconst' Sequence of byte codes that have a constant parameter. `hasname' Sequence of byte codes that access a attribute by name. `hasjrel' Sequence of byte codes that have a relative jump target. `hasjabs' Sequence of byte codes that have an absolute jump target. `haslocal' Sequence of byte codes that access a a local variable. `hascompare' Sequence of byte codes of boolean operations. * Menu: * Python Byte Code Instructions::  File: python-lib.info, Node: Python Byte Code Instructions, Prev: dis, Up: dis Python Byte Code Instructions ----------------------------- The Python compiler currently generates the following byte code instructions. `STOP_CODE' Indicates end-of-code to the compiler, not used by the interpreter. `POP_TOP' Removes the top-of-stack (TOS) item. `ROT_TWO' Swaps the two top-most stack items. `ROT_THREE' Lifts second and third stack item one position up, moves top down to position three. `DUP_TOP' Duplicates the reference on top of the stack. Unary Operations take the top of the stack, apply the operation, and push the result back on the stack. `UNARY_POSITIVE' Implements `TOS = +TOS'. `UNARY_NEG' Implements `TOS = -TOS'. `UNARY_NOT' Implements `TOS = not TOS'. `UNARY_CONVERT' Implements `TOS = `TOS`'. `UNARY_INVERT' Implements `TOS = ~TOS'. Binary operations remove the top of the stack (TOS) and the second top-most stack item (TOS1) from the stack. They perform the operation, and put the result back on the stack. `BINARY_POWER' Implements `TOS = TOS1 ** TOS'. `BINARY_MULTIPLY' Implements `TOS = TOS1 * TOS'. `BINARY_DIVIDE' Implements `TOS = TOS1 / TOS'. `BINARY_MODULO' Implements `TOS = TOS1 % TOS'. `BINARY_ADD' Implements `TOS = TOS1 + TOS'. `BINARY_SUBTRACT' Implements `TOS = TOS1 - TOS'. `BINARY_SUBSCR' Implements `TOS = TOS1[TOS]'. `BINARY_LSHIFT' Implements `TOS = TOS1 << TOS'. `BINARY_RSHIFT' Implements `TOS = TOS1 >> TOS'. `BINARY_AND' Implements `TOS = TOS1 and TOS'. `BINARY_XOR' Implements `TOS = TOS1 ^ TOS'. `BINARY_OR' Implements `TOS = TOS1 or TOS'. The slice opcodes take up to three parameters. `SLICE+0' Implements `TOS = TOS[:]'. `SLICE+1' Implements `TOS = TOS1[TOS:]'. `SLICE+2' Implements `TOS = TOS1[:TOS1]'. `SLICE+3' Implements `TOS = TOS2[TOS1:TOS]'. Slice assignment needs even an additional parameter. As any statement, they put nothing on the stack. `STORE_SLICE+0' Implements `TOS[:] = TOS1'. `STORE_SLICE+1' Implements `TOS1[TOS:] = TOS2'. `STORE_SLICE+2' Implements `TOS1[:TOS] = TOS2'. `STORE_SLICE+3' Implements `TOS2[TOS1:TOS] = TOS3'. `DELETE_SLICE+0' Implements `del TOS[:]'. `DELETE_SLICE+1' Implements `del TOS1[TOS:]'. `DELETE_SLICE+2' Implements `del TOS1[:TOS]'. `DELETE_SLICE+3' Implements `del TOS2[TOS1:TOS]'. `STORE_SUBSCR' Implements `TOS1[TOS] = TOS2'. `DELETE_SUBSCR' Implements `del TOS1[TOS]'. `PRINT_EXPR' Implements the expression statement for the interactive mode. TOS is removed from the stack and printed. In non-interactive mode, an expression statement is terminated with `POP_STACK'. `PRINT_ITEM' Prints TOS. There is one such instruction for each item in the print statement. `PRINT_NEWLINE' Prints a new line on `sys.stdout'. This is generated as the last operation of a print statement, unless the statement ends with a comma. `BREAK_LOOP' Terminates a loop due to a break statement. `LOAD_LOCALS' Pushes a reference to the locals of the current scope on the stack. This is used in the code for a class definition: After the class body is evaluated, the locals are passed to the class definition. `RETURN_VALUE' Returns with TOS to the caller of the function. `EXEC_STMT' Implements `exec TOS2,TOS1,TOS'. The compiler fills missing optional parameters with None. `POP_BLOCK' Removes one block from the block stack. Per frame, there is a stack of blocks, denoting nested loops, try statements, and such. `END_FINALLY' Terminates a finally-block. The interpreter recalls whether the exception has to be re-raised, or whether the function returns, and continues with the outer-next block. `BUILD_CLASS' Creates a new class object. TOS is the methods dictionary, TOS1 the tuple of the names of the base classes, and TOS2 the class name. All of the following opcodes expect arguments. An argument is two bytes, with the more significant byte last. `STORE_NAME namei' Implements `name = TOS'. NAMEI is the index of NAME in the attribute `co_names' of the code object. The compiler tries to use `STORE_LOCAL' or `STORE_GLOBAL' if possible. `DELETE_NAME namei' Implements `del name', where NAMEI is the index into `co_names' attribute of the code object. `UNPACK_TUPLE count' Unpacks TOS into COUNT individual values, which are put onto the stack right-to-left. `UNPACK_LIST count' Unpacks TOS into COUNT individual values. `STORE_ATTR namei' Implements `TOS.name = TOS1', where NAMEI is the index of name in `co_names'. `DELETE_ATTR namei' Implements `del TOS.name', using NAMEI as index into `co_names'. `STORE_GLOBAL namei' Works as `STORE_NAME', but stores the name as a global. `DELETE_GLOBAL namei' Works as `DELETE_NAME', but deletes a global name. `LOAD_CONST consti' Pushes `co_consts[CONSTI]' onto the stack. `LOAD_NAME namei' Pushes the value associated with `co_names[NAMEI]' onto the stack. `BUILD_TUPLE count' Creates a tuple consuming COUNT items from the stack, and pushes the resulting tuple onto the stack. `BUILD_LIST count' Works as `BUILD_TUPLE', but creates a list. `BUILD_MAP zero' Pushes an empty dictionary object onto the stack. The argument is ignored and set to zero by the compiler. `LOAD_ATTR namei' Replaces TOS with `getattr(TOS,co_names[NAMEI]'. `COMPARE_OP opname' Performs a boolean operation. The operation name can be found in `cmp_op[OPNAME]'. `IMPORT_NAME namei' Imports the module `co_names[NAMEI]'. The module object is pushed onto the stack. The current name space is not affected: for a proper import statement, a subsequent `STORE_FAST' instruction modifies the name space. `IMPORT_FROM namei' Imports the attribute `co_names[NAMEI]'. The module to import from is found in TOS and left there. `JUMP_FORWARD delta' Increments byte code counter by DELTA. `JUMP_IF_TRUE delta' If TOS is true, increment the byte code counter by DELTA. TOS is left on the stack. `JUMP_IF_FALSE delta' If TOS is false, increment the byte code counter by DELTA. TOS is not changed. `JUMP_ABSOLUTE target' Set byte code counter to TARGET. `FOR_LOOP delta' Iterate over a sequence. TOS is the current index, TOS1 the sequence. First, the next element is computed. If the sequence is exhausted, increment byte code counter by DELTA. Otherwise, push the sequence, the incremented counter, and the current item onto the stack. `LOAD_GLOBAL namei' Loads the global named `co_names[NAMEI]' onto the stack. `SETUP_LOOP delta' Pushes a block for a loop onto the block stack. The block spans from the current instruction with a size of DELTA bytes. `SETUP_EXCEPT delta' Pushes a try block from a try-except clause onto the block stack. DELTA points to the first except block. `SETUP_FINALLY delta' Pushes a try block from a try-except clause onto the block stack. DELTA points to the finally block. `LOAD_FAST var_num' Pushes a reference to the local `co_varnames[VAR_NUM]' onto the stack. `STORE_FAST var_num' Stores TOS into the local `co_varnames[VAR_NUM]'. `DELETE_FAST var_num' Deletes local `co_varnames[VAR_NUM]'. `SET_LINENO lineno' Sets the current line number to LINENO. `RAISE_VARARGS argc' Raises an exception. ARGC indicates the number of parameters to the raise statement, ranging from 1 to 3. The handler will find the traceback as TOS2, the parameter as TOS1, and the exception as TOS. `CALL_FUNCTION argc' Calls a function. The low byte of ARGC indicates the number of positional parameters, the high byte the number of keyword parameters. On the stack, the opcode finds the keyword parameters first. For each keyword argument, the value is on top of the key. Below the keyword parameters, the positional parameters are on the stack, with the right-most parameter on top. Below the parameters, the function object to call is on the stack. `MAKE_FUNCTION argc' Pushes a new function object on the stack. TOS is the code associated with the function. The function object is defined to have ARGC default parameters, which are found below TOS. `BUILD_SLICE argc' Pushes a slice object on the stack. ARGC must be 2 or 3. If it is 2, `slice(TOS1, TOS)' is pushed; if it is 3, `slice(TOS2, TOS1, TOS)' is pushed. See the `slice()' built-in function.  File: python-lib.info, Node: new, Next: site, Prev: dis, Up: Python Services Runtime implementation object creation ====================================== This section was written by Moshe Zadka . Interface to the creation of runtime implementation objects. The `new' module allows an interface to the interpreter object creation functions. This is for use primarily in marshal-type functions, when a new object needs to be created "magically" and not by using the regular creation functions. This module provides a low-level interface to the interpreter, so care must be exercised when using this module. The `new' module defines the following functions: `instance(class, dict)' This function creates an instance of CLASS with dictionary DICT without calling the `__init__()' constructor. Note that there are no guarantees that the object will be in a consistent state. `instancemethod(function, instance, class)' This function will return a method object, bound to INSTANCE, or unbound if INSTANCE is `None'. FUNCTION must be callable, and INSTANCE must be an instance object or `None'. `function(code, globals[, name[argdefs]])' Returns a (Python) function with the given code and globals. If NAME is given, it must be a string or `None'. If it is a string, the function will have the given name, otherwise the function name will be taken from `CODE.co_name'. If ARGDEFS is given, it must be a tuple and will be used to the determine the default values of parameters. `code(argcount, nlocals, stacksize, flags, codestring, constants, names, varnames, filename, name, firstlineno, lnotab)' This function is an interface to the `PyCode_New()' C function. `module(name)' This function returns a new module object with name NAME. NAME must be a string. `classobj(name, baseclasses, dict)' This function returns a new class object, with name NAME, derived from BASECLASSES (which should be a tuple of classes) and with namespace DICT.  File: python-lib.info, Node: site, Next: user, Prev: new, Up: Python Services Site-specific configuration hook ================================ A standard way to reference site-specific modules. *This module is automatically imported during initialization.* In earlier versions of Python (up to and including 1.5a3), scripts or modules that needed to use site-specific modules would place `import site' somewhere near the top of their code. This is no longer necessary. This will append site-specific paths to the module search path. It starts by constructing up to four directories from a head and a tail part. For the head part, it uses `sys.prefix' and `sys.exec_prefix'; empty heads are skipped. For the tail part, it uses the empty string (on Macintosh or Windows) or it uses first `lib/python{VERSION}/site-packages' and then `lib/site-python' (on UNIX). For each of the distinct head-tail combinations, it sees if it refers to an existing directory, and if so, adds to `sys.path', and also inspected for path configuration files. A path configuration file is a file whose name has the form `PACKAGE.pth'; its contents are additional items (one per line) to be added to `sys.path'. Non-existing items are never added to `sys.path', but no check is made that the item refers to a directory (rather than a file). No item is added to `sys.path' more than once. Blank lines and lines beginning with `#' are skipped. For example, suppose `sys.prefix' and `sys.exec_prefix' are set to `/usr/local'. The Python 1.5.2p1 library is then installed in `/usr/local/lib/python1.5' (note that only the first three characters of `sys.version' are used to form the path name). Suppose this has a subdirectory `/usr/local/lib/python1.5/site-packages' with three subsubdirectories, `foo', `bar' and `spam', and two path configuration files, `foo.pth' and `bar.pth'. Assume `foo.pth' contains the following: # foo package configuration foo bar bletch and `bar.pth' contains: # bar package configuration bar Then the following directories are added to `sys.path', in this order: /usr/local/lib/python1.5/site-packages/bar /usr/local/lib/python1.5/site-packages/foo Note that `bletch' is omitted because it doesn't exist; the `bar' directory precedes the `foo' directory because `bar.pth' comes alphabetically before `foo.pth'; and `spam' is omitted because it is not mentioned in either path configuration file. After these path manipulations, an attempt is made to import a module named `sitecustomize', which can perform arbitrary site-specific customizations. If this import fails with an `ImportError' exception, it is silently ignored. Note that for some non-UNIX systems, `sys.prefix' and `sys.exec_prefix' are empty, and the path manipulations are skipped; however the import of `sitecustomize' is still attempted.  File: python-lib.info, Node: user, Next: __builtin__, Prev: site, Up: Python Services User-specific configuration hook ================================ A standard way to reference user-specific modules. As a policy, Python doesn't run user-specified code on startup of Python programs. (Only interactive sessions execute the script specified in the `PYTHONSTARTUP' environment variable if it exists). However, some programs or sites may find it convenient to allow users to have a standard customization file, which gets run when a program requests it. This module implements such a mechanism. A program that wishes to use the mechanism must execute the statement import user The `user' module looks for a file `.pythonrc.py' in the user's home directory and if it can be opened, exececutes it (using `execfile()') in its own (i.e. the module `user''s) global namespace. Errors during this phase are not caught; that's up to the program that imports the `user' module, if it wishes. The home directory is assumed to be named by the `HOME' environment variable; if this is not set, the current directory is used. The user's `.pythonrc.py' could conceivably test for `sys.version' if it wishes to do different things depending on the Python version. A warning to users: be very conservative in what you place in your `.pythonrc.py' file. Since you don't know which programs will use it, changing the behavior of standard modules or functions is generally not a good idea. A suggestion for programmers who wish to use this mechanism: a simple way to let users specify options for your package is to have them define variables in their `.pythonrc.py' file that you test in your module. For example, a module `spam' that has a verbosity level can look for a variable `user.spam_verbose', as follows: import user try: verbose = user.spam_verbose # user's verbosity preference except AttributeError: verbose = 0 # default verbosity Programs with extensive customization needs are better off reading a program-specific customization file. Programs with security or privacy concerns should *not* import this module; a user can easily break into a program by placing arbitrary code in the `.pythonrc.py' file. Modules for general use should *not* import this module; it may interfere with the operation of the importing program. See also: *Note site:: site-wide customization mechanism  File: python-lib.info, Node: __builtin__, Next: __main__, Prev: user, Up: Python Services Built-in functions ================== The set of built-in functions. This module provides direct access to all `built-in' identifiers of Python; e.g. `__builtin__.open' is the full name for the built-in function `open()'. See section *Note traceback::, "Built-in Functions."  File: python-lib.info, Node: __main__, Prev: __builtin__, Up: Python Services Top-level script environment. ============================= The environment where the top-level script is run. This module represents the (otherwise anonymous) scope in which the interpreter's main program executes -- commands read either from standard input or from a script file.  File: python-lib.info, Node: String Services, Next: Miscellaneous Services, Prev: Python Services, Up: Top String Services *************** The modules described in this chapter provide a wide range of string manipulation operations. Here's an overview: * Menu: * string:: * re:: * regex:: * regsub:: * struct:: * fpformat:: * StringIO:: * cStringIO::  File: python-lib.info, Node: string, Next: re, Prev: String Services, Up: String Services Common string operations ======================== Common string operations. This module defines some constants useful for checking character classes and some useful string functions. See the module `re' for string functions based on regular expressions. The constants defined in this module are are: `digits' The string `'0123456789''. `hexdigits' The string `'0123456789abcdefABCDEF''. `letters' The concatenation of the strings `lowercase()' and `uppercase()' described below. `lowercase' A string containing all the characters that are considered lowercase letters. On most systems this is the string `'abcdefghijklmnopqrstuvwxyz''. Do not change its definition -- the effect on the routines `upper()' and `swapcase()' is undefined. `octdigits' The string `'01234567''. `uppercase' A string containing all the characters that are considered uppercase letters. On most systems this is the string `'ABCDEFGHIJKLMNOPQRSTUVWXYZ''. Do not change its definition -- the effect on the routines `lower()' and `swapcase()' is undefined. `whitespace' A string containing all characters that are considered whitespace. On most systems this includes the characters space, tab, linefeed, return, formfeed, and vertical tab. Do not change its definition -- the effect on the routines `strip()' and `split()' is undefined. The functions defined in this module are: `atof(s)' Convert a string to a floating point number. The string must have the standard syntax for a floating point literal in Python, optionally preceded by a sign (`+' or `-'). Note that this behaves identical to the built-in function `float()' when passed a string. *Note:* When passing in a string, values for NaNand Infinity may be returned, depending on the underlying C library. The specific set of strings accepted which cause these values to be returned depends entirely on the C library and is known to vary. `atoi(s[, base])' Convert string S to an integer in the given BASE. The string must consist of one or more digits, optionally preceded by a sign (`+' or `-'). The BASE defaults to 10. If it is 0, a default base is chosen depending on the leading characters of the string (after stripping the sign): `0x' or `0X' means 16, `0' means 8, anything else means 10. If BASE is 16, a leading `0x' or `0X' is always accepted. Note that when invoked without BASE or with BASE set to 10, this behaves identical to the built-in function `int()' when passed a string. (Also note: for a more flexible interpretation of numeric literals, use the built-in function `eval()'.) `atol(s[, base])' Convert string S to a long integer in the given BASE. The string must consist of one or more digits, optionally preceded by a sign (`+' or `-'). The BASE argument has the same meaning as for `atoi()'. A trailing `l' or `L' is not allowed, except if the base is 0. Note that when invoked without BASE or with BASE set to 10, this behaves identical to the built-in function `long()' when passed a string. `capitalize(word)' Capitalize the first character of the argument. `capwords(s)' Split the argument into words using `split()', capitalize each word using `capitalize()', and join the capitalized words using `join()'. Note that this replaces runs of whitespace characters by a single space, and removes leading and trailing whitespace. `expandtabs(s, [tabsize])' Expand tabs in a string, i.e. replace them by one or more spaces, depending on the current column and the given tab size. The column number is reset to zero after each newline occurring in the string. This doesn't understand other non-printing characters or escape sequences. The tab size defaults to 8. `find(s, sub[, start[,end]])' Return the lowest index in S where the substring SUB is found such that SUB is wholly contained in `S[START:END]'. Return `-1' on failure. Defaults for START and END and interpretation of negative values is the same as for slices. `rfind(s, sub[, start[, end]])' Like `find()' but find the highest index. `index(s, sub[, start[, end]])' Like `find()' but raise `ValueError' when the substring is not found. `rindex(s, sub[, start[, end]])' Like `rfind()' but raise `ValueError' when the substring is not found. `count(s, sub[, start[, end]])' Return the number of (non-overlapping) occurrences of substring SUB in string `S[START:END]'. Defaults for START and END and interpretation of negative values is the same as for slices. `lower(s)' Return a copy of S, but with upper case letters converted to lower case. `maketrans(from, to)' Return a translation table suitable for passing to `translate()' or `regex.compile()', that will map each character in FROM into the character at the same position in TO; FROM and TO must have the same length. *Warning:* don't use strings derived from `lowercase' and `uppercase' as arguments; in some locales, these don't have the same length. For case conversions, always use `lower()' and `upper()'. `split(s[, sep[, maxsplit]])' Return a list of the words of the string S. If the optional second argument SEP is absent or `None', the words are separated by arbitrary strings of whitespace characters (space, tab, newline, return, formfeed). If the second argument SEP is present and not `None', it specifies a string to be used as the word separator. The returned list will then have one more item than the number of non-overlapping occurrences of the separator in the string. The optional third argument MAXSPLIT defaults to 0. If it is nonzero, at most MAXSPLIT number of splits occur, and the remainder of the string is returned as the final element of the list (thus, the list will have at most `MAXSPLIT+1' elements). `splitfields(s[, sep[, maxsplit]])' This function behaves identically to `split()'. (In the past, `split()' was only used with one argument, while `splitfields()' was only used with two arguments.) `join(words[, sep])' Concatenate a list or tuple of words with intervening occurrences of SEP. The default value for SEP is a single space character. It is always true that `string.join(string.split(S, SEP), SEP)' equals S. `joinfields(words[, sep])' This function behaves identical to `join()'. (In the past, `join()' was only used with one argument, while `joinfields()' was only used with two arguments.) `lstrip(s)' Return a copy of S but without leading whitespace characters. `rstrip(s)' Return a copy of S but without trailing whitespace characters. `strip(s)' Return a copy of S without leading or trailing whitespace. `swapcase(s)' Return a copy of S, but with lower case letters converted to upper case and vice versa. `translate(s, table[, deletechars])' Delete all characters from S that are in DELETECHARS (if present), and then translate the characters using TABLE, which must be a 256-character string giving the translation for each character value, indexed by its ordinal. `upper(s)' Return a copy of S, but with lower case letters converted to upper case. `ljust(s, width)' `rjust s, width' `center s, width' These functions respectively left-justify, right-justify and center a string in a field of given width. They return a string that is at least WIDTH characters wide, created by padding the string S with spaces until the given width on the right, left or both sides. The string is never truncated. `zfill(s, width)' Pad a numeric string on the left with zero digits until the given width is reached. Strings starting with a sign are handled correctly. `replace(str, old, new[, maxsplit])' Return a copy of string STR with all occurrences of substring OLD replaced by NEW. If the optional argument MAXSPLIT is given, the first MAXSPLIT occurrences are replaced. This module is implemented in Python. Much of its functionality has been reimplemented in the built-in module `strop'. However, you should *never* import the latter module directly. When `string' discovers that `strop' exists, it transparently replaces parts of itself with the implementation from `strop'. After initialization, there is *no* overhead in using `string' instead of `strop'.  File: python-lib.info, Node: re, Next: regex, Prev: string, Up: String Services Perl-style regular expression operations. ========================================= This module was documented by Andrew M. Kuchling . This section was written by Andrew M. Kuchling . Perl-style regular expression search and match operations. This module provides regular expression matching operations similar to those found in Perl. It's 8-bit clean: the strings being processed may contain both null bytes and characters whose high bit is set. Regular expression pattern strings may not contain null bytes, but can specify the null byte using the `\NUMBER' notation. Characters with the high bit set may be included. The `re' module is always available. Regular expressions use the backslash character (`\') to indicate special forms or to allow special characters to be used without invoking their special meaning. This collides with Python's usage of the same character for the same purpose in string literals; for example, to match a literal backslash, one might have to write `'\\\\'' as the pattern string, because the regular expression must be `\\', and each backslash must be expressed as `\\' inside a regular Python string literal. The solution is to use Python's raw string notation for regular expression patterns; backslashes are not handled in any special way in a string literal prefixed with `r'. So `r"\n"' is a two-character string containing `\' and `n', while `"\n"' is a one-character string containing a newline. Usually patterns will be expressed in Python code using this raw string notation. * Menu: * Regular Expression Syntax:: * Matching vs. Searching:: * Contents of Module re:: * Regular Expression Objects:: * Match Objects::