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: Cookie, Next: asyncore, Prev: CGIHTTPServer, Up: Internet Protocols and Support HTTP state management ===================== Support for HTTP state management (cookies). This module was documented by Timothy O'Malley . This section was written by Moshe Zadka . The `Cookie' module defines classes for abstracting the concept of cookies, an HTTP state management mechanism. It supports both simple string-only cookies, and provides an abstraction for having any serializable data-type as cookie value. The module formerly strictly applied the parsing rules described in in the RFC 2109 and RFC 2068 specifications. It has since been discovered that MSIE 3.0x doesn't follow the character rules outlined in those specs. As a result, the parsing rules used are a bit less strict. `CookieError' Exception failing because of RFC 2109 invalidity: incorrect attributes, incorrect `Set-Cookie' header, etc. `BaseCookie([input])' This class is a dictionary-like object whose keys are strings and whose values are `Morsel's. Note that upon setting a key to a value, the value is first converted to a `Morsel' containing the key and the value. If INPUT is given, it is passed to the `load' method. `SimpleCookie([input])' This class derives from `BaseCookie' and overrides `value_decode' and `value_encode' to be the identity and `str()' respectively. `SerialCookie([input])' This class derives from `BaseCookie' and overrides `value_decode' and `value_encode' to be the `pickle.loads()' and `pickle.dumps'. Do not use this class. Reading pickled values from a cookie is a security hole, as arbitrary client-code can be run on `pickle.loads()'. It is supported for backwards compatibility. `SmartCookie([input])' This class derives from `BaseCookie'. It overrides `value_decode' to be `pickle.loads()' if it is a valid pickle, and otherwise the value itself. It overrides `value_encode' to be `pickle.dumps()' unless it is a string, in which case it returns the value itself. The same security warning from `SerialCookie' applies here. See also: *RFC2109 HTTP State Management Mechanism* This is the state management specification implemented by this module. * Menu: * Cookie Objects:: * Morsel Objects:: * Example 7::  File: python-lib.info, Node: Cookie Objects, Next: Morsel Objects, Prev: Cookie, Up: Cookie Cookie Objects -------------- `value_decode(val)' Return a decoded value from a string representation. Return value can be any type. This method does nothing in `BaseCookie' -- it exists so it can be overridden. `value_encode(val)' Return an encoded value. VAL can be any type, but return value must be a string. This method does nothing in `BaseCookie' -- it exists so it can be overridden In general, it should be the case that `value_encode' and `value_decode' are inverses on the range of VALUE_DECODE. `output([attrs[, header[, sep]]])' Return a string representation suitable to be sent as HTTP headers. ATTRS and HEADER are sent to each `Morsel''s `output' method. SEP is used to join the headers together, and is by default a newline. `js_output([attrs])' Return an embeddable JavaScript snippet, which, if run on a browser which supports JavaScript, will act the same as if the HTTP headers was sent. The meaning for ATTRS is the same as in `output()'. `load(rawdata)' If RAWDATA is a string, parse it as an `HTTP_COOKIE' and add the values found there as `Morsel's. If it is a dictionary, it is equivalent to: for k, v in rawdata.items(): cookie[k] = v  File: python-lib.info, Node: Morsel Objects, Next: Example 7, Prev: Cookie Objects, Up: Cookie Morsel Objects -------------- `Morsel()' Abstract a key/value pair, which has some RFC 2109 attributes. Morsels are dictionary-like objects, whose set of keys is constant -- the valid RFC 2109 attributes, which are * `expires' * `path' * `comment' * `domain' * `max-age' * `secure' * `version' The keys are case-insensitive. `value' The value of the cookie. `coded_value' The encoded value of the cookie -- this is what should be sent. `key' The name of the cookie. `set(key, value, coded_value)' Set the KEY, VALUE and CODED_VALUE members. `isReservedKey(K)' Whether K is a member of the set of keys of a `Morsel'. `output([attrs[, header]])' Return a string representation of the Morsel, suitable to be sent as an HTTP header. By default, all the attributes are included, unless ATTRS is given, in which case it should be a list of attributes to use. HEADER is by default `"Set-Cookie:"'. `js_output([attrs])' Return an embeddable JavaScript snippet, which, if run on a browser which supports JavaScript, will act the same as if the HTTP header was sent. The meaning for ATTRS is the same as in `output()'. `OutputString([attrs])' Return a string representing the Morsel, without any surrounding HTTP or JavaScript. The meaning for ATTRS is the same as in `output()'.  File: python-lib.info, Node: Example 7, Prev: Morsel Objects, Up: Cookie Example ------- The following example demonstrates how to use the `Cookie' module. >>> import Cookie >>> C = Cookie.SimpleCookie() >>> C = Cookie.SerialCookie() >>> C = Cookie.SmartCookie() >>> C = Cookie.Cookie() # backwards-compatible alias for SmartCookie >>> C = Cookie.SmartCookie() >>> C["fig"] = "newton" >>> C["sugar"] = "wafer" >>> print C # generate HTTP headers Set-Cookie: sugar=wafer; Set-Cookie: fig=newton; >>> print C.output() # same thing Set-Cookie: sugar=wafer; Set-Cookie: fig=newton; >>> C = Cookie.SmartCookie() >>> C["rocky"] = "road" >>> C["rocky"]["path"] = "/cookie" >>> print C.output(header="Cookie:") Cookie: rocky=road; Path=/cookie; >>> print C.output(attrs=[], header="Cookie:") Cookie: rocky=road; >>> C = Cookie.SmartCookie() >>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header) >>> print C Set-Cookie: vienna=finger; Set-Cookie: chips=ahoy; >>> C = Cookie.SmartCookie() >>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";') >>> print C Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"; >>> C = Cookie.SmartCookie() >>> C["oreo"] = "doublestuff" >>> C["oreo"]["path"] = "/" >>> print C Set-Cookie: oreo=doublestuff; Path=/; >>> C = Cookie.SmartCookie() >>> C["twix"] = "none for you" >>> C["twix"].value 'none for you' >>> C = Cookie.SimpleCookie() >>> C["number"] = 7 # equivalent to C["number"] = str(7) >>> C["string"] = "seven" >>> C["number"].value '7' >>> C["string"].value 'seven' >>> print C Set-Cookie: number=7; Set-Cookie: string=seven; >>> C = Cookie.SerialCookie() >>> C["number"] = 7 >>> C["string"] = "seven" >>> C["number"].value 7 >>> C["string"].value 'seven' >>> print C Set-Cookie: number="I7\012."; Set-Cookie: string="S'seven'\012p1\012."; >>> C = Cookie.SmartCookie() >>> C["number"] = 7 >>> C["string"] = "seven" >>> C["number"].value 7 >>> C["string"].value 'seven' >>> print C Set-Cookie: number="I7\012."; Set-Cookie: string=seven;  File: python-lib.info, Node: asyncore, Prev: Cookie, Up: Internet Protocols and Support Asynchronous socket handler =========================== A base class for developing asynchronous socket handling services. This module was documented by Sam Rushing . This section was written by Christopher Petrilli . This module provides the basic infrastructure for writing asynchronous socket service clients and servers. There are only two ways to have a program on a single processor do "more than one thing at a time." Multi-threaded programming is the simplest and most popular way to do it, but there is another very different technique, that lets you have nearly all the advantages of multi-threading, without actually using multiple threads. It's really only practical if your program is largely I/O bound. If your program is CPU bound, then pre-emptive scheduled threads are probably what you really need. Network servers are rarely CPU-bound, however. If your operating system supports the `select()' system call in its I/O library (and nearly all do), then you can use it to juggle multiple communication channels at once; doing other work while your I/O is taking place in the "background." Although this strategy can seem strange and complex, especially at first, it is in many ways easier to understand and control than multi-threaded programming. The module documented here solves many of the difficult problems for you, making the task of building sophisticated high-performance network servers and clients a snap. `dispatcher()' The first class we will introduce is the `dispatcher' class. This is a thin wrapper around a low-level socket object. To make it more useful, it has a few methods for event-handling on it. Otherwise, it can be treated as a normal non-blocking socket object. The direct interface between the select loop and the socket object are the `handle_read_event()' and `handle_write_event()' methods. These are called whenever an object `fires' that event. The firing of these low-level events can tell us whether certain higher-level events have taken place, depending on the timing and the state of the connection. For example, if we have asked for a socket to connect to another host, we know that the connection has been made when the socket fires a write event (at this point you know that you may write to it with the expectation of success). The implied higher-level events are: Event Description ------ ----- handle_connect() Implied by a write event handle_close() Implied by a read event with no data available handle_accept() Implied by a read event on a listening socket This set of user-level events is larger than the basics. The full set of methods that can be overridden in your subclass are: `handle_read()' Called when there is new data to be read from a socket. `handle_write()' Called when there is an attempt to write data to the object. Often this method will implement the necessary buffering for performance. For example: def handle_write(self): sent = self.send(self.buffer) self.buffer = self.buffer[sent:] `handle_expt()' Called when there is out of band (OOB) data for a socket connection. This will almost never happen, as OOB is tenuously supported and rarely used. `handle_connect()' Called when the socket actually makes a connection. This might be used to send a "welcome" banner, or something similar. `handle_close()' Called when the socket is closed. `handle_accept()' Called on listening sockets when they actually accept a new connection. `readable()' Each time through the `select()' loop, the set of sockets is scanned, and this method is called to see if there is any interest in reading. The default method simply returns `1', indicating that by default, all channels will be interested. `writable()' Each time through the `select()' loop, the set of sockets is scanned, and this method is called to see if there is any interest in writing. The default method simply returns `1', indicating that by default, all channels will be interested. In addition, there are the basic methods needed to construct and manipulate "channels," which are what we will call the socket connections in this context. Note that most of these are nearly identical to their socket partners. `create_socket(family, type)' This is identical to the creation of a normal socket, and will use the same options for creation. Refer to the `socket' documentation for information on creating sockets. `connect(address)' As with the normal socket object, ADDRESS is a tuple with the first element the host to connect to, and the second the port. `send(data)' Send DATA out the socket. `recv(buffer_size)' Read at most BUFFER_SIZE bytes from the socket. `listen([backlog])' Listen for connections made to the socket. The BACKLOG argument specifies the maximum number of queued connections and should be at least 1; the maximum value is system-dependent (usually 5). `bind(address)' Bind the socket to ADDRESS. The socket must not already be bound. (The format of ADDRESS depends on the address family -- see above.) `accept()' Accept a connection. The socket must be bound to an address and listening for connections. The return value is a pair `(CONN, ADDRESS)' where CONN is a _new_ socket object usable to send and receive data on the connection, and ADDRESS is the address bound to the socket on the other end of the connection. `close()' Close the socket. All future operations on the socket object will fail. The remote end will receive no more data (after queued data is flushed). Sockets are automatically closed when they are garbage-collected. * Menu: * Example basic HTTP client::  File: python-lib.info, Node: Example basic HTTP client, Prev: asyncore, Up: asyncore Example basic HTTP client ------------------------- As a basic example, below is a very basic HTTP client that uses the `dispatcher' class to implement its socket handling: class http_client(asyncore.dispatcher): def __init__(self, host,path): asyncore.dispatcher.__init__(self) self.path = path self.create_socket(socket.AF_INET, socket.SOCK_STREAM) self.connect( (host, 80) ) self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % self.path def handle_connect(self): pass def handle_read(self): data = self.recv(8192) print data def writable(self): return (len(self.buffer) > 0) def handle_write(self): sent = self.send(self.buffer) self.buffer = self.buffer[sent:]  File: python-lib.info, Node: Internet Data Handling, Next: Structured Markup Processing Tools, Prev: Internet Protocols and Support, Up: Top Internet Data Handling ********************** This chapter describes modules which support handling data formats commonly used on the internet. Some, like SGML and XML, may be useful for other applications as well. * Menu: * formatter:: * rfc822:: * mimetools:: * MimeWriter:: * multifile:: * binhex:: * uu:: * binascii:: * xdrlib:: * mailcap:: * mimetypes:: * base64:: * quopri:: * mailbox:: * mhlib:: * mimify:: * netrc:: * robotparser::  File: python-lib.info, Node: formatter, Next: rfc822, Prev: Internet Data Handling, Up: Internet Data Handling Generic output formatting ========================= Generic output formatter and device interface. This module supports two interface definitions, each with multiple implementations. The _formatter_ interface is used by the `HTMLParser' class of the `htmllib' module, and the _writer_ interface is required by the formatter interface. Formatter objects transform an abstract flow of formatting events into specific output events on writer objects. Formatters manage several stack structures to allow various properties of a writer object to be changed and restored; writers need not be able to handle relative changes nor any sort of "change back" operation. Specific writer properties which may be controlled via formatter objects are horizontal alignment, font, and left margin indentations. A mechanism is provided which supports providing arbitrary, non-exclusive style settings to a writer as well. Additional interfaces facilitate formatting events which are not reversible, such as paragraph separation. Writer objects encapsulate device interfaces. Abstract devices, such as file formats, are supported as well as physical devices. The provided implementations all work with abstract devices. The interface makes available mechanisms for setting the properties which formatter objects manage and inserting data into the output. * Menu: * Formatter Interface:: * Formatter Implementations:: * Writer Interface:: * Writer Implementations::  File: python-lib.info, Node: Formatter Interface, Next: Formatter Implementations, Prev: formatter, Up: formatter The Formatter Interface ----------------------- Interfaces to create formatters are dependent on the specific formatter class being instantiated. The interfaces described below are the required interfaces which all formatters must support once initialized. One data element is defined at the module level: `AS_IS' Value which can be used in the font specification passed to the `push_font()' method described below, or as the new value to any other `push_PROPERTY()' method. Pushing the `AS_IS' value allows the corresponding `pop_PROPERTY()' method to be called without having to track whether the property was changed. The following attributes are defined for formatter instance objects: `writer' The writer instance with which the formatter interacts. `end_paragraph(blanklines)' Close any open paragraphs and insert at least BLANKLINES before the next paragraph. `add_line_break()' Add a hard line break if one does not already exist. This does not break the logical paragraph. `add_hor_rule(*args, **kw)' Insert a horizontal rule in the output. A hard break is inserted if there is data in the current paragraph, but the logical paragraph is not broken. The arguments and keywords are passed on to the writer's `send_line_break()' method. `add_flowing_data(data)' Provide data which should be formatted with collapsed whitespace. Whitespace from preceding and successive calls to `add_flowing_data()' is considered as well when the whitespace collapse is performed. The data which is passed to this method is expected to be word-wrapped by the output device. Note that any word-wrapping still must be performed by the writer object due to the need to rely on device and font information. `add_literal_data(data)' Provide data which should be passed to the writer unchanged. Whitespace, including newline and tab characters, are considered legal in the value of DATA. `add_label_data(format, counter)' Insert a label which should be placed to the left of the current left margin. This should be used for constructing bulleted or numbered lists. If the FORMAT value is a string, it is interpreted as a format specification for COUNTER, which should be an integer. The result of this formatting becomes the value of the label; if FORMAT is not a string it is used as the label value directly. The label value is passed as the only argument to the writer's `send_label_data()' method. Interpretation of non-string label values is dependent on the associated writer. Format specifications are strings which, in combination with a counter value, are used to compute label values. Each character in the format string is copied to the label value, with some characters recognized to indicate a transform on the counter value. Specifically, the character `1' represents the counter value formatter as an Arabic number, the characters `A' and `a' represent alphabetic representations of the counter value in upper and lower case, respectively, and `I' and `i' represent the counter value in Roman numerals, in upper and lower case. Note that the alphabetic and roman transforms require that the counter value be greater than zero. `flush_softspace()' Send any pending whitespace buffered from a previous call to `add_flowing_data()' to the associated writer object. This should be called before any direct manipulation of the writer object. `push_alignment(align)' Push a new alignment setting onto the alignment stack. This may be `AS_IS' if no change is desired. If the alignment value is changed from the previous setting, the writer's `new_alignment()' method is called with the ALIGN value. `pop_alignment()' Restore the previous alignment. `push_font(`('size, italic, bold, teletype`)')' Change some or all font properties of the writer object. Properties which are not set to `AS_IS' are set to the values passed in while others are maintained at their current settings. The writer's `new_font()' method is called with the fully resolved font specification. `pop_font()' Restore the previous font. `push_margin(margin)' Increase the number of left margin indentations by one, associating the logical tag MARGIN with the new indentation. The initial margin level is `0'. Changed values of the logical tag must be true values; false values other than `AS_IS' are not sufficient to change the margin. `pop_margin()' Restore the previous margin. `push_style(*styles)' Push any number of arbitrary style specifications. All styles are pushed onto the styles stack in order. A tuple representing the entire stack, including `AS_IS' values, is passed to the writer's `new_styles()' method. `pop_style([n` = 1'])' Pop the last N style specifications passed to `push_style()'. A tuple representing the revised stack, including `AS_IS' values, is passed to the writer's `new_styles()' method. `set_spacing(spacing)' Set the spacing style for the writer. `assert_line_data([flag` = 1'])' Inform the formatter that data has been added to the current paragraph out-of-band. This should be used when the writer has been manipulated directly. The optional FLAG argument can be set to false if the writer manipulations produced a hard line break at the end of the output.  File: python-lib.info, Node: Formatter Implementations, Next: Writer Interface, Prev: Formatter Interface, Up: formatter Formatter Implementations ------------------------- Two implementations of formatter objects are provided by this module. Most applications may use one of these classes without modification or subclassing. `NullFormatter([writer])' A formatter which does nothing. If WRITER is omitted, a `NullWriter' instance is created. No methods of the writer are called by `NullFormatter' instances. Implementations should inherit from this class if implementing a writer interface but don't need to inherit any implementation. `AbstractFormatter(writer)' The standard formatter. This implementation has demonstrated wide applicability to many writers, and may be used directly in most circumstances. It has been used to implement a full-featured world-wide web browser.  File: python-lib.info, Node: Writer Interface, Next: Writer Implementations, Prev: Formatter Implementations, Up: formatter The Writer Interface -------------------- Interfaces to create writers are dependent on the specific writer class being instantiated. The interfaces described below are the required interfaces which all writers must support once initialized. Note that while most applications can use the `AbstractFormatter' class as a formatter, the writer must typically be provided by the application. `flush()' Flush any buffered output or device control events. `new_alignment(align)' Set the alignment style. The ALIGN value can be any object, but by convention is a string or `None', where `None' indicates that the writer's "preferred" alignment should be used. Conventional ALIGN values are `'left'', `'center'', `'right'', and `'justify''. `new_font(font)' Set the font style. The value of FONT will be `None', indicating that the device's default font should be used, or a tuple of the form `('SIZE, ITALIC, BOLD, TELETYPE`)'. Size will be a string indicating the size of font that should be used; specific strings and their interpretation must be defined by the application. The ITALIC, BOLD, and TELETYPE values are boolean indicators specifying which of those font attributes should be used. `new_margin(margin, level)' Set the margin level to the integer LEVEL and the logical tag to MARGIN. Interpretation of the logical tag is at the writer's discretion; the only restriction on the value of the logical tag is that it not be a false value for non-zero values of LEVEL. `new_spacing(spacing)' Set the spacing style to SPACING. `new_styles(styles)' Set additional styles. The STYLES value is a tuple of arbitrary values; the value `AS_IS' should be ignored. The STYLES tuple may be interpreted either as a set or as a stack depending on the requirements of the application and writer implementation. `send_line_break()' Break the current line. `send_paragraph(blankline)' Produce a paragraph separation of at least BLANKLINE blank lines, or the equivalent. The BLANKLINE value will be an integer. Note that the implementation will receive a call to `send_line_break()' before this call if a line break is needed; this method should not include ending the last line of the paragraph. It is only responsible for vertical spacing between paragraphs. `send_hor_rule(*args, **kw)' Display a horizontal rule on the output device. The arguments to this method are entirely application- and writer-specific, and should be interpreted with care. The method implementation may assume that a line break has already been issued via `send_line_break()'. `send_flowing_data(data)' Output character data which may be word-wrapped and re-flowed as needed. Within any sequence of calls to this method, the writer may assume that spans of multiple whitespace characters have been collapsed to single space characters. `send_literal_data(data)' Output character data which has already been formatted for display. Generally, this should be interpreted to mean that line breaks indicated by newline characters should be preserved and no new line breaks should be introduced. The data may contain embedded newline and tab characters, unlike data provided to the `send_formatted_data()' interface. `send_label_data(data)' Set DATA to the left of the current left margin, if possible. The value of DATA is not restricted; treatment of non-string values is entirely application- and writer-dependent. This method will only be called at the beginning of a line.  File: python-lib.info, Node: Writer Implementations, Prev: Writer Interface, Up: formatter Writer Implementations ---------------------- Three implementations of the writer object interface are provided as examples by this module. Most applications will need to derive new writer classes from the `NullWriter' class. `NullWriter()' A writer which only provides the interface definition; no actions are taken on any methods. This should be the base class for all writers which do not need to inherit any implementation methods. `AbstractWriter()' A writer which can be used in debugging formatters, but not much else. Each method simply announces itself by printing its name and arguments on standard output. `DumbWriter([file[, maxcol` = 72']])' Simple writer class which writes output on the file object passed in as FILE or, if FILE is omitted, on standard output. The output is simply word-wrapped to the number of columns specified by MAXCOL. This class is suitable for reflowing a sequence of paragraphs.  File: python-lib.info, Node: rfc822, Next: mimetools, Prev: formatter, Up: Internet Data Handling Parse RFC 822 mail headers ========================== Parse RFC 822 style mail headers. This module defines a class, `Message', which represents a collection of "email headers" as defined by the Internet standard RFC 822. It is used in various contexts, usually to read such headers from a file. This module also defines a helper class `AddressList' for parsing RFC 822 addresses. Please refer to the RFC for information on the specific syntax of RFC 822 headers. The `mailbox' module provides classes to read mailboxes produced by various end-user mail programs. `Message(file[, seekable])' A `Message' instance is instantiated with an input object as parameter. Message relies only on the input object having a `readline()' method; in particular, ordinary file objects qualify. Instantiation reads headers from the input object up to a delimiter line (normally a blank line) and stores them in the instance. The message body, following the headers, is not consumed. This class can work with any input object that supports a `readline()' method. If the input object has seek and tell capability, the `rewindbody()' method will work; also, illegal lines will be pushed back onto the input stream. If the input object lacks seek but has an `unread()' method that can push back a line of input, `Message' will use that to push back illegal lines. Thus this class can be used to parse messages coming from a buffered stream. The optional SEEKABLE argument is provided as a workaround for certain stdio libraries in which `tell()' discards buffered data before discovering that the `lseek()' system call doesn't work. For maximum portability, you should set the seekable argument to zero to prevent that initial `tell()' when passing in an unseekable object such as a a file object created from a socket object. Input lines as read from the file may either be terminated by CR-LF or by a single linefeed; a terminating CR-LF is replaced by a single linefeed before the line is stored. All header matching is done independent of upper or lower case; e.g. `M['From']', `M['from']' and `M['FROM']' all yield the same result. `AddressList(field)' You may instantiate the `AddressList' helper class using a single string parameter, a comma-separated list of RFC 822 addresses to be parsed. (The parameter `None' yields an empty list.) `parsedate(date)' Attempts to parse a date according to the rules in RFC 822. however, some mailers don't follow that format as specified, so `parsedate()' tries to guess correctly in such cases. DATE is a string containing an RFC 822 date, such as `'Mon, 20 Nov 1995 19:12:08 -0500''. If it succeeds in parsing the date, `parsedate()' returns a 9-tuple that can be passed directly to `time.mktime()'; otherwise `None' will be returned. Note that fields 6, 7, and 8 of the result tuple are not usable. `parsedate_tz(date)' Performs the same function as `parsedate()', but returns either `None' or a 10-tuple; the first 9 elements make up a tuple that can be passed directly to `time.mktime()', and the tenth is the offset of the date's timezone from UTC (which is the official term for Greenwich Mean Time). (Note that the sign of the timezone offset is the opposite of the sign of the `time.timezone' variable for the same timezone; the latter variable follows the POSIX standard while this module follows RFC 822.) If the input string has no timezone, the last element of the tuple returned is `None'. Note that fields 6, 7, and 8 of the result tuple are not usable. `mktime_tz(tuple)' Turn a 10-tuple as returned by `parsedate_tz()' into a UTC timestamp. It the timezone item in the tuple is `None', assume local time. Minor deficiency: this first interprets the first 8 elements as a local time and then compensates for the timezone difference; this may yield a slight error around daylight savings time switch dates. Not enough to worry about for common use. See also: *Note mailbox:: Classes to read various mailbox formats produced by end-user mail programs. *Note mimetools:: Subclass of rfc.Message that handles MIME encoded messages. * Menu: * Message Objects:: * AddressList Objects::  File: python-lib.info, Node: Message Objects, Next: AddressList Objects, Prev: rfc822, Up: rfc822 Message Objects --------------- A `Message' instance has the following methods: `rewindbody()' Seek to the start of the message body. This only works if the file object is seekable. `isheader(line)' Returns a line's canonicalized fieldname (the dictionary key that will be used to index it) if the line is a legal RFC 822 header; otherwise returns None (implying that parsing should stop here and the line be pushed back on the input stream). It is sometimes useful to override this method in a subclass. `islast(line)' Return true if the given line is a delimiter on which Message should stop. The delimiter line is consumed, and the file object's read location positioned immediately after it. By default this method just checks that the line is blank, but you can override it in a subclass. `iscomment(line)' Return true if the given line should be ignored entirely, just skipped. By default this is a stub that always returns false, but you can override it in a subclass. `getallmatchingheaders(name)' Return a list of lines consisting of all headers matching NAME, if any. Each physical line, whether it is a continuation line or not, is a separate list item. Return the empty list if no header matches NAME. `getfirstmatchingheader(name)' Return a list of lines comprising the first header matching NAME, and its continuation line(s), if any. Return `None' if there is no header matching NAME. `getrawheader(name)' Return a single string consisting of the text after the colon in the first header matching NAME. This includes leading whitespace, the trailing linefeed, and internal linefeeds and whitespace if there any continuation line(s) were present. Return `None' if there is no header matching NAME. `getheader(name[, default])' Like `getrawheader(NAME)', but strip leading and trailing whitespace. Internal whitespace is not stripped. The optional DEFAULT argument can be used to specify a different default to be returned when there is no header matching NAME. `get(name[, default])' An alias for `getheader()', to make the interface more compatible with regular dictionaries. `getaddr(name)' Return a pair `(FULL NAME, EMAIL ADDRESS)' parsed from the string returned by `getheader(NAME)'. If no header matching NAME exists, return `(None, None)'; otherwise both the full name and the address are (possibly empty) strings. Example: If M's first `From' header contains the string `'jack@cwi.nl (Jack Jansen)'', then `m.getaddr('From')' will yield the pair `('Jack Jansen', 'jack@cwi.nl')'. If the header contained `'Jack Jansen '' instead, it would yield the exact same result. `getaddrlist(name)' This is similar to `getaddr(LIST)', but parses a header containing a list of email addresses (e.g. a `To' header) and returns a list of `(FULL NAME, EMAIL ADDRESS)' pairs (even if there was only one address in the header). If there is no header matching NAME, return an empty list. If multiple headers exist that match the named header (e.g. if there are several `Cc' headers), all are parsed for addresses. Any continuation lines the named headers contain are also parsed. `getdate(name)' Retrieve a header using `getheader()' and parse it into a 9-tuple compatible with `time.mktime()'; note that fields 6, 7, and 8 are not usable. If there is no header matching NAME, or it is unparsable, return `None'. Date parsing appears to be a black art, and not all mailers adhere to the standard. While it has been tested and found correct on a large collection of email from many sources, it is still possible that this function may occasionally yield an incorrect result. `getdate_tz(name)' Retrieve a header using `getheader()' and parse it into a 10-tuple; the first 9 elements will make a tuple compatible with `time.mktime()', and the 10th is a number giving the offset of the date's timezone from UTC. Note that fields 6, 7, and 8 are not usable. Similarly to `getdate()', if there is no header matching NAME, or it is unparsable, return `None'. `Message' instances also support a read-only mapping interface. In particular: `M[name]' is like `M.getheader(name)' but raises `KeyError' if there is no matching header; and `len(M)', `M.has_key(name)', `M.keys()', `M.values()' and `M.items()' act as expected (and consistently). Finally, `Message' instances have two public instance variables: `headers' A list containing the entire set of header lines, in the order in which they were read (except that setitem calls may disturb this order). Each line contains a trailing newline. The blank line terminating the headers is not contained in the list. `fp' The file or file-like object passed at instantiation time. This can be used to read the message content.  File: python-lib.info, Node: AddressList Objects, Prev: Message Objects, Up: rfc822 AddressList Objects ------------------- An `AddressList' instance has the following methods: `__len__()' Return the number of addresses in the address list. `__str__()' Return a canonicalized string representation of the address list. Addresses are rendered in "name" form, comma-separated. `__add__(alist)' Return a new `AddressList' instance that contains all addresses in both `AddressList' operands, with duplicates removed (set union). `__iadd__(alist)' In-place version of `__add__()'; turns this `AddressList' instance into the union of itself and the right-hand instance, ALIST. `__sub__(alist)' Return a new `AddressList' instance that contains every address in the left-hand `AddressList' operand that is not present in the right-hand address operand (set difference). `__isub__(alist)' In-place version of `__sub__()', removing addresses in this list which are also in ALIST. Finally, `AddressList' instances have one public instance variable: `addresslist' A list of tuple string pairs, one per address. In each member, the first is the canonicalized name part, the second is the actual route-address (`@'-separated username-host.domain pair).  File: python-lib.info, Node: mimetools, Next: MimeWriter, Prev: rfc822, Up: Internet Data Handling Tools for parsing MIME messages =============================== Tools for parsing MIME-style message bodies. This module defines a subclass of the `rfc822' module's `Message' class and a number of utility functions that are useful for the manipulation for MIME multipart or encoded message. It defines the following items: `Message(fp[, seekable])' Return a new instance of the `Message' class. This is a subclass of the `rfc822.Message' class, with some additional methods (see below). The SEEKABLE argument has the same meaning as for `rfc822.Message'. `choose_boundary()' Return a unique string that has a high likelihood of being usable as a part boundary. The string has the form `'HOSTIPADDR.UID.PID.TIMESTAMP.RANDOM''. `decode(input, output, encoding)' Read data encoded using the allowed MIME ENCODING from open file object INPUT and write the decoded data to open file object OUTPUT. Valid values for ENCODING include `'base64'', `'quoted-printable'' and `'uuencode''. `encode(input, output, encoding)' Read data from open file object INPUT and write it encoded using the allowed MIME ENCODING to open file object OUTPUT. Valid values for ENCODING are the same as for `decode()'. `copyliteral(input, output)' Read lines from open file INPUT until `EOF' and write them to open file OUTPUT. `copybinary(input, output)' Read blocks until `EOF' from open file INPUT and write them to open file OUTPUT. The block size is currently fixed at 8192. See also: *Note rfc822:: Provides the base class for `mimetools.Message'. *Note multifile:: Support for reading files which contain distinct parts, such as MIME data. The MIME Frequently Asked Questions document. For an overview of MIME, see the answer to question 1.1 in Part 1 of this document. * Menu: * Additional Methods of Message Objects::  File: python-lib.info, Node: Additional Methods of Message Objects, 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 of 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 multipart 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::