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: mimetools.Message Methods, Prev: mimetools, Up: mimetools Additional Methods of Message objects ------------------------------------- The `Message' class defines the following methods in addition to the `rfc822.Message' methods: `getplist()' Return the parameter list of the `content-type' header. This is a list if strings. For parameters of the form `KEY=VALUE', KEY is converted to lower case but VALUE is not. For example, if the message contains the header `Content-type: text/html; spam=1; Spam=2; Spam' then `getplist()' will return the Python list `['spam=1', 'spam=2', 'Spam']'. `getparam(name)' Return the VALUE of the first parameter (as returned by `getplist()' of the form `NAME=VALUE' for the given NAME. If VALUE is surrounded by quotes of the form ``<'...`>'' or ``"'...`"'', these are removed. `getencoding()' Return the encoding specified in the `content-transfer-encoding' message header. If no such header exists, return `'7bit''. The encoding is converted to lower case. `gettype()' Return the message type (of the form `TYPE/SUBTYPE') as specified in the `content-type' header. If no such header exists, return `'text/plain''. The type is converted to lower case. `getmaintype()' Return the main type as specified in the `content-type' header. If no such header exists, return `'text''. The main type is converted to lower case. `getsubtype()' Return the subtype as specified in the `content-type' header. If no such header exists, return `'plain''. The subtype is converted to lower case.  File: python-lib.info, Node: MimeWriter, Next: multifile, Prev: mimetools, Up: Internet Data Handling Generic MIME file writer ======================== Generic MIME file writer. This section was written by Christopher G. Petrilli . This module defines the class `MimeWriter'. The `MimeWriter' class implements a basic formatter for creating MIME multi-part files. It doesn't seek around the output file nor does it use large amounts of buffer space. You must write the parts out in the order that they should occur in the final file. `MimeWriter' does buffer the headers you add, allowing you to rearrange their order. `MimeWriter(fp)' Return a new instance of the `MimeWriter' class. The only argument passed, FP, is a file object to be used for writing. Note that a `StringIO' object could also be used. * Menu: * MimeWriter Objects::  File: python-lib.info, Node: MimeWriter Objects, Prev: MimeWriter, Up: MimeWriter MimeWriter Objects ------------------ `MimeWriter' instances have the following methods: `addheader(key, value[, prefix])' Add a header line to the MIME message. The KEY is the name of the header, where the VALUE obviously provides the value of the header. The optional argument PREFIX determines where the header is inserted; `0' means append at the end, `1' is insert at the start. The default is to append. `flushheaders()' Causes all headers accumulated so far to be written out (and forgotten). This is useful if you don't need a body part at all, e.g. for a subpart of type `message/rfc822' that's (mis)used to store some header-like information. `startbody(ctype[, plist[, prefix]])' Returns a file-like object which can be used to write to the body of the message. The content-type is set to the provided CTYPE, and the optional parameter PLIST provides additional parameters for the content-type declaration. PREFIX functions as in `addheader()' except that the default is to insert at the start. `startmultipartbody(subtype[, boundary[, plist[, prefix]]])' Returns a file-like object which can be used to write to the body of the message. Additionally, this method initializes the multi-part code, where SUBTYPE provides the mutlipart subtype, BOUNDARY may provide a user-defined boundary specification, and PLIST provides optional parameters for the subtype. PREFIX functions as in `startbody()'. Subparts should be created using `nextpart()'. `nextpart()' Returns a new instance of `MimeWriter' which represents an individual part in a multipart message. This may be used to write the part as well as used for creating recursively complex multipart messages. The message must first be initialized with `startmultipartbody()' before using `nextpart()'. `lastpart()' This is used to designate the last part of a multipart message, and should *always* be used when writing multipart messages.  File: python-lib.info, Node: multifile, Next: binhex, Prev: MimeWriter, Up: Internet Data Handling Support for files containing distinct parts =========================================== Support for reading files which contain distinct parts, such as some MIME data. This section was written by Eric S. Raymond . The `MultiFile' object enables you to treat sections of a text file as file-like input objects, with `''' being returned by `readline()' when a given delimiter pattern is encountered. The defaults of this class are designed to make it useful for parsing MIME multipart messages, but by subclassing it and overriding methods it can be easily adapted for more general use. `MultiFile(fp[, seekable])' Create a multi-file. You must instantiate this class with an input object argument for the `MultiFile' instance to get lines from, such as as a file object returned by `open()'. `MultiFile' only ever looks at the input object's `readline()', `seek()' and `tell()' methods, and the latter two are only needed if you want random access to the individual MIME parts. To use `MultiFile' on a non-seekable stream object, set the optional SEEKABLE argument to false; this will prevent using the input object's `seek()' and `tell()' methods. It will be useful to know that in `MultiFile''s view of the world, text is composed of three kinds of lines: data, section-dividers, and end-markers. MultiFile is designed to support parsing of messages that may have multiple nested message parts, each with its own pattern for section-divider and end-marker lines. * Menu: * MultiFile Objects:: * MultiFile Example::  File: python-lib.info, Node: MultiFile Objects, Next: MultiFile Example, Prev: multifile, Up: multifile MultiFile Objects ----------------- A `MultiFile' instance has the following methods: `push(str)' Push a boundary string. When an appropriately decorated version of this boundary is found as an input line, it will be interpreted as a section-divider or end-marker. All subsequent reads will return the empty string to indicate end-of-file, until a call to `pop()' removes the boundary a or `next()' call reenables it. It is possible to push more than one boundary. Encountering the most-recently-pushed boundary will return EOF; encountering any other boundary will raise an error. `readline(str)' Read a line. If the line is data (not a section-divider or end-marker or real EOF) return it. If the line matches the most-recently-stacked boundary, return `''' and set `self.last' to 1 or 0 according as the match is or is not an end-marker. If the line matches any other stacked boundary, raise an error. On encountering end-of-file on the underlying stream object, the method raises `Error' unless all boundaries have been popped. `readlines(str)' Return all lines remaining in this part as a list of strings. `read()' Read all lines, up to the next section. Return them as a single (multiline) string. Note that this doesn't take a size argument! `next()' Skip lines to the next section (that is, read lines until a section-divider or end-marker has been consumed). Return true if there is such a section, false if an end-marker is seen. Re-enable the most-recently-pushed boundary. `pop()' Pop a section boundary. This boundary will no longer be interpreted as EOF. `seek(pos[, whence])' Seek. Seek indices are relative to the start of the current section. The POS and WHENCE arguments are interpreted as for a file seek. `tell()' Return the file position relative to the start of the current section. `is_data(str)' Return true if STR is data and false if it might be a section boundary. As written, it tests for a prefix other than `'-'`-'' at start of line (which all MIME boundaries have) but it is declared so it can be overridden in derived classes. Note that this test is used intended as a fast guard for the real boundary tests; if it always returns false it will merely slow processing, not cause it to fail. `section_divider(str)' Turn a boundary into a section-divider line. By default, this method prepends `'-'`-'' (which MIME section boundaries have) but it is declared so it can be overridden in derived classes. This method need not append LF or CR-LF, as comparison with the result ignores trailing whitespace. `end_marker(str)' Turn a boundary string into an end-marker line. By default, this method prepends `'-'`-'' and appends `'-'`-'' (like a MIME-multipart end-of-message marker) but it is declared so it can be be overridden in derived classes. This method need not append LF or CR-LF, as comparison with the result ignores trailing whitespace. Finally, `MultiFile' instances have two public instance variables: `level' Nesting depth of the current part. `last' True if the last end-of-file was for an end-of-message marker.  File: python-lib.info, Node: MultiFile Example, Prev: MultiFile Objects, Up: multifile `MultiFile' Example ------------------- fp = MultiFile(sys.stdin, 0) fp.push(outer_boundary) message1 = fp.readlines() # We should now be either at real EOF or stopped on a message # boundary. Re-enable the outer boundary. fp.next() # Read another message with the same delimiter message2 = fp.readlines() # Re-enable that delimiter again fp.next() # Now look for a message subpart with a different boundary fp.push(inner_boundary) sub_header = fp.readlines() # If no exception has been thrown, we're looking at the start of # the message subpart. Reset and grab the subpart fp.next() sub_body = fp.readlines() # Got it. Now pop the inner boundary to re-enable the outer one. fp.pop() # Read to next outer boundary message3 = fp.readlines()  File: python-lib.info, Node: binhex, Next: uu, Prev: multifile, Up: Internet Data Handling Encode and decode binhex4 files =============================== Encode and decode files in binhex4 format. This module encodes and decodes files in binhex4 format, a format allowing representation of Macintosh files in ASCII. On the Macintosh, both forks of a file and the finder information are encoded (or decoded), on other platforms only the data fork is handled. The `binhex' module defines the following functions: `binhex(input, output)' Convert a binary file with filename INPUT to binhex file OUTPUT. The OUTPUT parameter can either be a filename or a file-like object (any object supporting a `write()' and `close()' method). `hexbin(input[, output])' Decode a binhex file INPUT. INPUT may be a filename or a file-like object supporting `read()' and `close()' methods. The resulting file is written to a file named OUTPUT, unless the argument is omitted in which case the output filename is read from the binhex file. See also: *Note binascii:: support module containing ASCII-to-binary and binary-to-ASCII conversions * Menu: * Notes::  File: python-lib.info, Node: Notes, Prev: binhex, Up: binhex Notes ----- There is an alternative, more powerful interface to the coder and decoder, see the source for details. If you code or decode textfiles on non-Macintosh platforms they will still use the Macintosh newline convention (carriage-return as end of line). As of this writing, `hexbin()' appears to not work in all cases.  File: python-lib.info, Node: uu, Next: binascii, Prev: binhex, Up: Internet Data Handling Encode and decode uuencode files ================================ Encode and decode files in uuencode format. This module was documented by Lance Ellinghouse <>. This module encodes and decodes files in uuencode format, allowing arbitrary binary data to be transferred over ascii-only connections. Wherever a file argument is expected, the methods accept a file-like object. For backwards compatibility, a string containing a pathname is also accepted, and the corresponding file will be opened for reading and writing; the pathname `'-'' is understood to mean the standard input or output. However, this interface is deprecated; it's better for the caller to open the file itself, and be sure that, when required, the mode is `'rb'' or `'wb'' on Windows or DOS. This code was contributed by Lance Ellinghouse, and modified by Jack Jansen. The `uu' module defines the following functions: `encode(in_file, out_file[, name[, mode]])' Uuencode file IN_FILE into file OUT_FILE. The uuencoded file will have the header specifying NAME and MODE as the defaults for the results of decoding the file. The default defaults are taken from IN_FILE, or `'-'' and `0666' respectively. `decode(in_file[, out_file[, mode]])' This call decodes uuencoded file IN_FILE placing the result on file OUT_FILE. If OUT_FILE is a pathname, MODE is used to set the permission bits if the file must be created. Defaults for OUT_FILE and MODE are taken from the uuencode header. See also: *Note binascii:: support module containing ASCII-to-binary and binary-to-ASCII conversions  File: python-lib.info, Node: binascii, Next: xdrlib, Prev: uu, Up: Internet Data Handling Convert between binary and ASCII ================================ Tools for converting between binary and various ASCII-encoded binary representations. The `binascii' module contains a number of methods to convert between binary and various ASCII-encoded binary representations. Normally, you will not use these functions directly but use wrapper modules like `uu' or `binhex' instead, this module solely exists because bit-manipuation of large amounts of data is slow in Python. The `binascii' module defines the following functions: `a2b_uu(string)' Convert a single line of uuencoded data back to binary and return the binary data. Lines normally contain 45 (binary) bytes, except for the last line. Line data may be followed by whitespace. `b2a_uu(data)' Convert binary data to a line of ASCII characters, the return value is the converted line, including a newline char. The length of DATA should be at most 45. `a2b_base64(string)' Convert a block of base64 data back to binary and return the binary data. More than one line may be passed at a time. `b2a_base64(data)' Convert binary data to a line of ASCII characters in base64 coding. The return value is the converted line, including a newline char. The length of DATA should be at most 57 to adhere to the base64 standard. `a2b_hqx(string)' Convert binhex4 formatted ASCII data to binary, without doing RLE-decompression. The string should contain a complete number of binary bytes, or (in case of the last portion of the binhex4 data) have the remaining bits zero. `rledecode_hqx(data)' Perform RLE-decompression on the data, as per the binhex4 standard. The algorithm uses `0x90' after a byte as a repeat indicator, followed by a count. A count of `0' specifies a byte value of `0x90'. The routine returns the decompressed data, unless data input data ends in an orphaned repeat indicator, in which case the `Incomplete' exception is raised. `rlecode_hqx(data)' Perform binhex4 style RLE-compression on DATA and return the result. `b2a_hqx(data)' Perform hexbin4 binary-to-ASCII translation and return the resulting string. The argument should already be RLE-coded, and have a length divisible by 3 (except possibly the last fragment). `crc_hqx(data, crc)' Compute the binhex4 crc value of DATA, starting with an initial CRC and returning the result. `Error' Exception raised on errors. These are usually programming errors. `Incomplete' Exception raised on incomplete data. These are usually not programming errors, but may be handled by reading a little more data and trying again. See also: *Note base64:: support for base64 encoding used in MIME email messages *Note binhex:: support for the binhex format used on the Macintosh *Note uu:: support for UU encoding used on UNIX  File: python-lib.info, Node: xdrlib, Next: mailcap, Prev: binascii, Up: Internet Data Handling Encode and decode XDR data. =========================== Encoders and decoders for the External Data Representation (XDR). The `xdrlib' module supports the External Data Representation Standard as described in RFC 1014, written by Sun Microsystems, Inc. June 1987. It supports most of the data types described in the RFC. The `xdrlib' module defines two classes, one for packing variables into XDR representation, and another for unpacking from XDR representation. There are also two exception classes. `Packer()' `Packer' is the class for packing data into XDR representation. The `Packer' class is instantiated with no arguments. `Unpacker(data)' `Unpacker' is the complementary class which unpacks XDR data values from a string buffer. The input buffer is given as DATA. * Menu: * Packer Objects:: * Unpacker Objects:: * Exceptions::  File: python-lib.info, Node: Packer Objects, Next: Unpacker Objects, Prev: xdrlib, Up: xdrlib Packer Objects -------------- `Packer' instances have the following methods: `get_buffer()' Returns the current pack buffer as a string. `reset()' Resets the pack buffer to the empty string. In general, you can pack any of the most common XDR data types by calling the appropriate `pack_TYPE()' method. Each method takes a single argument, the value to pack. The following simple data type packing methods are supported: `pack_uint()', `pack_int()', `pack_enum()', `pack_bool()', `pack_uhyper()', and `pack_hyper()'. `pack_float(value)' Packs the single-precision floating point number VALUE. `pack_double(value)' Packs the double-precision floating point number VALUE. The following methods support packing strings, bytes, and opaque data: `pack_fstring(n, s)' Packs a fixed length string, S. N is the length of the string but it is *not* packed into the data buffer. The string is padded with null bytes if necessary to guaranteed 4 byte alignment. `pack_fopaque(n, data)' Packs a fixed length opaque data stream, similarly to `pack_fstring()'. `pack_string(s)' Packs a variable length string, S. The length of the string is first packed as an unsigned integer, then the string data is packed with `pack_fstring()'. `pack_opaque(data)' Packs a variable length opaque data string, similarly to `pack_string()'. `pack_bytes(bytes)' Packs a variable length byte stream, similarly to `pack_string()'. The following methods support packing arrays and lists: `pack_list(list, pack_item)' Packs a LIST of homogeneous items. This method is useful for lists with an indeterminate size; i.e. the size is not available until the entire list has been walked. For each item in the list, an unsigned integer `1' is packed first, followed by the data value from the list. PACK_ITEM is the function that is called to pack the individual item. At the end of the list, an unsigned integer `0' is packed. For example, to pack a list of integers, the code might appear like this: import xdrlib p = xdrlib.Packer() p.pack_list([1, 2, 3], p.pack_int) `pack_farray(n, array, pack_item)' Packs a fixed length list (ARRAY) of homogeneous items. N is the length of the list; it is *not* packed into the buffer, but a `ValueError' exception is raised if `len(ARRAY)' is not equal to N. As above, PACK_ITEM is the function used to pack each element. `pack_array(list, pack_item)' Packs a variable length LIST of homogeneous items. First, the length of the list is packed as an unsigned integer, then each element is packed as in `pack_farray()' above.  File: python-lib.info, Node: Unpacker Objects, Next: Exceptions, Prev: Packer Objects, Up: xdrlib Unpacker Objects ---------------- The `Unpacker' class offers the following methods: `reset(data)' Resets the string buffer with the given DATA. `get_position()' Returns the current unpack position in the data buffer. `set_position(position)' Sets the data buffer unpack position to POSITION. You should be careful about using `get_position()' and `set_position()'. `get_buffer()' Returns the current unpack data buffer as a string. `done()' Indicates unpack completion. Raises an `Error' exception if all of the data has not been unpacked. In addition, every data type that can be packed with a `Packer', can be unpacked with an `Unpacker'. Unpacking methods are of the form `unpack_TYPE()', and take no arguments. They return the unpacked object. `unpack_float()' Unpacks a single-precision floating point number. `unpack_double()' Unpacks a double-precision floating point number, similarly to `unpack_float()'. In addition, the following methods unpack strings, bytes, and opaque data: `unpack_fstring(n)' Unpacks and returns a fixed length string. N is the number of characters expected. Padding with null bytes to guaranteed 4 byte alignment is assumed. `unpack_fopaque(n)' Unpacks and returns a fixed length opaque data stream, similarly to `unpack_fstring()'. `unpack_string()' Unpacks and returns a variable length string. The length of the string is first unpacked as an unsigned integer, then the string data is unpacked with `unpack_fstring()'. `unpack_opaque()' Unpacks and returns a variable length opaque data string, similarly to `unpack_string()'. `unpack_bytes()' Unpacks and returns a variable length byte stream, similarly to `unpack_string()'. The following methods support unpacking arrays and lists: `unpack_list(unpack_item)' Unpacks and returns a list of homogeneous items. The list is unpacked one element at a time by first unpacking an unsigned integer flag. If the flag is `1', then the item is unpacked and appended to the list. A flag of `0' indicates the end of the list. UNPACK_ITEM is the function that is called to unpack the items. `unpack_farray(n, unpack_item)' Unpacks and returns (as a list) a fixed length array of homogeneous items. N is number of list elements to expect in the buffer. As above, UNPACK_ITEM is the function used to unpack each element. `unpack_array(unpack_item)' Unpacks and returns a variable length LIST of homogeneous items. First, the length of the list is unpacked as an unsigned integer, then each element is unpacked as in `unpack_farray()' above.  File: python-lib.info, Node: Exceptions, Prev: Unpacker Objects, Up: xdrlib Exceptions ---------- Exceptions in this module are coded as class instances: `Error' The base exception class. `Error' has a single public data member `msg' containing the description of the error. `ConversionError' Class derived from `Error'. Contains no additional instance variables. Here is an example of how you would catch one of these exceptions: import xdrlib p = xdrlib.Packer() try: p.pack_double(8.01) except xdrlib.ConversionError, instance: print 'packing the double failed:', instance.msg  File: python-lib.info, Node: mailcap, Next: mimetypes, Prev: xdrlib, Up: Internet Data Handling Mailcap file handling. ====================== Mailcap file handling. Mailcap files are used to configure how MIME-aware applications such as mail readers and Web browsers react to files with different MIME types. (The name "mailcap" is derived from the phrase "mail capability".) For example, a mailcap file might contain a line like `video/mpeg; xmpeg %s'. Then, if the user encounters an email message or Web document with the MIME type `video/mpeg', `%s' will be replaced by a filename (usually one belonging to a temporary file) and the `xmpeg' program can be automatically started to view the file. The mailcap format is documented in RFC 1524, "A User Agent Configuration Mechanism For Multimedia Mail Format Information," but is not an Internet standard. However, mailcap files are supported on most UNIX systems. `findmatch(caps, MIMEtype [, key[, filename[, plist]]])' Return a 2-tuple; the first element is a string containing the command line to be executed (which can be passed to `os.system()'), and the second element is the mailcap entry for a given MIME type. If no matching MIME type can be found, `(None, None)' is returned. KEY is the name of the field desired, which represents the type of activity to be performed; the default value is 'view', since in the most common case you simply want to view the body of the MIME-typed data. Other possible values might be 'compose' and 'edit', if you wanted to create a new body of the given MIME type or alter the existing body data. See RFC 1524 for a complete list of these fields. FILENAME is the filename to be substituted for `%s' in the command line; the default value is `'/dev/null'' which is almost certainly not what you want, so usually you'll override it by specifying a filename. PLIST can be a list containing named parameters; the default value is simply an empty list. Each entry in the list must be a string containing the parameter name, an equals sign (`='), and the parameter's value. Mailcap entries can contain named parameters like `%{foo}', which will be replaced by the value of the parameter named 'foo'. For example, if the command line `showpartial %{id} %{number} %{total}' was in a mailcap file, and PLIST was set to `['id=1', 'number=2', 'total=3']', the resulting command line would be `"showpartial 1 2 3"'. In a mailcap file, the "test" field can optionally be specified to test some external condition (e.g., the machine architecture, or the window system in use) to determine whether or not the mailcap line applies. `findmatch()' will automatically check such conditions and skip the entry if the check fails. `getcaps()' Returns a dictionary mapping MIME types to a list of mailcap file entries. This dictionary must be passed to the `findmatch()' function. An entry is stored as a list of dictionaries, but it shouldn't be necessary to know the details of this representation. The information is derived from all of the mailcap files found on the system. Settings in the user's mailcap file `$HOME/.mailcap' will override settings in the system mailcap files `/etc/mailcap', `/usr/etc/mailcap', and `/usr/local/etc/mailcap'. An example usage: >>> import mailcap >>> d=mailcap.getcaps() >>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223') ('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'})  File: python-lib.info, Node: mimetypes, Next: base64, Prev: mailcap, Up: Internet Data Handling Map filenames to MIME types =========================== Mapping of filename extensions to MIME types. This section was written by Fred L. Drake, Jr. . The `mimetypes' converts between a filename or URL and the MIME type associated with the filename extension. Conversions are provided from filename to MIME type and from MIME type to filename extension; encodings are not supported for the later conversion. The functions described below provide the primary interface for this module. If the module has not been initialized, they will call `init()'. `guess_type(filename)' Guess the type of a file based on its filename or URL, given by FILENAME. The return value is a tuple `(TYPE, ENCODING)' where TYPE is `None' if the type can't be guessed (no or unknown suffix) or a string of the form `'TYPE/SUBTYPE'', usable for a MIME `content-type' header; and encoding is `None' for no encoding or the name of the program used to encode (e.g. `compress' or `gzip'). The encoding is suitable for use as a `content-encoding' header, *not* as a `content-transfer-encoding' header. The mappings are table driven. Encoding suffixes are case sensitive; type suffixes are first tried case sensitive, then case insensitive. `guess_extension(type)' Guess the extension for a file based on its MIME type, given by TYPE. The return value is a string giving a filename extension, including the leading dot (`.'). The extension is not guaranteed to have been associated with any particular data stream, but would be mapped to the MIME type TYPE by `guess_type()'. If no extension can be guessed for TYPE, `None' is returned. Some additional functions and data items are available for controlling the behavior of the module. `init([files])' Initialize the internal data structures. If given, FILES must be a sequence of file names which should be used to augment the default type map. If omitted, the file names to use are taken from `knownfiles'. Each file named in FILES or `knownfiles' takes precedence over those named before it. Calling `init()' repeatedly is allowed. `read_mime_types(filename)' Load the type map given in the file FILENAME, if it exists. The type map is returned as a dictionary mapping filename extensions, including the leading dot (`.'), to strings of the form `'TYPE/SUBTYPE''. If the file FILENAME does not exist or cannot be read, `None' is returned. `inited' Flag indicating whether or not the global data structures have been initialized. This is set to true by `init()'. `knownfiles' List of type map file names commonly installed. These files are typically named `mime.types' and are installed in different locations by different packages. `suffix_map' Dictionary mapping suffixes to suffixes. This is used to allow recognition of encoded files for which the encoding and the type are indicated by the same extension. For example, the `.tgz' extension is mapped to `.tar.gz' to allow the encoding and type to be recognized separately. `encodings_map' Dictionary mapping filename extensions to encoding types. `types_map' Dictionary mapping filename extensions to MIME types.  File: python-lib.info, Node: base64, Next: quopri, Prev: mimetypes, Up: Internet Data Handling Encode and decode MIME base64 data ================================== Encode and decode files using the MIME base64 data. This module performs base64 encoding and decoding of arbitrary binary strings into text strings that can be safely emailed or posted. The encoding scheme is defined in RFC 1421 ("Privacy Enhancement for Internet Electronic Mail: Part I: Message Encryption and Authentication Procedures", section 4.3.2.4, "Step 4: Printable Encoding") and is used for MIME email and various other Internet-related applications; it is not the same as the output produced by the `uuencode' program. For example, the string `'www.python.org'' is encoded as the string `'d3d3LnB5dGhvbi5vcmc=\n''. `decode(input, output)' Decode the contents of the INPUT file and write the resulting binary data to the OUTPUT file. INPUT and OUTPUT must either be file objects or objects that mimic the file object interface. INPUT will be read until `INPUT.read()' returns an empty string. `decodestring(s)' Decode the string S, which must contain one or more lines of base64 encoded data, and return a string containing the resulting binary data. `encode(input, output)' Encode the contents of the INPUT file and write the resulting base64 encoded data to the OUTPUT file. INPUT and OUTPUT must either be file objects or objects that mimic the file object interface. INPUT will be read until `INPUT.read()' returns an empty string. `encodestring(s)' Encode the string S, which can contain arbitrary binary data, and return a string containing one or more lines of base64 encoded data. See also: *Note binascii:: support module containing ASCII-to-binary and binary-to-ASCII conversions  File: python-lib.info, Node: quopri, Next: mailbox, Prev: base64, Up: Internet Data Handling Encode and decode MIME quoted-printable data ============================================ Encode and decode files using the MIME quoted-printable encoding. This module performs quoted-printable transport encoding and decoding, as defined in RFC 1521: "MIME (Multipurpose Internet Mail Extensions) Part One". The quoted-printable encoding is designed for data where there are relatively few nonprintable characters; the base64 encoding scheme available via the `base64' module is more compact if there are many such characters, as when sending a graphics file. `decode(input, output)' Decode the contents of the INPUT file and write the resulting decoded binary data to the OUTPUT file. INPUT and OUTPUT must either be file objects or objects that mimic the file object interface. INPUT will be read until `INPUT.read()' returns an empty string. `encode(input, output, quotetabs)' Encode the contents of the INPUT file and write the resulting quoted-printable data to the OUTPUT file. INPUT and OUTPUT must either be file objects or objects that mimic the file object interface. INPUT will be read until `INPUT.read()' returns an empty string.  File: python-lib.info, Node: mailbox, Next: mhlib, Prev: quopri, Up: Internet Data Handling Read various mailbox formats ============================ Read various mailbox formats. This module defines a number of classes that allow easy and uniform access to mail messages in a (UNIX) mailbox. `UnixMailbox(fp)' Access a classic UNIX-style mailbox, where all messages are contained in a single file and separated by "From name time" lines. The file object FP points to the mailbox file. `MmdfMailbox(fp)' Access an MMDF-style mailbox, where all messages are contained in a single file and separated by lines consisting of 4 control-A characters. The file object FP points to the mailbox file. `MHMailbox(dirname)' Access an MH mailbox, a directory with each message in a separate file with a numeric name. The name of the mailbox directory is passed in DIRNAME. `Maildir(dirname)' Access a Qmail mail directory. All new and current mail for the mailbox specified by DIRNAME is made available. `BabylMailbox(fp)' Access a Babyl mailbox, which is similar to an MMDF mailbox. Mail messages start with a line containing only `'*** EOOH ***'' and end with a line containing only `'\037\014''. * Menu: * Mailbox Objects::  File: python-lib.info, Node: Mailbox Objects, Prev: mailbox, Up: mailbox Mailbox Objects --------------- All implementations of Mailbox objects have one externally visible method: `next()' Return the next message in the mailbox, as a `rfc822.Message' object (see the `rfc822' module). Depending on the mailbox implementation the FP attribute of this object may be a true file object or a class instance simulating a file object, taking care of things like message boundaries if multiple mail messages are contained in a single file, etc.  File: python-lib.info, Node: mhlib, Next: mimify, Prev: mailbox, Up: Internet Data Handling Access to MH mailboxes ====================== Manipulate MH mailboxes from Python. The `mhlib' module provides a Python interface to MH folders and their contents. The module contains three basic classes, `MH', which represents a particular collection of folders, `Folder', which represents a single folder, and `Message', which represents a single message. `MH([path[, profile]])' `MH' represents a collection of MH folders. `Folder(mh, name)' The `Folder' class represents a single folder and its messages. `Message(folder, number[, name])' `Message' objects represent individual messages in a folder. The Message class is derived from `mimetools.Message'. * Menu: * MH Objects:: * Folder Objects:: * Message Objects 2::  File: python-lib.info, Node: MH Objects, Next: Folder Objects, Prev: mhlib, Up: mhlib MH Objects ---------- `MH' instances have the following methods: `error(format[, ...])' Print an error message - can be overridden. `getprofile(key)' Return a profile entry (`None' if not set). `getpath()' Return the mailbox pathname. `getcontext()' Return the current folder name. `setcontext(name)' Set the current folder name. `listfolders()' Return a list of top-level folders. `listallfolders()' Return a list of all folders. `listsubfolders(name)' Return a list of direct subfolders of the given folder. `listallsubfolders(name)' Return a list of all subfolders of the given folder. `makefolder(name)' Create a new folder. `deletefolder(name)' Delete a folder - must have no subfolders. `openfolder(name)' Return a new open folder object.  File: python-lib.info, Node: Folder Objects, Next: Message Objects 2, Prev: MH Objects, Up: mhlib Folder Objects -------------- `Folder' instances represent open folders and have the following methods: `error(format[, ...])' Print an error message - can be overridden. `getfullname()' Return the folder's full pathname. `getsequencesfilename()' Return the full pathname of the folder's sequences file. `getmessagefilename(n)' Return the full pathname of message N of the folder. `listmessages()' Return a list of messages in the folder (as numbers). `getcurrent()' Return the current message number. `setcurrent(n)' Set the current message number to N. `parsesequence(seq)' Parse msgs syntax into list of messages. `getlast()' Get last message, or `0' if no messages are in the folder. `setlast(n)' Set last message (internal use only). `getsequences()' Return dictionary of sequences in folder. The sequence names are used as keys, and the values are the lists of message numbers in the sequences. `putsequences(dict)' Return dictionary of sequences in folder {name: list}. `removemessages(list)' Remove messages in list from folder. `refilemessages(list, tofolder)' Move messages in list to other folder. `movemessage(n, tofolder, ton)' Move one message to a given destination in another folder. `copymessage(n, tofolder, ton)' Copy one message to a given destination in another folder.  File: python-lib.info, Node: Message Objects 2, Prev: Folder Objects, Up: mhlib Message Objects --------------- The `Message' class adds one method to those of `mimetools.Message': `openmessage(n)' Return a new open message object (costs a file descriptor).  File: python-lib.info, Node: mimify, Next: netrc, Prev: mhlib, Up: Internet Data Handling MIME processing of mail messages ================================ Mimification and unmimification of mail messages. The mimify module defines two functions to convert mail messages to and from MIME format. The mail message can be either a simple message or a so-called multipart message. Each part is treated separately. Mimifying (a part of) a message entails encoding the message as quoted-printable if it contains any characters that cannot be represented using 7-bit ASCII. Unmimifying (a part of) a message entails undoing the quoted-printable encoding. Mimify and unmimify are especially useful when a message has to be edited before being sent. Typical use would be: unmimify message edit message mimify message send message The modules defines the following user-callable functions and user-settable variables: `mimify(infile, outfile)' Copy the message in INFILE to OUTFILE, converting parts to quoted-printable and adding MIME mail headers when necessary. INFILE and OUTFILE can be file objects (actually, any object that has a `readline()' method (for INFILE) or a `write()' method (for OUTFILE)) or strings naming the files. If INFILE and OUTFILE are both strings, they may have the same value. `unmimify(infile, outfile[, decode_base64])' Copy the message in INFILE to OUTFILE, decoding all quoted-printable parts. INFILE and OUTFILE can be file objects (actually, any object that has a `readline()' method (for INFILE) or a `write()' method (for OUTFILE)) or strings naming the files. If INFILE and OUTFILE are both strings, they may have the same value. If the DECODE_BASE64 argument is provided and tests true, any parts that are coded in the base64 encoding are decoded as well. `mime_decode_header(line)' Return a decoded version of the encoded header line in LINE. `mime_encode_header(line)' Return a MIME-encoded version of the header line in LINE. `MAXLEN' By default, a part will be encoded as quoted-printable when it contains any non-ASCII characters (i.e., characters with the 8th bit set), or if there are any lines longer than `MAXLEN' characters (default value 200). `CHARSET' When not specified in the mail headers, a character set must be filled in. The string used is stored in `CHARSET', and the default value is ISO-8859-1 (also known as Latin1 (latin-one)). This module can also be used from the command line. Usage is as follows: mimify.py -e [-l length] [infile [outfile]] mimify.py -d [-b] [infile [outfile]] to encode (mimify) and decode (unmimify) respectively. INFILE defaults to standard input, OUTFILE defaults to standard output. The same file can be specified for input and output. If the *-l* option is given when encoding, if there are any lines longer than the specified LENGTH, the containing part will be encoded. If the *-b* option is given when decoding, any base64 parts will be decoded as well.  File: python-lib.info, Node: netrc, Prev: mimify, Up: Internet Data Handling netrc file processing ===================== Loading of `.netrc' files. This module was documented by Eric S. Raymond . This section was written by Eric S. Raymond . *Added in Python version 1.5.2* The `netrc' class parses and encapsulates the netrc file format used by the UNIX `ftp' program and other FTP clients. `netrc([file])' A `netrc' instance or subclass instance enapsulates data from a netrc file. The initialization argument, if present, specifies the file to parse. If no argument is given, the file `.netrc' in the user's home directory will be read. Parse errors will raise `SyntaxError' with diagnostic information including the file name, line number, and terminating token. * Menu: * netrc Objects::  File: python-lib.info, Node: netrc Objects, Prev: netrc, Up: netrc netrc Objects ------------- A `netrc' instance has the following methods: `authenticators(host)' Return a 3-tuple `(LOGIN, ACCOUNT, PASSWORD)' of authenticators for HOST. If the netrc file did not contain an entry for the given host, return the tuple associated with the `default' entry. If neither matching host nor default entry is available, return `None'. `__repr__()' Dump the class data as a string in the format of a netrc file. (This discards comments and may reorder the entries.) Instances of `netrc' have public instance variables: `hosts' Dictionmary mapping host names to `(LOGIN, ACCOUNT, PASSWORD)' tuples. The `default' entry, if any, is represented as a pseudo-host by that name. `macros' Dictionary mapping macro names to string lists.  File: python-lib.info, Node: Restricted Execution, Next: Multimedia Services, Prev: Internet Data Handling, Up: Top Restricted Execution ******************** In general, Python programs have complete access to the underlying operating system throug the various functions and classes, For example, a Python program can open any file for reading and writing by using the `open()' built-in function (provided the underlying OS gives you permission!). This is exactly what you want for most applications. There exists a class of applications for which this "openness" is inappropriate. Take Grail: a web browser that accepts "applets," snippets of Python code, from anywhere on the Internet for execution on the local system. This can be used to improve the user interface of forms, for instance. Since the originator of the code is unknown, it is obvious that it cannot be trusted with the full resources of the local machine. *Restricted execution* is the basic framework in Python that allows for the segregation of trusted and untrusted code. It is based on the notion that trusted Python code (a *supervisor*) can create a "padded cell' (or environment) with limited permissions, and run the untrusted code within this cell. The untrusted code cannot break out of its cell, and can only interact with sensitive system resources through interfaces defined and managed by the trusted code. The term "restricted execution" is favored over "safe-Python" since true safety is hard to define, and is determined by the way the restricted environment is created. Note that the restricted environments can be nested, with inner cells creating subcells of lesser, but never greater, privilege. An interesting aspect of Python's restricted execution model is that the interfaces presented to untrusted code usually have the same names as those presented to trusted code. Therefore no special interfaces need to be learned to write code designed to run in a restricted environment. And because the exact nature of the padded cell is determined by the supervisor, different restrictions can be imposed, depending on the application. For example, it might be deemed "safe" for untrusted code to read any file within a specified directory, but never to write a file. In this case, the supervisor may redefine the built-in `open()' function so that it raises an exception whenever the MODE parameter is `'w''. It might also perform a `chroot()'-like operation on the FILENAME parameter, such that root is always relative to some safe "sandbox" area of the filesystem. In this case, the untrusted code would still see an built-in `open()' function in its environment, with the same calling interface. The semantics would be identical too, with `IOError's being raised when the supervisor determined that an unallowable parameter is being used. The Python run-time determines whether a particular code block is executing in restricted execution mode based on the identity of the `__builtins__' object in its global variables: if this is (the dictionary of) the standard `__builtin__' module, the code is deemed to be unrestricted, else it is deemed to be restricted. Python code executing in restricted mode faces a number of limitations that are designed to prevent it from escaping from the padded cell. For instance, the function object attribute `func_globals' and the class and instance object attribute `__dict__' are unavailable. Two modules provide the framework for setting up restricted execution environments: See also: Andrew Kuchling, "Restricted Execution HOWTO." Available online at `http://www.python.org/doc/howto/rexec/'. Grail, an Internet browser written in Python, is available at `http://grail.cnri.reston.va.us/grail/'. More information on the use of Python's restricted execution mode in Grail is available on the Web site. * Menu: * rexec:: * Bastion::