[Python-3000-checkins] r62491 - in python/branches/py3k: Doc/library/asynchat.rst Doc/library/asyncore.rst Doc/library/basehttpserver.rst Doc/library/bdb.rst Doc/library/bz2.rst Doc/library/calendar.rst Doc/library/cgihttpserver.rst Doc/library/chunk.rst Doc/library/codecs.rst Doc/library/collections.rst Doc/library/csv.rst Doc/library/ctypes.rst Doc/library/curses.rst Doc/library/decimal.rst Doc/library/difflib.rst Doc/library/doctest.rst Doc/library/email.charset.rst Doc/library/email.generator.rst Doc/library/email.header.rst Doc/library/email.message.rst Doc/library/email.parser.rst Doc/library/filecmp.rst Doc/library/fractions.rst Doc/library/ftplib.rst Doc/library/gettext.rst Doc/library/logging.rst Doc/library/mailbox.rst Doc/library/mmap.rst Doc/library/modulefinder.rst Doc/library/msilib.rst Doc/library/numbers.rst Doc/library/pickle.rst Doc/library/robotparser.rst Doc/library/simplehttpserver.rst Doc/library/smtpd.rst Doc/library/string.rst Doc/library/struct.rst Doc/library/textwrap.rst Doc/library/xml.etree.elementtree.rst Doc/library/zipimport.rst
benjamin.peterson
python-3000-checkins at python.org
Fri Apr 25 03:59:12 CEST 2008
Author: benjamin.peterson
Date: Fri Apr 25 03:59:09 2008
New Revision: 62491
Log:
Merged revisions 62490 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r62490 | benjamin.peterson | 2008-04-24 20:29:10 -0500 (Thu, 24 Apr 2008) | 2 lines
reformat some documentation of classes so methods and attributes are under the class directive
........
Modified:
python/branches/py3k/ (props changed)
python/branches/py3k/Doc/library/asynchat.rst
python/branches/py3k/Doc/library/asyncore.rst
python/branches/py3k/Doc/library/basehttpserver.rst
python/branches/py3k/Doc/library/bdb.rst
python/branches/py3k/Doc/library/bz2.rst
python/branches/py3k/Doc/library/calendar.rst
python/branches/py3k/Doc/library/cgihttpserver.rst
python/branches/py3k/Doc/library/chunk.rst
python/branches/py3k/Doc/library/codecs.rst
python/branches/py3k/Doc/library/collections.rst
python/branches/py3k/Doc/library/csv.rst
python/branches/py3k/Doc/library/ctypes.rst
python/branches/py3k/Doc/library/curses.rst
python/branches/py3k/Doc/library/decimal.rst
python/branches/py3k/Doc/library/difflib.rst
python/branches/py3k/Doc/library/doctest.rst
python/branches/py3k/Doc/library/email.charset.rst
python/branches/py3k/Doc/library/email.generator.rst
python/branches/py3k/Doc/library/email.header.rst
python/branches/py3k/Doc/library/email.message.rst
python/branches/py3k/Doc/library/email.parser.rst
python/branches/py3k/Doc/library/filecmp.rst
python/branches/py3k/Doc/library/fractions.rst
python/branches/py3k/Doc/library/ftplib.rst
python/branches/py3k/Doc/library/gettext.rst
python/branches/py3k/Doc/library/logging.rst
python/branches/py3k/Doc/library/mailbox.rst
python/branches/py3k/Doc/library/mmap.rst
python/branches/py3k/Doc/library/modulefinder.rst
python/branches/py3k/Doc/library/msilib.rst
python/branches/py3k/Doc/library/numbers.rst
python/branches/py3k/Doc/library/pickle.rst
python/branches/py3k/Doc/library/robotparser.rst
python/branches/py3k/Doc/library/simplehttpserver.rst
python/branches/py3k/Doc/library/smtpd.rst
python/branches/py3k/Doc/library/string.rst
python/branches/py3k/Doc/library/struct.rst
python/branches/py3k/Doc/library/textwrap.rst
python/branches/py3k/Doc/library/xml.etree.elementtree.rst
python/branches/py3k/Doc/library/zipimport.rst
Modified: python/branches/py3k/Doc/library/asynchat.rst
==============================================================================
--- python/branches/py3k/Doc/library/asynchat.rst (original)
+++ python/branches/py3k/Doc/library/asynchat.rst Fri Apr 25 03:59:09 2008
@@ -197,10 +197,10 @@
the data no larger than *buffer_size*.
-.. method:: simple_producer.more()
+ .. method:: more()
- Produces the next chunk of information from the producer, or returns the
- empty string.
+ Produces the next chunk of information from the producer, or returns the
+ empty string.
.. class:: fifo([list=None])
@@ -212,26 +212,26 @@
producers or data items to be written to the channel.
-.. method:: fifo.is_empty()
+ .. method:: is_empty()
- Returns ``True`` if and only if the fifo is empty.
+ Returns ``True`` if and only if the fifo is empty.
-.. method:: fifo.first()
+ .. method:: first()
- Returns the least-recently :meth:`push`\ ed item from the fifo.
+ Returns the least-recently :meth:`push`\ ed item from the fifo.
-.. method:: fifo.push(data)
+ .. method:: push(data)
- Adds the given data (which may be a string or a producer object) to the
- producer fifo.
+ Adds the given data (which may be a string or a producer object) to the
+ producer fifo.
-.. method:: fifo.pop()
+ .. method:: pop()
- If the fifo is not empty, returns ``True, first()``, deleting the popped
- item. Returns ``False, None`` for an empty fifo.
+ If the fifo is not empty, returns ``True, first()``, deleting the popped
+ item. Returns ``False, None`` for an empty fifo.
The :mod:`asynchat` module also defines one utility function, which may be of
use in network and textual analysis operations.
Modified: python/branches/py3k/Doc/library/asyncore.rst
==============================================================================
--- python/branches/py3k/Doc/library/asyncore.rst (original)
+++ python/branches/py3k/Doc/library/asyncore.rst Fri Apr 25 03:59:09 2008
@@ -95,132 +95,132 @@
should be added to the list of channels :cfunc:`select`\ ed or
:cfunc:`poll`\ ed for read and write events.
-Thus, the set of channel events is larger than the basic socket events. The
-full set of methods that can be overridden in your subclass follows:
+ Thus, the set of channel events is larger than the basic socket events. The
+ full set of methods that can be overridden in your subclass follows:
-.. method:: dispatcher.handle_read()
+ .. method:: handle_read()
- Called when the asynchronous loop detects that a :meth:`read` call on the
- channel's socket will succeed.
+ Called when the asynchronous loop detects that a :meth:`read` call on the
+ channel's socket will succeed.
-.. method:: dispatcher.handle_write()
+ .. method:: handle_write()
- Called when the asynchronous loop detects that a writable socket can be
- written. Often this method will implement the necessary buffering for
- performance. For example::
+ Called when the asynchronous loop detects that a writable socket can be
+ written. 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:]
+ def handle_write(self):
+ sent = self.send(self.buffer)
+ self.buffer = self.buffer[sent:]
-.. method:: dispatcher.handle_expt()
+ .. method:: 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.
+ 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.
-.. method:: dispatcher.handle_connect()
+ .. method:: handle_connect()
- Called when the active opener's socket actually makes a connection. Might
- send a "welcome" banner, or initiate a protocol negotiation with the remote
- endpoint, for example.
+ Called when the active opener's socket actually makes a connection. Might
+ send a "welcome" banner, or initiate a protocol negotiation with the
+ remote endpoint, for example.
-.. method:: dispatcher.handle_close()
+ .. method:: handle_close()
- Called when the socket is closed.
+ Called when the socket is closed.
-.. method:: dispatcher.handle_error()
+ .. method:: handle_error()
- Called when an exception is raised and not otherwise handled. The default
- version prints a condensed traceback.
+ Called when an exception is raised and not otherwise handled. The default
+ version prints a condensed traceback.
-.. method:: dispatcher.handle_accept()
+ .. method:: handle_accept()
- Called on listening channels (passive openers) when a connection can be
- established with a new remote endpoint that has issued a :meth:`connect`
- call for the local endpoint.
+ Called on listening channels (passive openers) when a connection can be
+ established with a new remote endpoint that has issued a :meth:`connect`
+ call for the local endpoint.
-.. method:: dispatcher.readable()
+ .. method:: readable()
- Called each time around the asynchronous loop to determine whether a
- channel's socket should be added to the list on which read events can
- occur. The default method simply returns ``True``, indicating that by
- default, all channels will be interested in read events.
+ Called each time around the asynchronous loop to determine whether a
+ channel's socket should be added to the list on which read events can
+ occur. The default method simply returns ``True``, indicating that by
+ default, all channels will be interested in read events.
-.. method:: dispatcher.writable()
+ .. method:: writable()
- Called each time around the asynchronous loop to determine whether a
- channel's socket should be added to the list on which write events can
- occur. The default method simply returns ``True``, indicating that by
- default, all channels will be interested in write events.
+ Called each time around the asynchronous loop to determine whether a
+ channel's socket should be added to the list on which write events can
+ occur. The default method simply returns ``True``, indicating that by
+ default, all channels will be interested in write events.
-In addition, each channel delegates or extends many of the socket methods.
-Most of these are nearly identical to their socket partners.
+ In addition, each channel delegates or extends many of the socket methods.
+ Most of these are nearly identical to their socket partners.
-.. method:: dispatcher.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 :mod:`socket` documentation for
- information on creating sockets.
+ .. method:: 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 :mod:`socket` documentation for
+ information on creating sockets.
-.. method:: dispatcher.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 number.
+ .. method:: 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 number.
-.. method:: dispatcher.send(data)
- Send *data* to the remote end-point of the socket.
+ .. method:: send(data)
+ Send *data* to the remote end-point of the socket.
-.. method:: dispatcher.recv(buffer_size)
- Read at most *buffer_size* bytes from the socket's remote end-point.
- An empty string implies that the channel has been closed from the other
- end.
+ .. method:: recv(buffer_size)
+ Read at most *buffer_size* bytes from the socket's remote end-point. An
+ empty string implies that the channel has been closed from the other end.
-.. method:: dispatcher.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).
+ .. method:: 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).
-.. method:: dispatcher.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.) To mark
- the socket as re-usable (setting the :const:`SO_REUSEADDR` option), call
- the :class:`dispatcher` object's :meth:`set_reuse_addr` method.
+ .. method:: 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.) To mark
+ the socket as re-usable (setting the :const:`SO_REUSEADDR` option), call
+ the :class:`dispatcher` object's :meth:`set_reuse_addr` method.
-.. method:: dispatcher.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.
+ .. method:: 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.
-.. method:: dispatcher.close()
- Close the socket. All future operations on the socket object will fail.
- The remote end-point will receive no more data (after queued data is
- flushed). Sockets are automatically closed when they are
- garbage-collected.
+ .. method:: close()
+
+ Close the socket. All future operations on the socket object will fail.
+ The remote end-point will receive no more data (after queued data is
+ flushed). Sockets are automatically closed when they are
+ garbage-collected.
.. _asyncore-example:
Modified: python/branches/py3k/Doc/library/basehttpserver.rst
==============================================================================
--- python/branches/py3k/Doc/library/basehttpserver.rst (original)
+++ python/branches/py3k/Doc/library/basehttpserver.rst Fri Apr 25 03:59:09 2008
@@ -34,216 +34,224 @@
.. class:: HTTPServer(server_address, RequestHandlerClass)
- This class builds on the :class:`TCPServer` class by storing the server address
- as instance variables named :attr:`server_name` and :attr:`server_port`. The
- server is accessible by the handler, typically through the handler's
- :attr:`server` instance variable.
+ This class builds on the :class:`TCPServer` class by storing the server
+ address as instance variables named :attr:`server_name` and
+ :attr:`server_port`. The server is accessible by the handler, typically
+ through the handler's :attr:`server` instance variable.
.. class:: BaseHTTPRequestHandler(request, client_address, server)
This class is used to handle the HTTP requests that arrive at the server. By
- itself, it cannot respond to any actual HTTP requests; it must be subclassed to
- handle each request method (e.g. GET or POST). :class:`BaseHTTPRequestHandler`
- provides a number of class and instance variables, and methods for use by
- subclasses.
+ itself, it cannot respond to any actual HTTP requests; it must be subclassed
+ to handle each request method (e.g. GET or
+ POST). :class:`BaseHTTPRequestHandler` provides a number of class and
+ instance variables, and methods for use by subclasses.
- The handler will parse the request and the headers, then call a method specific
- to the request type. The method name is constructed from the request. For
- example, for the request method ``SPAM``, the :meth:`do_SPAM` method will be
- called with no arguments. All of the relevant information is stored in instance
- variables of the handler. Subclasses should not need to override or extend the
- :meth:`__init__` method.
+ The handler will parse the request and the headers, then call a method
+ specific to the request type. The method name is constructed from the
+ request. For example, for the request method ``SPAM``, the :meth:`do_SPAM`
+ method will be called with no arguments. All of the relevant information is
+ stored in instance variables of the handler. Subclasses should not need to
+ override or extend the :meth:`__init__` method.
-:class:`BaseHTTPRequestHandler` has the following instance variables:
+ :class:`BaseHTTPRequestHandler` has the following instance variables:
-.. attribute:: BaseHTTPRequestHandler.client_address
+ .. attribute:: client_address
- Contains a tuple of the form ``(host, port)`` referring to the client's address.
+ Contains a tuple of the form ``(host, port)`` referring to the client's
+ address.
-.. attribute:: BaseHTTPRequestHandler.command
+ .. attribute:: command
- Contains the command (request type). For example, ``'GET'``.
+ Contains the command (request type). For example, ``'GET'``.
-.. attribute:: BaseHTTPRequestHandler.path
+ .. attribute:: path
- Contains the request path.
+ Contains the request path.
-.. attribute:: BaseHTTPRequestHandler.request_version
+ .. attribute:: request_version
- Contains the version string from the request. For example, ``'HTTP/1.0'``.
+ Contains the version string from the request. For example, ``'HTTP/1.0'``.
-.. attribute:: BaseHTTPRequestHandler.headers
+ .. attribute:: headers
- Holds an instance of the class specified by the :attr:`MessageClass` class
- variable. This instance parses and manages the headers in the HTTP request.
+ Holds an instance of the class specified by the :attr:`MessageClass` class
+ variable. This instance parses and manages the headers in the HTTP
+ request.
-.. attribute:: BaseHTTPRequestHandler.rfile
+ .. attribute:: rfile
- Contains an input stream, positioned at the start of the optional input data.
+ Contains an input stream, positioned at the start of the optional input
+ data.
-.. attribute:: BaseHTTPRequestHandler.wfile
+ .. attribute:: wfile
- Contains the output stream for writing a response back to the client. Proper
- adherence to the HTTP protocol must be used when writing to this stream.
+ Contains the output stream for writing a response back to the
+ client. Proper adherence to the HTTP protocol must be used when writing to
+ this stream.
-:class:`BaseHTTPRequestHandler` has the following class variables:
+ :class:`BaseHTTPRequestHandler` has the following class variables:
-.. attribute:: BaseHTTPRequestHandler.server_version
- Specifies the server software version. You may want to override this. The
- format is multiple whitespace-separated strings, where each string is of the
- form name[/version]. For example, ``'BaseHTTP/0.2'``.
+ .. attribute:: server_version
+ Specifies the server software version. You may want to override this. The
+ format is multiple whitespace-separated strings, where each string is of
+ the form name[/version]. For example, ``'BaseHTTP/0.2'``.
-.. attribute:: BaseHTTPRequestHandler.sys_version
- Contains the Python system version, in a form usable by the
- :attr:`version_string` method and the :attr:`server_version` class variable. For
- example, ``'Python/1.4'``.
+ .. attribute:: sys_version
+ Contains the Python system version, in a form usable by the
+ :attr:`version_string` method and the :attr:`server_version` class
+ variable. For example, ``'Python/1.4'``.
-.. attribute:: BaseHTTPRequestHandler.error_message_format
- Specifies a format string for building an error response to the client. It uses
- parenthesized, keyed format specifiers, so the format operand must be a
- dictionary. The *code* key should be an integer, specifying the numeric HTTP
- error code value. *message* should be a string containing a (detailed) error
- message of what occurred, and *explain* should be an explanation of the error
- code number. Default *message* and *explain* values can found in the *responses*
- class variable.
+ .. attribute:: error_message_format
+ Specifies a format string for building an error response to the client. It
+ uses parenthesized, keyed format specifiers, so the format operand must be
+ a dictionary. The *code* key should be an integer, specifying the numeric
+ HTTP error code value. *message* should be a string containing a
+ (detailed) error message of what occurred, and *explain* should be an
+ explanation of the error code number. Default *message* and *explain*
+ values can found in the *responses* class variable.
-.. attribute:: BaseHTTPRequestHandler.error_content_type
- Specifies the Content-Type HTTP header of error responses sent to the client.
- The default value is ``'text/html'``.
+ .. attribute:: error_content_type
+ Specifies the Content-Type HTTP header of error responses sent to the
+ client. The default value is ``'text/html'``.
-.. attribute:: BaseHTTPRequestHandler.protocol_version
- This specifies the HTTP protocol version used in responses. If set to
- ``'HTTP/1.1'``, the server will permit HTTP persistent connections; however,
- your server *must* then include an accurate ``Content-Length`` header (using
- :meth:`send_header`) in all of its responses to clients. For backwards
- compatibility, the setting defaults to ``'HTTP/1.0'``.
+ .. attribute:: protocol_version
+ This specifies the HTTP protocol version used in responses. If set to
+ ``'HTTP/1.1'``, the server will permit HTTP persistent connections;
+ however, your server *must* then include an accurate ``Content-Length``
+ header (using :meth:`send_header`) in all of its responses to clients.
+ For backwards compatibility, the setting defaults to ``'HTTP/1.0'``.
-.. attribute:: BaseHTTPRequestHandler.MessageClass
- .. index:: single: Message (in module mimetools)
+ .. attribute:: MessageClass
- Specifies a :class:`rfc822.Message`\ -like class to parse HTTP headers.
- Typically, this is not overridden, and it defaults to
- :class:`mimetools.Message`.
+ .. index:: single: Message (in module mimetools)
+ Specifies a :class:`rfc822.Message`\ -like class to parse HTTP headers.
+ Typically, this is not overridden, and it defaults to
+ :class:`mimetools.Message`.
-.. attribute:: BaseHTTPRequestHandler.responses
- This variable contains a mapping of error code integers to two-element tuples
- containing a short and long message. For example, ``{code: (shortmessage,
- longmessage)}``. The *shortmessage* is usually used as the *message* key in an
- error response, and *longmessage* as the *explain* key (see the
- :attr:`error_message_format` class variable).
+ .. attribute:: responses
-A :class:`BaseHTTPRequestHandler` instance has the following methods:
+ This variable contains a mapping of error code integers to two-element tuples
+ containing a short and long message. For example, ``{code: (shortmessage,
+ longmessage)}``. The *shortmessage* is usually used as the *message* key in an
+ error response, and *longmessage* as the *explain* key (see the
+ :attr:`error_message_format` class variable).
-.. method:: BaseHTTPRequestHandler.handle()
+ A :class:`BaseHTTPRequestHandler` instance has the following methods:
- Calls :meth:`handle_one_request` once (or, if persistent connections are
- enabled, multiple times) to handle incoming HTTP requests. You should never need
- to override it; instead, implement appropriate :meth:`do_\*` methods.
+ .. method:: handle()
-.. method:: BaseHTTPRequestHandler.handle_one_request()
+ Calls :meth:`handle_one_request` once (or, if persistent connections are
+ enabled, multiple times) to handle incoming HTTP requests. You should
+ never need to override it; instead, implement appropriate :meth:`do_\*`
+ methods.
- This method will parse and dispatch the request to the appropriate :meth:`do_\*`
- method. You should never need to override it.
+ .. method:: handle_one_request()
-.. method:: BaseHTTPRequestHandler.send_error(code[, message])
+ This method will parse and dispatch the request to the appropriate
+ :meth:`do_\*` method. You should never need to override it.
- Sends and logs a complete error reply to the client. The numeric *code*
- specifies the HTTP error code, with *message* as optional, more specific text. A
- complete set of headers is sent, followed by text composed using the
- :attr:`error_message_format` class variable.
+ .. method:: send_error(code[, message])
-.. method:: BaseHTTPRequestHandler.send_response(code[, message])
+ Sends and logs a complete error reply to the client. The numeric *code*
+ specifies the HTTP error code, with *message* as optional, more specific text. A
+ complete set of headers is sent, followed by text composed using the
+ :attr:`error_message_format` class variable.
- Sends a response header and logs the accepted request. The HTTP response line is
- sent, followed by *Server* and *Date* headers. The values for these two headers
- are picked up from the :meth:`version_string` and :meth:`date_time_string`
- methods, respectively.
+ .. method:: send_response(code[, message])
-.. method:: BaseHTTPRequestHandler.send_header(keyword, value)
+ Sends a response header and logs the accepted request. The HTTP response
+ line is sent, followed by *Server* and *Date* headers. The values for
+ these two headers are picked up from the :meth:`version_string` and
+ :meth:`date_time_string` methods, respectively.
- Writes a specific HTTP header to the output stream. *keyword* should specify the
- header keyword, with *value* specifying its value.
+ .. method:: send_header(keyword, value)
-.. method:: BaseHTTPRequestHandler.end_headers()
+ Writes a specific HTTP header to the output stream. *keyword* should
+ specify the header keyword, with *value* specifying its value.
- Sends a blank line, indicating the end of the HTTP headers in the response.
+ .. method:: end_headers()
-.. method:: BaseHTTPRequestHandler.log_request([code[, size]])
+ Sends a blank line, indicating the end of the HTTP headers in the
+ response.
- Logs an accepted (successful) request. *code* should specify the numeric HTTP
- code associated with the response. If a size of the response is available, then
- it should be passed as the *size* parameter.
+ .. method:: log_request([code[, size]])
-.. method:: BaseHTTPRequestHandler.log_error(...)
+ Logs an accepted (successful) request. *code* should specify the numeric
+ HTTP code associated with the response. If a size of the response is
+ available, then it should be passed as the *size* parameter.
- Logs an error when a request cannot be fulfilled. By default, it passes the
- message to :meth:`log_message`, so it takes the same arguments (*format* and
- additional values).
+ .. method:: log_error(...)
-.. method:: BaseHTTPRequestHandler.log_message(format, ...)
+ Logs an error when a request cannot be fulfilled. By default, it passes
+ the message to :meth:`log_message`, so it takes the same arguments
+ (*format* and additional values).
- Logs an arbitrary message to ``sys.stderr``. This is typically overridden to
- create custom error logging mechanisms. The *format* argument is a standard
- printf-style format string, where the additional arguments to
- :meth:`log_message` are applied as inputs to the formatting. The client address
- and current date and time are prefixed to every message logged.
+ .. method:: log_message(format, ...)
-.. method:: BaseHTTPRequestHandler.version_string()
+ Logs an arbitrary message to ``sys.stderr``. This is typically overridden
+ to create custom error logging mechanisms. The *format* argument is a
+ standard printf-style format string, where the additional arguments to
+ :meth:`log_message` are applied as inputs to the formatting. The client
+ address and current date and time are prefixed to every message logged.
- Returns the server software's version string. This is a combination of the
- :attr:`server_version` and :attr:`sys_version` class variables.
+ .. method:: version_string()
-.. method:: BaseHTTPRequestHandler.date_time_string([timestamp])
+ Returns the server software's version string. This is a combination of the
+ :attr:`server_version` and :attr:`sys_version` class variables.
- Returns the date and time given by *timestamp* (which must be in the format
- returned by :func:`time.time`), formatted for a message header. If *timestamp*
- is omitted, it uses the current date and time.
- The result looks like ``'Sun, 06 Nov 1994 08:49:37 GMT'``.
+ .. method:: date_time_string([timestamp])
+ Returns the date and time given by *timestamp* (which must be in the
+ format returned by :func:`time.time`), formatted for a message header. If
+ *timestamp* is omitted, it uses the current date and time.
-.. method:: BaseHTTPRequestHandler.log_date_time_string()
+ The result looks like ``'Sun, 06 Nov 1994 08:49:37 GMT'``.
- Returns the current date and time, formatted for logging.
+ .. method:: log_date_time_string()
-.. method:: BaseHTTPRequestHandler.address_string()
+ Returns the current date and time, formatted for logging.
- Returns the client address, formatted for logging. A name lookup is performed on
- the client's IP address.
+
+ .. method:: address_string()
+
+ Returns the client address, formatted for logging. A name lookup is
+ performed on the client's IP address.
.. seealso::
Modified: python/branches/py3k/Doc/library/bdb.rst
==============================================================================
--- python/branches/py3k/Doc/library/bdb.rst (original)
+++ python/branches/py3k/Doc/library/bdb.rst Fri Apr 25 03:59:09 2008
@@ -31,32 +31,35 @@
first line of that function is executed. A conditional breakpoint always
counts a hit.
-:class:`Breakpoint` instances have the following methods:
+ :class:`Breakpoint` instances have the following methods:
-.. method:: Breakpoint.deleteMe()
+ .. method:: deleteMe()
- Delete the breakpoint from the list associated to a file/line. If it is the
- last breakpoint in that position, it also deletes the entry for the
- file/line.
+ Delete the breakpoint from the list associated to a file/line. If it is
+ the last breakpoint in that position, it also deletes the entry for the
+ file/line.
-.. method:: Breakpoint.enable()
- Mark the breakpoint as enabled.
+ .. method:: enable()
-.. method:: Breakpoint.disable()
+ Mark the breakpoint as enabled.
- Mark the breakpoint as disabled.
-.. method:: Breakpoint.bpprint([out])
+ .. method:: disable()
- Print all the information about the breakpoint:
+ Mark the breakpoint as disabled.
- * The breakpoint number.
- * If it is temporary or not.
- * Its file,line position.
- * The condition that causes a break.
- * If it must be ignored the next N times.
- * The breakpoint hit count.
+
+ .. method:: pprint([out])
+
+ Print all the information about the breakpoint:
+
+ * The breakpoint number.
+ * If it is temporary or not.
+ * Its file,line position.
+ * The condition that causes a break.
+ * If it must be ignored the next N times.
+ * The breakpoint hit count.
.. class:: Bdb()
@@ -68,247 +71,246 @@
(:class:`pdb.Pdb`) is an example.
-The following methods of :class:`Bdb` normally don't need to be overridden.
-
-.. method:: Bdb.canonic(filename)
+ The following methods of :class:`Bdb` normally don't need to be overridden.
- Auxiliary method for getting a filename in a canonical form, that is, as a
- case-normalized (on case-insensitive filesystems) absolute path, stripped
- of surrounding angle brackets.
+ .. method:: canonic(filename)
-.. method:: Bdb.reset()
+ Auxiliary method for getting a filename in a canonical form, that is, as a
+ case-normalized (on case-insensitive filesystems) absolute path, stripped
+ of surrounding angle brackets.
- Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
- :attr:`quitting` attributes with values ready to start debugging.
+ .. method:: reset()
+ Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
+ :attr:`quitting` attributes with values ready to start debugging.
-.. method:: Bdb.trace_dispatch(frame, event, arg)
+ .. method:: trace_dispatch(frame, event, arg)
- This function is installed as the trace function of debugged frames. Its
- return value is the new trace function (in most cases, that is, itself).
+ This function is installed as the trace function of debugged frames. Its
+ return value is the new trace function (in most cases, that is, itself).
- The default implementation decides how to dispatch a frame, depending on the
- type of event (passed as a string) that is about to be executed. *event* can
- be one of the following:
+ The default implementation decides how to dispatch a frame, depending on
+ the type of event (passed as a string) that is about to be executed.
+ *event* can be one of the following:
- * ``"line"``: A new line of code is going to be executed.
- * ``"call"``: A function is about to be called, or another code block
- entered.
- * ``"return"``: A function or other code block is about to return.
- * ``"exception"``: An exception has occurred.
- * ``"c_call"``: A C function is about to be called.
- * ``"c_return"``: A C function has returned.
- * ``"c_exception"``: A C function has thrown an exception.
+ * ``"line"``: A new line of code is going to be executed.
+ * ``"call"``: A function is about to be called, or another code block
+ entered.
+ * ``"return"``: A function or other code block is about to return.
+ * ``"exception"``: An exception has occurred.
+ * ``"c_call"``: A C function is about to be called.
+ * ``"c_return"``: A C function has returned.
+ * ``"c_exception"``: A C function has thrown an exception.
- For the Python events, specialized functions (see below) are called. For the
- C events, no action is taken.
+ For the Python events, specialized functions (see below) are called. For
+ the C events, no action is taken.
- The *arg* parameter depends on the previous event.
+ The *arg* parameter depends on the previous event.
- For more information on trace functions, see :ref:`debugger-hooks`. For more
- information on code and frame objects, refer to :ref:`types`.
+ For more information on trace functions, see :ref:`debugger-hooks`. For
+ more information on code and frame objects, refer to :ref:`types`.
-.. method:: Bdb.dispatch_line(frame)
+ .. method:: dispatch_line(frame)
- If the debugger should stop on the current line, invoke the :meth:`user_line`
- method (which should be overridden in subclasses). Raise a :exc:`BdbQuit`
- exception if the :attr:`Bdb.quitting` flag is set (which can be set from
- :meth:`user_line`). Return a reference to the :meth:`trace_dispatch` method
- for further tracing in that scope.
+ If the debugger should stop on the current line, invoke the
+ :meth:`user_line` method (which should be overridden in subclasses).
+ Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
+ (which can be set from :meth:`user_line`). Return a reference to the
+ :meth:`trace_dispatch` method for further tracing in that scope.
-.. method:: Bdb.dispatch_call(frame, arg)
+ .. method:: dispatch_call(frame, arg)
- If the debugger should stop on this function call, invoke the
- :meth:`user_call` method (which should be overridden in subclasses). Raise a
- :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
- be set from :meth:`user_call`). Return a reference to the
- :meth:`trace_dispatch` method for further tracing in that scope.
+ If the debugger should stop on this function call, invoke the
+ :meth:`user_call` method (which should be overridden in subclasses).
+ Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
+ (which can be set from :meth:`user_call`). Return a reference to the
+ :meth:`trace_dispatch` method for further tracing in that scope.
-.. method:: Bdb.dispatch_return(frame, arg)
+ .. method:: dispatch_return(frame, arg)
- If the debugger should stop on this function return, invoke the
- :meth:`user_return` method (which should be overridden in subclasses). Raise
- a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
- be set from :meth:`user_return`). Return a reference to the
- :meth:`trace_dispatch` method for further tracing in that scope.
+ If the debugger should stop on this function return, invoke the
+ :meth:`user_return` method (which should be overridden in subclasses).
+ Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
+ (which can be set from :meth:`user_return`). Return a reference to the
+ :meth:`trace_dispatch` method for further tracing in that scope.
-.. method:: Bdb.dispatch_exception(frame, arg)
+ .. method:: dispatch_exception(frame, arg)
- If the debugger should stop at this exception, invokes the
- :meth:`user_exception` method (which should be overridden in subclasses).
- Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
- (which can be set from :meth:`user_exception`). Return a reference to the
- :meth:`trace_dispatch` method for further tracing in that scope.
+ If the debugger should stop at this exception, invokes the
+ :meth:`user_exception` method (which should be overridden in subclasses).
+ Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
+ (which can be set from :meth:`user_exception`). Return a reference to the
+ :meth:`trace_dispatch` method for further tracing in that scope.
-Normally derived classes don't override the following methods, but they may if
-they want to redefine the definition of stopping and breakpoints.
+ Normally derived classes don't override the following methods, but they may
+ if they want to redefine the definition of stopping and breakpoints.
-.. method:: Bdb.stop_here(frame)
+ .. method:: stop_here(frame)
- This method checks if the *frame* is somewhere below :attr:`botframe` in the
- call stack. :attr:`botframe` is the frame in which debugging started.
+ This method checks if the *frame* is somewhere below :attr:`botframe` in
+ the call stack. :attr:`botframe` is the frame in which debugging started.
-.. method:: Bdb.break_here(frame)
+ .. method:: break_here(frame)
- This method checks if there is a breakpoint in the filename and line
- belonging to *frame* or, at least, in the current function. If the
- breakpoint is a temporary one, this method deletes it.
+ This method checks if there is a breakpoint in the filename and line
+ belonging to *frame* or, at least, in the current function. If the
+ breakpoint is a temporary one, this method deletes it.
-.. method:: Bdb.break_anywhere(frame)
+ .. method:: break_anywhere(frame)
- This method checks if there is a breakpoint in the filename of the current
- frame.
+ This method checks if there is a breakpoint in the filename of the current
+ frame.
-Derived classes should override these methods to gain control over debugger
-operation.
+ Derived classes should override these methods to gain control over debugger
+ operation.
-.. method:: Bdb.user_call(frame, argument_list)
+ .. method:: user_call(frame, argument_list)
- This method is called from :meth:`dispatch_call` when there is the
- possibility that a break might be necessary anywhere inside the called
- function.
+ This method is called from :meth:`dispatch_call` when there is the
+ possibility that a break might be necessary anywhere inside the called
+ function.
-.. method:: Bdb.user_line(frame)
+ .. method:: user_line(frame)
- This method is called from :meth:`dispatch_line` when either
- :meth:`stop_here` or :meth:`break_here` yields True.
+ This method is called from :meth:`dispatch_line` when either
+ :meth:`stop_here` or :meth:`break_here` yields True.
-.. method:: Bdb.user_return(frame, return_value)
+ .. method:: user_return(frame, return_value)
- This method is called from :meth:`dispatch_return` when :meth:`stop_here`
- yields True.
+ This method is called from :meth:`dispatch_return` when :meth:`stop_here`
+ yields True.
-.. method:: Bdb.user_exception(frame, exc_info)
+ .. method:: user_exception(frame, exc_info)
- This method is called from :meth:`dispatch_exception` when :meth:`stop_here`
- yields True.
+ This method is called from :meth:`dispatch_exception` when
+ :meth:`stop_here` yields True.
-.. method:: Bdb.do_clear(arg)
+ .. method:: do_clear(arg)
- Handle how a breakpoint must be removed when it is a temporary one.
+ Handle how a breakpoint must be removed when it is a temporary one.
- This method must be implemented by derived classes.
+ This method must be implemented by derived classes.
-Derived classes and clients can call the following methods to affect the
-stepping state.
+ Derived classes and clients can call the following methods to affect the
+ stepping state.
-.. method:: Bdb.set_step()
+ .. method:: set_step()
- Stop after one line of code.
+ Stop after one line of code.
-.. method:: Bdb.set_next(frame)
+ .. method:: set_next(frame)
- Stop on the next line in or below the given frame.
+ Stop on the next line in or below the given frame.
-.. method:: Bdb.set_return(frame)
+ .. method:: set_return(frame)
- Stop when returning from the given frame.
+ Stop when returning from the given frame.
-.. method:: Bdb.set_trace([frame])
+ .. method:: set_trace([frame])
- Start debugging from *frame*. If *frame* is not specified, debugging starts
- from caller's frame.
+ Start debugging from *frame*. If *frame* is not specified, debugging
+ starts from caller's frame.
-.. method:: Bdb.set_continue()
+ .. method:: set_continue()
- Stop only at breakpoints or when finished. If there are no breakpoints, set
- the system trace function to None.
+ Stop only at breakpoints or when finished. If there are no breakpoints,
+ set the system trace function to None.
-.. method:: Bdb.set_quit()
+ .. method:: set_quit()
- Set the :attr:`quitting` attribute to True. This raises :exc:`BdbQuit` in
- the next call to one of the :meth:`dispatch_\*` methods.
+ Set the :attr:`quitting` attribute to True. This raises :exc:`BdbQuit` in
+ the next call to one of the :meth:`dispatch_\*` methods.
-Derived classes and clients can call the following methods to manipulate
-breakpoints. These methods return a string containing an error message if
-something went wrong, or ``None`` if all is well.
+ Derived classes and clients can call the following methods to manipulate
+ breakpoints. These methods return a string containing an error message if
+ something went wrong, or ``None`` if all is well.
-.. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]])
+ .. method:: set_break(filename, lineno[, temporary=0[, cond[, funcname]]])
- Set a new breakpoint. If the *lineno* line doesn't exist for the *filename*
- passed as argument, return an error message. The *filename* should be in
- canonical form, as described in the :meth:`canonic` method.
+ Set a new breakpoint. If the *lineno* line doesn't exist for the
+ *filename* passed as argument, return an error message. The *filename*
+ should be in canonical form, as described in the :meth:`canonic` method.
-.. method:: Bdb.clear_break(filename, lineno)
+ .. method:: clear_break(filename, lineno)
- Delete the breakpoints in *filename* and *lineno*. If none were set, an
- error message is returned.
+ Delete the breakpoints in *filename* and *lineno*. If none were set, an
+ error message is returned.
-.. method:: Bdb.clear_bpbynumber(arg)
+ .. method:: clear_bpbynumber(arg)
- Delete the breakpoint which has the index *arg* in the
- :attr:`Breakpoint.bpbynumber`. If *arg* is not numeric or out of range,
- return an error message.
+ Delete the breakpoint which has the index *arg* in the
+ :attr:`Breakpoint.bpbynumber`. If *arg* is not numeric or out of range,
+ return an error message.
-.. method:: Bdb.clear_all_file_breaks(filename)
+ .. method:: clear_all_file_breaks(filename)
- Delete all breakpoints in *filename*. If none were set, an error message is
- returned.
+ Delete all breakpoints in *filename*. If none were set, an error message
+ is returned.
-.. method:: Bdb.clear_all_breaks()
+ .. method:: clear_all_breaks()
- Delete all existing breakpoints.
+ Delete all existing breakpoints.
-.. method:: Bdb.get_break(filename, lineno)
+ .. method:: get_break(filename, lineno)
- Check if there is a breakpoint for *lineno* of *filename*.
+ Check if there is a breakpoint for *lineno* of *filename*.
-.. method:: Bdb.get_breaks(filename, lineno)
+ .. method:: get_breaks(filename, lineno)
- Return all breakpoints for *lineno* in *filename*, or an empty list if none
- are set.
+ Return all breakpoints for *lineno* in *filename*, or an empty list if
+ none are set.
-.. method:: Bdb.get_file_breaks(filename)
+ .. method:: get_file_breaks(filename)
- Return all breakpoints in *filename*, or an empty list if none are set.
+ Return all breakpoints in *filename*, or an empty list if none are set.
-.. method:: Bdb.get_all_breaks()
+ .. method:: get_all_breaks()
- Return all breakpoints that are set.
+ Return all breakpoints that are set.
-Derived classes and clients can call the following methods to get a data
-structure representing a stack trace.
+ Derived classes and clients can call the following methods to get a data
+ structure representing a stack trace.
-.. method:: Bdb.get_stack(f, t)
+ .. method:: get_stack(f, t)
- Get a list of records for a frame and all higher (calling) and lower frames,
- and the size of the higher part.
+ Get a list of records for a frame and all higher (calling) and lower
+ frames, and the size of the higher part.
-.. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': '])
+ .. method:: format_stack_entry(frame_lineno, [lprefix=': '])
- Return a string with information about a stack entry, identified by a
- ``(frame, lineno)`` tuple:
+ Return a string with information about a stack entry, identified by a
+ ``(frame, lineno)`` tuple:
- * The canonical form of the filename which contains the frame.
- * The function name, or ``"<lambda>"``.
- * The input arguments.
- * The return value.
- * The line of code (if it exists).
+ * The canonical form of the filename which contains the frame.
+ * The function name, or ``"<lambda>"``.
+ * The input arguments.
+ * The return value.
+ * The line of code (if it exists).
-The following two methods can be called by clients to use a debugger to debug a
-:term:`statement`, given as a string.
+ The following two methods can be called by clients to use a debugger to debug
+ a :term:`statement`, given as a string.
-.. method:: Bdb.run(cmd, [globals, [locals]])
+ .. method:: run(cmd, [globals, [locals]])
- Debug a statement executed via the :func:`exec` function. *globals*
- defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
+ Debug a statement executed via the :func:`exec` function. *globals*
+ defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
-.. method:: Bdb.runeval(expr, [globals, [locals]])
+ .. method:: runeval(expr, [globals, [locals]])
- Debug an expression executed via the :func:`eval` function. *globals* and
- *locals* have the same meaning as in :meth:`run`.
+ Debug an expression executed via the :func:`eval` function. *globals* and
+ *locals* have the same meaning as in :meth:`run`.
-.. method:: Bdb.runctx(cmd, globals, locals)
+ .. method:: runctx(cmd, globals, locals)
- For backwards compatibility. Calls the :meth:`run` method.
+ For backwards compatibility. Calls the :meth:`run` method.
-.. method:: Bdb.runcall(func, *args, **kwds)
+ .. method:: runcall(func, *args, **kwds)
- Debug a single function call, and return its result.
+ Debug a single function call, and return its result.
Finally, the module defines the following functions:
Modified: python/branches/py3k/Doc/library/bz2.rst
==============================================================================
--- python/branches/py3k/Doc/library/bz2.rst (original)
+++ python/branches/py3k/Doc/library/bz2.rst Fri Apr 25 03:59:09 2008
@@ -44,75 +44,77 @@
.. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]])
- Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
+ Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
or writing. When opened for writing, the file will be created if it doesn't
- exist, and truncated otherwise. If *buffering* is given, ``0`` means unbuffered,
- and larger numbers specify the buffer size; the default is ``0``. If
- *compresslevel* is given, it must be a number between ``1`` and ``9``; the
- default is ``9``. Add a ``'U'`` to mode to open the file for input with
- universal newline support. Any line ending in the input file will be seen as a
- ``'\n'`` in Python. Also, a file so opened gains the attribute
+ exist, and truncated otherwise. If *buffering* is given, ``0`` means
+ unbuffered, and larger numbers specify the buffer size; the default is
+ ``0``. If *compresslevel* is given, it must be a number between ``1`` and
+ ``9``; the default is ``9``. Add a ``'U'`` to mode to open the file for input
+ with universal newline support. Any line ending in the input file will be
+ seen as a ``'\n'`` in Python. Also, a file so opened gains the attribute
:attr:`newlines`; the value for this attribute is one of ``None`` (no newline
- read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the newline
- types seen. Universal newlines are available only when reading. Instances
- support iteration in the same way as normal :class:`file` instances.
+ read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the
+ newline types seen. Universal newlines are available only when
+ reading. Instances support iteration in the same way as normal :class:`file`
+ instances.
-.. method:: BZ2File.close()
+ .. method:: close()
- Close the file. Sets data attribute :attr:`closed` to true. A closed file cannot
- be used for further I/O operations. :meth:`close` may be called more than once
- without error.
+ Close the file. Sets data attribute :attr:`closed` to true. A closed file
+ cannot be used for further I/O operations. :meth:`close` may be called
+ more than once without error.
-.. method:: BZ2File.read([size])
+ .. method:: read([size])
- Read at most *size* uncompressed bytes, returned as a string. If the *size*
- argument is negative or omitted, read until EOF is reached.
+ Read at most *size* uncompressed bytes, returned as a string. If the
+ *size* argument is negative or omitted, read until EOF is reached.
-.. method:: BZ2File.readline([size])
+ .. method:: readline([size])
- Return the next line from the file, as a string, retaining newline. A
- non-negative *size* argument limits the maximum number of bytes to return (an
- incomplete line may be returned then). Return an empty string at EOF.
+ Return the next line from the file, as a string, retaining newline. A
+ non-negative *size* argument limits the maximum number of bytes to return
+ (an incomplete line may be returned then). Return an empty string at EOF.
-.. method:: BZ2File.readlines([size])
+ .. method:: readlines([size])
- Return a list of lines read. The optional *size* argument, if given, is an
- approximate bound on the total number of bytes in the lines returned.
+ Return a list of lines read. The optional *size* argument, if given, is an
+ approximate bound on the total number of bytes in the lines returned.
-.. method:: BZ2File.seek(offset[, whence])
+ .. method:: seek(offset[, whence])
- Move to new file position. Argument *offset* is a byte count. Optional argument
- *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start of file; offset
- should be ``>= 0``); other values are ``os.SEEK_CUR`` or ``1`` (move relative to
- current position; offset can be positive or negative), and ``os.SEEK_END`` or
- ``2`` (move relative to end of file; offset is usually negative, although many
- platforms allow seeking beyond the end of a file).
+ Move to new file position. Argument *offset* is a byte count. Optional
+ argument *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start
+ of file; offset should be ``>= 0``); other values are ``os.SEEK_CUR`` or
+ ``1`` (move relative to current position; offset can be positive or
+ negative), and ``os.SEEK_END`` or ``2`` (move relative to end of file;
+ offset is usually negative, although many platforms allow seeking beyond
+ the end of a file).
- Note that seeking of bz2 files is emulated, and depending on the parameters the
- operation may be extremely slow.
+ Note that seeking of bz2 files is emulated, and depending on the
+ parameters the operation may be extremely slow.
-.. method:: BZ2File.tell()
+ .. method:: tell()
- Return the current file position, an integer.
+ Return the current file position, an integer.
-.. method:: BZ2File.write(data)
+ .. method:: write(data)
- Write string *data* to file. Note that due to buffering, :meth:`close` may be
- needed before the file on disk reflects the data written.
+ Write string *data* to file. Note that due to buffering, :meth:`close` may
+ be needed before the file on disk reflects the data written.
-.. method:: BZ2File.writelines(sequence_of_strings)
+ .. method:: writelines(sequence_of_strings)
- Write the sequence of strings to the file. Note that newlines are not added. The
- sequence can be any iterable object producing strings. This is equivalent to
- calling write() for each string.
+ Write the sequence of strings to the file. Note that newlines are not
+ added. The sequence can be any iterable object producing strings. This is
+ equivalent to calling write() for each string.
Sequential (de)compression
@@ -125,23 +127,23 @@
.. class:: BZ2Compressor([compresslevel])
Create a new compressor object. This object may be used to compress data
- sequentially. If you want to compress data in one shot, use the :func:`compress`
- function instead. The *compresslevel* parameter, if given, must be a number
- between ``1`` and ``9``; the default is ``9``.
+ sequentially. If you want to compress data in one shot, use the
+ :func:`compress` function instead. The *compresslevel* parameter, if given,
+ must be a number between ``1`` and ``9``; the default is ``9``.
-.. method:: BZ2Compressor.compress(data)
+ .. method:: compress(data)
- Provide more data to the compressor object. It will return chunks of compressed
- data whenever possible. When you've finished providing data to compress, call
- the :meth:`flush` method to finish the compression process, and return what is
- left in internal buffers.
+ Provide more data to the compressor object. It will return chunks of
+ compressed data whenever possible. When you've finished providing data to
+ compress, call the :meth:`flush` method to finish the compression process,
+ and return what is left in internal buffers.
-.. method:: BZ2Compressor.flush()
+ .. method:: flush()
- Finish the compression process and return what is left in internal buffers. You
- must not use the compressor object after calling this method.
+ Finish the compression process and return what is left in internal
+ buffers. You must not use the compressor object after calling this method.
.. class:: BZ2Decompressor()
@@ -151,12 +153,13 @@
:func:`decompress` function instead.
-.. method:: BZ2Decompressor.decompress(data)
+ .. method:: decompress(data)
- Provide more data to the decompressor object. It will return chunks of
- decompressed data whenever possible. If you try to decompress data after the end
- of stream is found, :exc:`EOFError` will be raised. If any data was found after
- the end of stream, it'll be ignored and saved in :attr:`unused_data` attribute.
+ Provide more data to the decompressor object. It will return chunks of
+ decompressed data whenever possible. If you try to decompress data after
+ the end of stream is found, :exc:`EOFError` will be raised. If any data
+ was found after the end of stream, it'll be ignored and saved in
+ :attr:`unused_data` attribute.
One-shot (de)compression
@@ -168,13 +171,13 @@
.. function:: compress(data[, compresslevel])
- Compress *data* in one shot. If you want to compress data sequentially, use an
- instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter, if
- given, must be a number between ``1`` and ``9``; the default is ``9``.
+ Compress *data* in one shot. If you want to compress data sequentially, use
+ an instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter,
+ if given, must be a number between ``1`` and ``9``; the default is ``9``.
.. function:: decompress(data)
- Decompress *data* in one shot. If you want to decompress data sequentially, use
- an instance of :class:`BZ2Decompressor` instead.
+ Decompress *data* in one shot. If you want to decompress data sequentially,
+ use an instance of :class:`BZ2Decompressor` instead.
Modified: python/branches/py3k/Doc/library/calendar.rst
==============================================================================
--- python/branches/py3k/Doc/library/calendar.rst (original)
+++ python/branches/py3k/Doc/library/calendar.rst Fri Apr 25 03:59:09 2008
@@ -33,74 +33,75 @@
itself. This is the job of subclasses.
-:class:`Calendar` instances have the following methods:
+ :class:`Calendar` instances have the following methods:
-.. method:: Calendar.iterweekdays(weekday)
+ .. method:: iterweekdays(weekday)
- Return an iterator for the week day numbers that will be used for one week.
- The first value from the iterator will be the same as the value of the
- :attr:`firstweekday` property.
+ Return an iterator for the week day numbers that will be used for one
+ week. The first value from the iterator will be the same as the value of
+ the :attr:`firstweekday` property.
-.. method:: Calendar.itermonthdates(year, month)
+ .. method:: itermonthdates(year, month)
- Return an iterator for the month *month* (1-12) in the year *year*. This
- iterator will return all days (as :class:`datetime.date` objects) for the month
- and all days before the start of the month or after the end of the month that
- are required to get a complete week.
+ Return an iterator for the month *month* (1-12) in the year *year*. This
+ iterator will return all days (as :class:`datetime.date` objects) for the
+ month and all days before the start of the month or after the end of the
+ month that are required to get a complete week.
-.. method:: Calendar.itermonthdays2(year, month)
+ .. method:: itermonthdays2(year, month)
- Return an iterator for the month *month* in the year *year* similar to
- :meth:`itermonthdates`. Days returned will be tuples consisting of a day number
- and a week day number.
+ Return an iterator for the month *month* in the year *year* similar to
+ :meth:`itermonthdates`. Days returned will be tuples consisting of a day
+ number and a week day number.
-.. method:: Calendar.itermonthdays(year, month)
+ .. method:: itermonthdays(year, month)
- Return an iterator for the month *month* in the year *year* similar to
- :meth:`itermonthdates`. Days returned will simply be day numbers.
+ Return an iterator for the month *month* in the year *year* similar to
+ :meth:`itermonthdates`. Days returned will simply be day numbers.
-.. method:: Calendar.monthdatescalendar(year, month)
+ .. method:: monthdatescalendar(year, month)
- Return a list of the weeks in the month *month* of the *year* as full weeks.
- Weeks are lists of seven :class:`datetime.date` objects.
+ Return a list of the weeks in the month *month* of the *year* as full
+ weeks. Weeks are lists of seven :class:`datetime.date` objects.
-.. method:: Calendar.monthdays2calendar(year, month)
+ .. method:: monthdays2calendar(year, month)
- Return a list of the weeks in the month *month* of the *year* as full weeks.
- Weeks are lists of seven tuples of day numbers and weekday numbers.
+ Return a list of the weeks in the month *month* of the *year* as full
+ weeks. Weeks are lists of seven tuples of day numbers and weekday
+ numbers.
-.. method:: Calendar.monthdayscalendar(year, month)
+ .. method:: monthdayscalendar(year, month)
- Return a list of the weeks in the month *month* of the *year* as full weeks.
- Weeks are lists of seven day numbers.
+ Return a list of the weeks in the month *month* of the *year* as full
+ weeks. Weeks are lists of seven day numbers.
-.. method:: Calendar.yeardatescalendar(year[, width])
+ .. method:: yeardatescalendar(year[, width])
- Return the data for the specified year ready for formatting. The return value
- is a list of month rows. Each month row contains up to *width* months
- (defaulting to 3). Each month contains between 4 and 6 weeks and each week
- contains 1--7 days. Days are :class:`datetime.date` objects.
+ Return the data for the specified year ready for formatting. The return
+ value is a list of month rows. Each month row contains up to *width*
+ months (defaulting to 3). Each month contains between 4 and 6 weeks and
+ each week contains 1--7 days. Days are :class:`datetime.date` objects.
-.. method:: Calendar.yeardays2calendar(year[, width])
+ .. method:: yeardays2calendar(year[, width])
- Return the data for the specified year ready for formatting (similar to
- :meth:`yeardatescalendar`). Entries in the week lists are tuples of day
- numbers and weekday numbers. Day numbers outside this month are zero.
+ Return the data for the specified year ready for formatting (similar to
+ :meth:`yeardatescalendar`). Entries in the week lists are tuples of day
+ numbers and weekday numbers. Day numbers outside this month are zero.
-.. method:: Calendar.yeardayscalendar(year[, width])
+ .. method:: yeardayscalendar(year[, width])
- Return the data for the specified year ready for formatting (similar to
- :meth:`yeardatescalendar`). Entries in the week lists are day numbers. Day
- numbers outside this month are zero.
+ Return the data for the specified year ready for formatting (similar to
+ :meth:`yeardatescalendar`). Entries in the week lists are day numbers. Day
+ numbers outside this month are zero.
.. class:: TextCalendar([firstweekday])
@@ -108,35 +109,35 @@
This class can be used to generate plain text calendars.
-:class:`TextCalendar` instances have the following methods:
+ :class:`TextCalendar` instances have the following methods:
-.. method:: TextCalendar.formatmonth(theyear, themonth[, w[, l]])
+ .. method:: formatmonth(theyear, themonth[, w[, l]])
- Return a month's calendar in a multi-line string. If *w* is provided, it
- specifies the width of the date columns, which are centered. If *l* is given,
- it specifies the number of lines that each week will use. Depends on the
- first weekday as specified in the constructor or set by the
- :meth:`setfirstweekday` method.
+ Return a month's calendar in a multi-line string. If *w* is provided, it
+ specifies the width of the date columns, which are centered. If *l* is
+ given, it specifies the number of lines that each week will use. Depends
+ on the first weekday as specified in the constructor or set by the
+ :meth:`setfirstweekday` method.
-.. method:: TextCalendar.prmonth(theyear, themonth[, w[, l]])
+ .. method:: prmonth(theyear, themonth[, w[, l]])
- Print a month's calendar as returned by :meth:`formatmonth`.
+ Print a month's calendar as returned by :meth:`formatmonth`.
-.. method:: TextCalendar.formatyear(theyear, themonth[, w[, l[, c[, m]]]])
+ .. method:: formatyear(theyear, themonth[, w[, l[, c[, m]]]])
- Return a *m*-column calendar for an entire year as a multi-line string.
- Optional parameters *w*, *l*, and *c* are for date column width, lines per
- week, and number of spaces between month columns, respectively. Depends on
- the first weekday as specified in the constructor or set by the
- :meth:`setfirstweekday` method. The earliest year for which a calendar can
- be generated is platform-dependent.
+ Return a *m*-column calendar for an entire year as a multi-line string.
+ Optional parameters *w*, *l*, and *c* are for date column width, lines per
+ week, and number of spaces between month columns, respectively. Depends on
+ the first weekday as specified in the constructor or set by the
+ :meth:`setfirstweekday` method. The earliest year for which a calendar
+ can be generated is platform-dependent.
-.. method:: TextCalendar.pryear(theyear[, w[, l[, c[, m]]]])
+ .. method:: pryear(theyear[, w[, l[, c[, m]]]])
- Print the calendar for an entire year as returned by :meth:`formatyear`.
+ Print the calendar for an entire year as returned by :meth:`formatyear`.
.. class:: HTMLCalendar([firstweekday])
@@ -144,43 +145,44 @@
This class can be used to generate HTML calendars.
-:class:`HTMLCalendar` instances have the following methods:
+ :class:`HTMLCalendar` instances have the following methods:
-.. method:: HTMLCalendar.formatmonth(theyear, themonth[, withyear])
+ .. method:: formatmonth(theyear, themonth[, withyear])
- Return a month's calendar as an HTML table. If *withyear* is true the year will
- be included in the header, otherwise just the month name will be used.
+ Return a month's calendar as an HTML table. If *withyear* is true the year
+ will be included in the header, otherwise just the month name will be
+ used.
-.. method:: HTMLCalendar.formatyear(theyear, themonth[, width])
+ .. method:: formatyear(theyear, themonth[, width])
- Return a year's calendar as an HTML table. *width* (defaulting to 3) specifies
- the number of months per row.
+ Return a year's calendar as an HTML table. *width* (defaulting to 3)
+ specifies the number of months per row.
-.. method:: HTMLCalendar.formatyearpage(theyear[, width[, css[, encoding]]])
+ .. method:: formatyearpage(theyear[, width[, css[, encoding]]])
- Return a year's calendar as a complete HTML page. *width* (defaulting to 3)
- specifies the number of months per row. *css* is the name for the cascading
- style sheet to be used. :const:`None` can be passed if no style sheet should be
- used. *encoding* specifies the encoding to be used for the output (defaulting to
- the system default encoding).
+ Return a year's calendar as a complete HTML page. *width* (defaulting to
+ 3) specifies the number of months per row. *css* is the name for the
+ cascading style sheet to be used. :const:`None` can be passed if no style
+ sheet should be used. *encoding* specifies the encoding to be used for the
+ output (defaulting to the system default encoding).
.. class:: LocaleTextCalendar([firstweekday[, locale]])
This subclass of :class:`TextCalendar` can be passed a locale name in the
- constructor and will return month and weekday names in the specified locale. If
- this locale includes an encoding all strings containing month and weekday names
- will be returned as unicode.
+ constructor and will return month and weekday names in the specified
+ locale. If this locale includes an encoding all strings containing month and
+ weekday names will be returned as unicode.
.. class:: LocaleHTMLCalendar([firstweekday[, locale]])
This subclass of :class:`HTMLCalendar` can be passed a locale name in the
- constructor and will return month and weekday names in the specified locale. If
- this locale includes an encoding all strings containing month and weekday names
- will be returned as unicode.
+ constructor and will return month and weekday names in the specified
+ locale. If this locale includes an encoding all strings containing month and
+ weekday names will be returned as unicode.
For simple text calendars this module provides the following functions.
Modified: python/branches/py3k/Doc/library/cgihttpserver.rst
==============================================================================
--- python/branches/py3k/Doc/library/cgihttpserver.rst (original)
+++ python/branches/py3k/Doc/library/cgihttpserver.rst Fri Apr 25 03:59:09 2008
@@ -43,22 +43,22 @@
and serve the output, instead of serving files, if the request leads to
somewhere below the ``cgi_directories`` path.
-The :class:`CGIHTTPRequestHandler` defines the following data member:
+ The :class:`CGIHTTPRequestHandler` defines the following data member:
-.. attribute:: CGIHTTPRequestHandler.cgi_directories
+ .. attribute:: cgi_directories
- This defaults to ``['/cgi-bin', '/htbin']`` and describes directories to treat
- as containing CGI scripts.
+ This defaults to ``['/cgi-bin', '/htbin']`` and describes directories to
+ treat as containing CGI scripts.
-The :class:`CGIHTTPRequestHandler` defines the following methods:
+ The :class:`CGIHTTPRequestHandler` defines the following methods:
-.. method:: CGIHTTPRequestHandler.do_POST()
+ .. method:: do_POST()
- This method serves the ``'POST'`` request type, only allowed for CGI scripts.
- Error 501, "Can only POST to CGI scripts", is output when trying to POST to a
- non-CGI url.
+ This method serves the ``'POST'`` request type, only allowed for CGI
+ scripts. Error 501, "Can only POST to CGI scripts", is output when trying
+ to POST to a non-CGI url.
Note that CGI scripts will be run with UID of user nobody, for security reasons.
Problems with the CGI script will be translated to error 403.
Modified: python/branches/py3k/Doc/library/chunk.rst
==============================================================================
--- python/branches/py3k/Doc/library/chunk.rst (original)
+++ python/branches/py3k/Doc/library/chunk.rst Fri Apr 25 03:59:09 2008
@@ -66,62 +66,64 @@
optional argument *inclheader* is true, the size given in the chunk header
includes the size of the header. The default value is false.
-A :class:`Chunk` object supports the following methods:
+ A :class:`Chunk` object supports the following methods:
-.. method:: Chunk.getname()
+ .. method:: getname()
- Returns the name (ID) of the chunk. This is the first 4 bytes of the chunk.
+ Returns the name (ID) of the chunk. This is the first 4 bytes of the
+ chunk.
-.. method:: Chunk.getsize()
+ .. method:: getsize()
- Returns the size of the chunk.
+ Returns the size of the chunk.
-.. method:: Chunk.close()
+ .. method:: close()
- Close and skip to the end of the chunk. This does not close the underlying
- file.
+ Close and skip to the end of the chunk. This does not close the
+ underlying file.
-The remaining methods will raise :exc:`IOError` if called after the
-:meth:`close` method has been called.
+ The remaining methods will raise :exc:`IOError` if called after the
+ :meth:`close` method has been called.
-.. method:: Chunk.isatty()
+ .. method:: isatty()
- Returns ``False``.
+ Returns ``False``.
-.. method:: Chunk.seek(pos[, whence])
+ .. method:: seek(pos[, whence])
- Set the chunk's current position. The *whence* argument is optional and
- defaults to ``0`` (absolute file positioning); other values are ``1`` (seek
- relative to the current position) and ``2`` (seek relative to the file's end).
- There is no return value. If the underlying file does not allow seek, only
- forward seeks are allowed.
+ Set the chunk's current position. The *whence* argument is optional and
+ defaults to ``0`` (absolute file positioning); other values are ``1``
+ (seek relative to the current position) and ``2`` (seek relative to the
+ file's end). There is no return value. If the underlying file does not
+ allow seek, only forward seeks are allowed.
-.. method:: Chunk.tell()
+ .. method:: tell()
- Return the current position into the chunk.
+ Return the current position into the chunk.
-.. method:: Chunk.read([size])
+ .. method:: read([size])
- Read at most *size* bytes from the chunk (less if the read hits the end of the
- chunk before obtaining *size* bytes). If the *size* argument is negative or
- omitted, read all data until the end of the chunk. The bytes are returned as a
- string object. An empty string is returned when the end of the chunk is
- encountered immediately.
+ Read at most *size* bytes from the chunk (less if the read hits the end of
+ the chunk before obtaining *size* bytes). If the *size* argument is
+ negative or omitted, read all data until the end of the chunk. The bytes
+ are returned as a string object. An empty string is returned when the end
+ of the chunk is encountered immediately.
-.. method:: Chunk.skip()
+ .. method:: skip()
+
+ Skip to the end of the chunk. All further calls to :meth:`read` for the
+ chunk will return ``''``. If you are not interested in the contents of
+ the chunk, this method should be called so that the file points to the
+ start of the next chunk.
- Skip to the end of the chunk. All further calls to :meth:`read` for the chunk
- will return ``''``. If you are not interested in the contents of the chunk,
- this method should be called so that the file points to the start of the next
- chunk.
.. rubric:: Footnotes
Modified: python/branches/py3k/Doc/library/codecs.rst
==============================================================================
--- python/branches/py3k/Doc/library/codecs.rst (original)
+++ python/branches/py3k/Doc/library/codecs.rst Fri Apr 25 03:59:09 2008
@@ -425,16 +425,16 @@
:func:`register_error`.
-.. method:: IncrementalEncoder.encode(object[, final])
+ .. method:: encode(object[, final])
- Encodes *object* (taking the current state of the encoder into account) and
- returns the resulting encoded object. If this is the last call to :meth:`encode`
- *final* must be true (the default is false).
+ Encodes *object* (taking the current state of the encoder into account)
+ and returns the resulting encoded object. If this is the last call to
+ :meth:`encode` *final* must be true (the default is false).
-.. method:: IncrementalEncoder.reset()
+ .. method:: reset()
- Reset the encoder to the initial state.
+ Reset the encoder to the initial state.
.. method:: IncrementalEncoder.getstate()
@@ -488,41 +488,42 @@
:func:`register_error`.
-.. method:: IncrementalDecoder.decode(object[, final])
+ .. method:: decode(object[, final])
- Decodes *object* (taking the current state of the decoder into account) and
- returns the resulting decoded object. If this is the last call to :meth:`decode`
- *final* must be true (the default is false). If *final* is true the decoder must
- decode the input completely and must flush all buffers. If this isn't possible
- (e.g. because of incomplete byte sequences at the end of the input) it must
- initiate error handling just like in the stateless case (which might raise an
- exception).
+ Decodes *object* (taking the current state of the decoder into account)
+ and returns the resulting decoded object. If this is the last call to
+ :meth:`decode` *final* must be true (the default is false). If *final* is
+ true the decoder must decode the input completely and must flush all
+ buffers. If this isn't possible (e.g. because of incomplete byte sequences
+ at the end of the input) it must initiate error handling just like in the
+ stateless case (which might raise an exception).
-.. method:: IncrementalDecoder.reset()
+ .. method:: reset()
- Reset the decoder to the initial state.
+ Reset the decoder to the initial state.
-.. method:: IncrementalDecoder.getstate()
+ .. method:: getstate()
- Return the current state of the decoder. This must be a tuple with two items,
- the first must be the buffer containing the still undecoded input. The second
- must be an integer and can be additional state info. (The implementation should
- make sure that ``0`` is the most common additional state info.) If this
- additional state info is ``0`` it must be possible to set the decoder to the
- state which has no input buffered and ``0`` as the additional state info, so
- that feeding the previously buffered input to the decoder returns it to the
- previous state without producing any output. (Additional state info that is more
- complicated than integers can be converted into an integer by
- marshaling/pickling the info and encoding the bytes of the resulting string into
- an integer.)
+ Return the current state of the decoder. This must be a tuple with two
+ items, the first must be the buffer containing the still undecoded
+ input. The second must be an integer and can be additional state
+ info. (The implementation should make sure that ``0`` is the most common
+ additional state info.) If this additional state info is ``0`` it must be
+ possible to set the decoder to the state which has no input buffered and
+ ``0`` as the additional state info, so that feeding the previously
+ buffered input to the decoder returns it to the previous state without
+ producing any output. (Additional state info that is more complicated than
+ integers can be converted into an integer by marshaling/pickling the info
+ and encoding the bytes of the resulting string into an integer.)
-.. method:: IncrementalDecoder.setstate(state)
+ .. method:: setstate(state)
+
+ Set the state of the encoder to *state*. *state* must be a decoder state
+ returned by :meth:`getstate`.
- Set the state of the encoder to *state*. *state* must be a decoder state
- returned by :meth:`getstate`.
The :class:`StreamWriter` and :class:`StreamReader` classes provide generic
working interfaces which can be used to implement new encoding submodules very
@@ -570,24 +571,25 @@
:func:`register_error`.
-.. method:: StreamWriter.write(object)
+ .. method:: write(object)
+
+ Writes the object's contents encoded to the stream.
- Writes the object's contents encoded to the stream.
+ .. method:: writelines(list)
-.. method:: StreamWriter.writelines(list)
+ Writes the concatenated list of strings to the stream (possibly by reusing
+ the :meth:`write` method).
- Writes the concatenated list of strings to the stream (possibly by reusing the
- :meth:`write` method).
+ .. method:: reset()
-.. method:: StreamWriter.reset()
+ Flushes and resets the codec buffers used for keeping state.
- Flushes and resets the codec buffers used for keeping state.
+ Calling this method should ensure that the data on the output is put into
+ a clean state that allows appending of new fresh data without having to
+ rescan the whole stream to recover state.
- Calling this method should ensure that the data on the output is put into a
- clean state that allows appending of new fresh data without having to rescan the
- whole stream to recover state.
In addition to the above methods, the :class:`StreamWriter` must also inherit
all other methods and attributes from the underlying stream.
@@ -630,55 +632,59 @@
:func:`register_error`.
-.. method:: StreamReader.read([size[, chars, [firstline]]])
+ .. method:: read([size[, chars, [firstline]]])
- Decodes data from the stream and returns the resulting object.
+ Decodes data from the stream and returns the resulting object.
- *chars* indicates the number of characters to read from the stream. :func:`read`
- will never return more than *chars* characters, but it might return less, if
- there are not enough characters available.
+ *chars* indicates the number of characters to read from the
+ stream. :func:`read` will never return more than *chars* characters, but
+ it might return less, if there are not enough characters available.
- *size* indicates the approximate maximum number of bytes to read from the stream
- for decoding purposes. The decoder can modify this setting as appropriate. The
- default value -1 indicates to read and decode as much as possible. *size* is
- intended to prevent having to decode huge files in one step.
+ *size* indicates the approximate maximum number of bytes to read from the
+ stream for decoding purposes. The decoder can modify this setting as
+ appropriate. The default value -1 indicates to read and decode as much as
+ possible. *size* is intended to prevent having to decode huge files in
+ one step.
- *firstline* indicates that it would be sufficient to only return the first line,
- if there are decoding errors on later lines.
+ *firstline* indicates that it would be sufficient to only return the first
+ line, if there are decoding errors on later lines.
- The method should use a greedy read strategy meaning that it should read as much
- data as is allowed within the definition of the encoding and the given size,
- e.g. if optional encoding endings or state markers are available on the stream,
- these should be read too.
+ The method should use a greedy read strategy meaning that it should read
+ as much data as is allowed within the definition of the encoding and the
+ given size, e.g. if optional encoding endings or state markers are
+ available on the stream, these should be read too.
-.. method:: StreamReader.readline([size[, keepends]])
+ .. method:: readline([size[, keepends]])
- Read one line from the input stream and return the decoded data.
+ Read one line from the input stream and return the decoded data.
- *size*, if given, is passed as size argument to the stream's :meth:`readline`
- method.
+ *size*, if given, is passed as size argument to the stream's
+ :meth:`readline` method.
- If *keepends* is false line-endings will be stripped from the lines returned.
+ If *keepends* is false line-endings will be stripped from the lines
+ returned.
-.. method:: StreamReader.readlines([sizehint[, keepends]])
+ .. method:: readlines([sizehint[, keepends]])
- Read all lines available on the input stream and return them as a list of lines.
+ Read all lines available on the input stream and return them as a list of
+ lines.
- Line-endings are implemented using the codec's decoder method and are included
- in the list entries if *keepends* is true.
+ Line-endings are implemented using the codec's decoder method and are
+ included in the list entries if *keepends* is true.
- *sizehint*, if given, is passed as the *size* argument to the stream's
- :meth:`read` method.
+ *sizehint*, if given, is passed as the *size* argument to the stream's
+ :meth:`read` method.
-.. method:: StreamReader.reset()
+ .. method:: reset()
- Resets the codec buffers used for keeping state.
+ Resets the codec buffers used for keeping state.
+
+ Note that no stream repositioning should take place. This method is
+ primarily intended to be able to recover from decoding errors.
- Note that no stream repositioning should take place. This method is primarily
- intended to be able to recover from decoding errors.
In addition to the above methods, the :class:`StreamReader` must also inherit
all other methods and attributes from the underlying stream.
@@ -747,6 +753,7 @@
Error handling is done in the same way as defined for the stream readers and
writers.
+
:class:`StreamRecoder` instances define the combined interfaces of
:class:`StreamReader` and :class:`StreamWriter` classes. They inherit all other
methods and attributes from the underlying stream.
Modified: python/branches/py3k/Doc/library/collections.rst
==============================================================================
--- python/branches/py3k/Doc/library/collections.rst (original)
+++ python/branches/py3k/Doc/library/collections.rst Fri Apr 25 03:59:09 2008
@@ -166,59 +166,60 @@
where only the most recent activity is of interest.
-Deque objects support the following methods:
+ Deque objects support the following methods:
-.. method:: deque.append(x)
+ .. method:: append(x)
- Add *x* to the right side of the deque.
+ Add *x* to the right side of the deque.
-.. method:: deque.appendleft(x)
+ .. method:: appendleft(x)
- Add *x* to the left side of the deque.
+ Add *x* to the left side of the deque.
-.. method:: deque.clear()
+ .. method:: clear()
- Remove all elements from the deque leaving it with length 0.
+ Remove all elements from the deque leaving it with length 0.
-.. method:: deque.extend(iterable)
+ .. method:: extend(iterable)
- Extend the right side of the deque by appending elements from the iterable
- argument.
+ Extend the right side of the deque by appending elements from the iterable
+ argument.
-.. method:: deque.extendleft(iterable)
+ .. method:: extendleft(iterable)
- Extend the left side of the deque by appending elements from *iterable*. Note,
- the series of left appends results in reversing the order of elements in the
- iterable argument.
+ Extend the left side of the deque by appending elements from *iterable*.
+ Note, the series of left appends results in reversing the order of
+ elements in the iterable argument.
-.. method:: deque.pop()
+ .. method:: pop()
- Remove and return an element from the right side of the deque. If no elements
- are present, raises an :exc:`IndexError`.
+ Remove and return an element from the right side of the deque. If no
+ elements are present, raises an :exc:`IndexError`.
-.. method:: deque.popleft()
+ .. method:: popleft()
- Remove and return an element from the left side of the deque. If no elements are
- present, raises an :exc:`IndexError`.
+ Remove and return an element from the left side of the deque. If no
+ elements are present, raises an :exc:`IndexError`.
-.. method:: deque.remove(value)
+ .. method:: remove(value)
- Removed the first occurrence of *value*. If not found, raises a
- :exc:`ValueError`.
+ Removed the first occurrence of *value*. If not found, raises a
+ :exc:`ValueError`.
-.. method:: deque.rotate(n)
+ .. method:: rotate(n)
+
+ Rotate the deque *n* steps to the right. If *n* is negative, rotate to
+ the left. Rotating one step to the right is equivalent to:
+ ``d.appendleft(d.pop())``.
- Rotate the deque *n* steps to the right. If *n* is negative, rotate to the
- left. Rotating one step to the right is equivalent to:
- ``d.appendleft(d.pop())``.
In addition to the above, deques support iteration, pickling, ``len(d)``,
``reversed(d)``, ``copy.copy(d)``, ``copy.deepcopy(d)``, membership testing with
@@ -348,32 +349,34 @@
arguments.
-:class:`defaultdict` objects support the following method in addition to the
-standard :class:`dict` operations:
+ :class:`defaultdict` objects support the following method in addition to the
+ standard :class:`dict` operations:
+
+ .. method:: defaultdict.__missing__(key)
-.. method:: defaultdict.__missing__(key)
+ If the :attr:`default_factory` attribute is ``None``, this raises an
+ :exc:`KeyError` exception with the *key* as argument.
- If the :attr:`default_factory` attribute is ``None``, this raises an
- :exc:`KeyError` exception with the *key* as argument.
+ If :attr:`default_factory` is not ``None``, it is called without arguments
+ to provide a default value for the given *key*, this value is inserted in
+ the dictionary for the *key*, and returned.
- If :attr:`default_factory` is not ``None``, it is called without arguments to
- provide a default value for the given *key*, this value is inserted in the
- dictionary for the *key*, and returned.
+ If calling :attr:`default_factory` raises an exception this exception is
+ propagated unchanged.
- If calling :attr:`default_factory` raises an exception this exception is
- propagated unchanged.
+ This method is called by the :meth:`__getitem__` method of the
+ :class:`dict` class when the requested key is not found; whatever it
+ returns or raises is then returned or raised by :meth:`__getitem__`.
- This method is called by the :meth:`__getitem__` method of the :class:`dict`
- class when the requested key is not found; whatever it returns or raises is then
- returned or raised by :meth:`__getitem__`.
-:class:`defaultdict` objects support the following instance variable:
+ :class:`defaultdict` objects support the following instance variable:
-.. attribute:: defaultdict.default_factory
+ .. attribute:: defaultdict.default_factory
- This attribute is used by the :meth:`__missing__` method; it is initialized from
- the first argument to the constructor, if present, or to ``None``, if absent.
+ This attribute is used by the :meth:`__missing__` method; it is
+ initialized from the first argument to the constructor, if present, or to
+ ``None``, if absent.
.. _defaultdict-examples:
Modified: python/branches/py3k/Doc/library/csv.rst
==============================================================================
--- python/branches/py3k/Doc/library/csv.rst (original)
+++ python/branches/py3k/Doc/library/csv.rst Fri Apr 25 03:59:09 2008
@@ -209,19 +209,20 @@
The :class:`Sniffer` class is used to deduce the format of a CSV file.
-The :class:`Sniffer` class provides two methods:
+ The :class:`Sniffer` class provides two methods:
-.. method:: Sniffer.sniff(sample[, delimiters=None])
+ .. method:: sniff(sample[, delimiters=None])
- Analyze the given *sample* and return a :class:`Dialect` subclass reflecting the
- parameters found. If the optional *delimiters* parameter is given, it is
- interpreted as a string containing possible valid delimiter characters.
+ Analyze the given *sample* and return a :class:`Dialect` subclass
+ reflecting the parameters found. If the optional *delimiters* parameter
+ is given, it is interpreted as a string containing possible valid
+ delimiter characters.
-.. method:: Sniffer.has_header(sample)
+ .. method:: has_header(sample)
- Analyze the sample text (presumed to be in CSV format) and return :const:`True`
- if the first row appears to be a series of column headers.
+ Analyze the sample text (presumed to be in CSV format) and return
+ :const:`True` if the first row appears to be a series of column headers.
An example for :class:`Sniffer` use::
Modified: python/branches/py3k/Doc/library/ctypes.rst
==============================================================================
--- python/branches/py3k/Doc/library/ctypes.rst (original)
+++ python/branches/py3k/Doc/library/ctypes.rst Fri Apr 25 03:59:09 2008
@@ -1441,10 +1441,10 @@
so repeated attribute accesses return the same library each time.
-.. method:: LibraryLoader.LoadLibrary(name)
+ .. method:: LoadLibrary(name)
- Load a shared library into the process and return it. This method always
- returns a new instance of the library.
+ Load a shared library into the process and return it. This method always
+ returns a new instance of the library.
These prefabricated library loaders are available:
@@ -1501,50 +1501,51 @@
Base class for C callable foreign functions.
-Instances of foreign functions are also C compatible data types; they represent
-C function pointers.
+ Instances of foreign functions are also C compatible data types; they
+ represent C function pointers.
-This behavior can be customized by assigning to special attributes of the
-foreign function object.
+ This behavior can be customized by assigning to special attributes of the
+ foreign function object.
-.. attribute:: _FuncPtr.restype
+ .. attribute:: restype
- Assign a ctypes type to specify the result type of the foreign function. Use
- ``None`` for ``void`` a function not returning anything.
+ Assign a ctypes type to specify the result type of the foreign function.
+ Use ``None`` for ``void`` a function not returning anything.
- It is possible to assign a callable Python object that is not a ctypes type, in
- this case the function is assumed to return a C ``int``, and the callable will
- be called with this integer, allowing to do further processing or error
- checking. Using this is deprecated, for more flexible post processing or error
- checking use a ctypes data type as :attr:`restype` and assign a callable to the
- :attr:`errcheck` attribute.
+ It is possible to assign a callable Python object that is not a ctypes
+ type, in this case the function is assumed to return a C ``int``, and the
+ callable will be called with this integer, allowing to do further
+ processing or error checking. Using this is deprecated, for more flexible
+ post processing or error checking use a ctypes data type as
+ :attr:`restype` and assign a callable to the :attr:`errcheck` attribute.
-.. attribute:: _FuncPtr.argtypes
+ .. attribute:: argtypes
- Assign a tuple of ctypes types to specify the argument types that the function
- accepts. Functions using the ``stdcall`` calling convention can only be called
- with the same number of arguments as the length of this tuple; functions using
- the C calling convention accept additional, unspecified arguments as well.
+ Assign a tuple of ctypes types to specify the argument types that the
+ function accepts. Functions using the ``stdcall`` calling convention can
+ only be called with the same number of arguments as the length of this
+ tuple; functions using the C calling convention accept additional,
+ unspecified arguments as well.
- When a foreign function is called, each actual argument is passed to the
- :meth:`from_param` class method of the items in the :attr:`argtypes` tuple, this
- method allows to adapt the actual argument to an object that the foreign
- function accepts. For example, a :class:`c_char_p` item in the :attr:`argtypes`
- tuple will convert a unicode string passed as argument into an byte string using
- ctypes conversion rules.
+ When a foreign function is called, each actual argument is passed to the
+ :meth:`from_param` class method of the items in the :attr:`argtypes`
+ tuple, this method allows to adapt the actual argument to an object that
+ the foreign function accepts. For example, a :class:`c_char_p` item in
+ the :attr:`argtypes` tuple will convert a unicode string passed as
+ argument into an byte string using ctypes conversion rules.
- New: It is now possible to put items in argtypes which are not ctypes types, but
- each item must have a :meth:`from_param` method which returns a value usable as
- argument (integer, string, ctypes instance). This allows to define adapters
- that can adapt custom objects as function parameters.
+ New: It is now possible to put items in argtypes which are not ctypes
+ types, but each item must have a :meth:`from_param` method which returns a
+ value usable as argument (integer, string, ctypes instance). This allows
+ to define adapters that can adapt custom objects as function parameters.
-.. attribute:: _FuncPtr.errcheck
+ .. attribute:: errcheck
- Assign a Python function or another callable to this attribute. The callable
- will be called with three or more arguments:
+ Assign a Python function or another callable to this attribute. The
+ callable will be called with three or more arguments:
.. function:: callable(result, func, arguments)
@@ -1559,9 +1560,9 @@
``arguments`` is a tuple containing the parameters originally passed to the
function call, this allows to specialize the behavior on the arguments used.
- The object that this function returns will be returned from the foreign function
- call, but it can also check the result value and raise an exception if the
- foreign function call failed.
+ The object that this function returns will be returned from the foreign
+ function call, but it can also check the result value and raise an exception
+ if the foreign function call failed.
.. exception:: ArgumentError()
@@ -1943,57 +1944,58 @@
:attr:`_objects`; this contains other Python objects that need to be kept alive
in case the memory block contains pointers.
-Common methods of ctypes data types, these are all class methods (to be exact,
-they are methods of the :term:`metaclass`):
+ Common methods of ctypes data types, these are all class methods (to be
+ exact, they are methods of the :term:`metaclass`):
-.. method:: _CData.from_address(address)
+ .. method:: from_address(address)
- This method returns a ctypes type instance using the memory specified by address
- which must be an integer.
+ This method returns a ctypes type instance using the memory specified by
+ address which must be an integer.
-.. method:: _CData.from_param(obj)
+ .. method:: from_param(obj)
- This method adapts obj to a ctypes type. It is called with the actual object
- used in a foreign function call, when the type is present in the foreign
- functions :attr:`argtypes` tuple; it must return an object that can be used as
- function call parameter.
+ This method adapts obj to a ctypes type. It is called with the actual
+ object used in a foreign function call, when the type is present in the
+ foreign functions :attr:`argtypes` tuple; it must return an object that
+ can be used as function call parameter.
- All ctypes data types have a default implementation of this classmethod,
- normally it returns ``obj`` if that is an instance of the type. Some types
- accept other objects as well.
+ All ctypes data types have a default implementation of this classmethod,
+ normally it returns ``obj`` if that is an instance of the type. Some
+ types accept other objects as well.
-.. method:: _CData.in_dll(library, name)
+ .. method:: in_dll(library, name)
- This method returns a ctypes type instance exported by a shared library. *name*
- is the name of the symbol that exports the data, *library* is the loaded shared
- library.
+ This method returns a ctypes type instance exported by a shared
+ library. *name* is the name of the symbol that exports the data, *library*
+ is the loaded shared library.
-Common instance variables of ctypes data types:
+ Common instance variables of ctypes data types:
-.. attribute:: _CData._b_base_
- Sometimes ctypes data instances do not own the memory block they contain,
- instead they share part of the memory block of a base object. The
- :attr:`_b_base_` read-only member is the root ctypes object that owns the memory
- block.
+ .. attribute:: _b_base_
+ Sometimes ctypes data instances do not own the memory block they contain,
+ instead they share part of the memory block of a base object. The
+ :attr:`_b_base_` read-only member is the root ctypes object that owns the
+ memory block.
-.. attribute:: _CData._b_needsfree_
- This read-only variable is true when the ctypes data instance has allocated the
- memory block itself, false otherwise.
+ .. attribute:: _b_needsfree_
+ This read-only variable is true when the ctypes data instance has
+ allocated the memory block itself, false otherwise.
-.. attribute:: _CData._objects
- This member is either ``None`` or a dictionary containing Python objects that
- need to be kept alive so that the memory block contents is kept valid. This
- object is only exposed for debugging; never modify the contents of this
- dictionary.
+ .. attribute:: _objects
+
+ This member is either ``None`` or a dictionary containing Python objects
+ that need to be kept alive so that the memory block contents is kept
+ valid. This object is only exposed for debugging; never modify the
+ contents of this dictionary.
.. _ctypes-fundamental-data-types-2:
@@ -2010,19 +2012,20 @@
so it inherits their methods and attributes. ctypes data types that are not
and do not contain pointers can now be pickled.
-Instances have a single attribute:
+ Instances have a single attribute:
-.. attribute:: _SimpleCData.value
+ .. attribute:: value
- This attribute contains the actual value of the instance. For integer and
- pointer types, it is an integer, for character types, it is a single character
- string, for character pointer types it is a Python string or unicode string.
+ This attribute contains the actual value of the instance. For integer and
+ pointer types, it is an integer, for character types, it is a single
+ character string, for character pointer types it is a Python string or
+ unicode string.
- When the ``value`` attribute is retrieved from a ctypes instance, usually a new
- object is returned each time. ``ctypes`` does *not* implement original object
- return, always a new object is constructed. The same is true for all other
- ctypes object instances.
+ When the ``value`` attribute is retrieved from a ctypes instance, usually
+ a new object is returned each time. ``ctypes`` does *not* implement
+ original object return, always a new object is constructed. The same is
+ true for all other ctypes object instances.
Fundamental data types, when returned as foreign function call results, or, for
example, by retrieving structure field members or array items, are transparently
@@ -2258,90 +2261,92 @@
Abstract base class for structures in *native* byte order.
-Concrete structure and union types must be created by subclassing one of these
-types, and at least define a :attr:`_fields_` class variable. ``ctypes`` will
-create :term:`descriptor`\s which allow reading and writing the fields by direct
-attribute accesses. These are the
+ Concrete structure and union types must be created by subclassing one of these
+ types, and at least define a :attr:`_fields_` class variable. ``ctypes`` will
+ create :term:`descriptor`\s which allow reading and writing the fields by direct
+ attribute accesses. These are the
-.. attribute:: Structure._fields_
+ .. attribute:: _fields_
- A sequence defining the structure fields. The items must be 2-tuples or
- 3-tuples. The first item is the name of the field, the second item specifies
- the type of the field; it can be any ctypes data type.
+ A sequence defining the structure fields. The items must be 2-tuples or
+ 3-tuples. The first item is the name of the field, the second item
+ specifies the type of the field; it can be any ctypes data type.
- For integer type fields like :class:`c_int`, a third optional item can be given.
- It must be a small positive integer defining the bit width of the field.
+ For integer type fields like :class:`c_int`, a third optional item can be
+ given. It must be a small positive integer defining the bit width of the
+ field.
- Field names must be unique within one structure or union. This is not checked,
- only one field can be accessed when names are repeated.
+ Field names must be unique within one structure or union. This is not
+ checked, only one field can be accessed when names are repeated.
- It is possible to define the :attr:`_fields_` class variable *after* the class
- statement that defines the Structure subclass, this allows to create data types
- that directly or indirectly reference themselves::
+ It is possible to define the :attr:`_fields_` class variable *after* the
+ class statement that defines the Structure subclass, this allows to create
+ data types that directly or indirectly reference themselves::
- class List(Structure):
- pass
- List._fields_ = [("pnext", POINTER(List)),
- ...
- ]
+ class List(Structure):
+ pass
+ List._fields_ = [("pnext", POINTER(List)),
+ ...
+ ]
- The :attr:`_fields_` class variable must, however, be defined before the type is
- first used (an instance is created, ``sizeof()`` is called on it, and so on).
- Later assignments to the :attr:`_fields_` class variable will raise an
- AttributeError.
+ The :attr:`_fields_` class variable must, however, be defined before the
+ type is first used (an instance is created, ``sizeof()`` is called on it,
+ and so on). Later assignments to the :attr:`_fields_` class variable will
+ raise an AttributeError.
- Structure and union subclass constructors accept both positional and named
- arguments. Positional arguments are used to initialize the fields in the same
- order as they appear in the :attr:`_fields_` definition, named arguments are
- used to initialize the fields with the corresponding name.
+ Structure and union subclass constructors accept both positional and named
+ arguments. Positional arguments are used to initialize the fields in the
+ same order as they appear in the :attr:`_fields_` definition, named
+ arguments are used to initialize the fields with the corresponding name.
- It is possible to defined sub-subclasses of structure types, they inherit the
- fields of the base class plus the :attr:`_fields_` defined in the sub-subclass,
- if any.
+ It is possible to defined sub-subclasses of structure types, they inherit
+ the fields of the base class plus the :attr:`_fields_` defined in the
+ sub-subclass, if any.
-.. attribute:: Structure._pack_
+ .. attribute:: _pack_
- An optional small integer that allows to override the alignment of structure
- fields in the instance. :attr:`_pack_` must already be defined when
- :attr:`_fields_` is assigned, otherwise it will have no effect.
+ An optional small integer that allows to override the alignment of
+ structure fields in the instance. :attr:`_pack_` must already be defined
+ when :attr:`_fields_` is assigned, otherwise it will have no effect.
-.. attribute:: Structure._anonymous_
+ .. attribute:: _anonymous_
- An optional sequence that lists the names of unnamed (anonymous) fields.
- ``_anonymous_`` must be already defined when :attr:`_fields_` is assigned,
- otherwise it will have no effect.
+ An optional sequence that lists the names of unnamed (anonymous) fields.
+ ``_anonymous_`` must be already defined when :attr:`_fields_` is assigned,
+ otherwise it will have no effect.
- The fields listed in this variable must be structure or union type fields.
- ``ctypes`` will create descriptors in the structure type that allows to access
- the nested fields directly, without the need to create the structure or union
- field.
+ The fields listed in this variable must be structure or union type fields.
+ ``ctypes`` will create descriptors in the structure type that allows to
+ access the nested fields directly, without the need to create the
+ structure or union field.
- Here is an example type (Windows)::
+ Here is an example type (Windows)::
- class _U(Union):
- _fields_ = [("lptdesc", POINTER(TYPEDESC)),
- ("lpadesc", POINTER(ARRAYDESC)),
- ("hreftype", HREFTYPE)]
+ class _U(Union):
+ _fields_ = [("lptdesc", POINTER(TYPEDESC)),
+ ("lpadesc", POINTER(ARRAYDESC)),
+ ("hreftype", HREFTYPE)]
- class TYPEDESC(Structure):
- _fields_ = [("u", _U),
- ("vt", VARTYPE)]
+ class TYPEDESC(Structure):
+ _fields_ = [("u", _U),
+ ("vt", VARTYPE)]
- _anonymous_ = ("u",)
+ _anonymous_ = ("u",)
- The ``TYPEDESC`` structure describes a COM data type, the ``vt`` field specifies
- which one of the union fields is valid. Since the ``u`` field is defined as
- anonymous field, it is now possible to access the members directly off the
- TYPEDESC instance. ``td.lptdesc`` and ``td.u.lptdesc`` are equivalent, but the
- former is faster since it does not need to create a temporary union instance::
+ The ``TYPEDESC`` structure describes a COM data type, the ``vt`` field
+ specifies which one of the union fields is valid. Since the ``u`` field
+ is defined as anonymous field, it is now possible to access the members
+ directly off the TYPEDESC instance. ``td.lptdesc`` and ``td.u.lptdesc``
+ are equivalent, but the former is faster since it does not need to create
+ a temporary union instance::
- td = TYPEDESC()
- td.vt = VT_PTR
- td.lptdesc = POINTER(some_type)
- td.u.lptdesc = POINTER(some_type)
+ td = TYPEDESC()
+ td.vt = VT_PTR
+ td.lptdesc = POINTER(some_type)
+ td.u.lptdesc = POINTER(some_type)
It is possible to defined sub-subclasses of structures, they inherit the fields
of the base class. If the subclass definition has a separate :attr:`_fields_`
Modified: python/branches/py3k/Doc/library/curses.rst
==============================================================================
--- python/branches/py3k/Doc/library/curses.rst (original)
+++ python/branches/py3k/Doc/library/curses.rst Fri Apr 25 03:59:09 2008
@@ -1567,92 +1567,94 @@
containing window, with coordinates ``(0, 0)``. The instance's
:attr:`stripspaces` flag is initially on.
-:class:`Textbox` objects have the following methods:
+ :class:`Textbox` objects have the following methods:
-.. method:: Textbox.edit([validator])
+ .. method:: edit([validator])
- This is the entry point you will normally use. It accepts editing keystrokes
- until one of the termination keystrokes is entered. If *validator* is supplied,
- it must be a function. It will be called for each keystroke entered with the
- keystroke as a parameter; command dispatch is done on the result. This method
- returns the window contents as a string; whether blanks in the window are
- included is affected by the :attr:`stripspaces` member.
-
-
-.. method:: Textbox.do_command(ch)
-
- Process a single command keystroke. Here are the supported special keystrokes:
-
- +------------------+-------------------------------------------+
- | Keystroke | Action |
- +==================+===========================================+
- | :kbd:`Control-A` | Go to left edge of window. |
- +------------------+-------------------------------------------+
- | :kbd:`Control-B` | Cursor left, wrapping to previous line if |
- | | appropriate. |
- +------------------+-------------------------------------------+
- | :kbd:`Control-D` | Delete character under cursor. |
- +------------------+-------------------------------------------+
- | :kbd:`Control-E` | Go to right edge (stripspaces off) or end |
- | | of line (stripspaces on). |
- +------------------+-------------------------------------------+
- | :kbd:`Control-F` | Cursor right, wrapping to next line when |
- | | appropriate. |
- +------------------+-------------------------------------------+
- | :kbd:`Control-G` | Terminate, returning the window contents. |
- +------------------+-------------------------------------------+
- | :kbd:`Control-H` | Delete character backward. |
- +------------------+-------------------------------------------+
- | :kbd:`Control-J` | Terminate if the window is 1 line, |
- | | otherwise insert newline. |
- +------------------+-------------------------------------------+
- | :kbd:`Control-K` | If line is blank, delete it, otherwise |
- | | clear to end of line. |
- +------------------+-------------------------------------------+
- | :kbd:`Control-L` | Refresh screen. |
- +------------------+-------------------------------------------+
- | :kbd:`Control-N` | Cursor down; move down one line. |
- +------------------+-------------------------------------------+
- | :kbd:`Control-O` | Insert a blank line at cursor location. |
- +------------------+-------------------------------------------+
- | :kbd:`Control-P` | Cursor up; move up one line. |
- +------------------+-------------------------------------------+
-
- Move operations do nothing if the cursor is at an edge where the movement is not
- possible. The following synonyms are supported where possible:
-
- +------------------------+------------------+
- | Constant | Keystroke |
- +========================+==================+
- | :const:`KEY_LEFT` | :kbd:`Control-B` |
- +------------------------+------------------+
- | :const:`KEY_RIGHT` | :kbd:`Control-F` |
- +------------------------+------------------+
- | :const:`KEY_UP` | :kbd:`Control-P` |
- +------------------------+------------------+
- | :const:`KEY_DOWN` | :kbd:`Control-N` |
- +------------------------+------------------+
- | :const:`KEY_BACKSPACE` | :kbd:`Control-h` |
- +------------------------+------------------+
-
- All other keystrokes are treated as a command to insert the given character and
- move right (with line wrapping).
-
-
-.. method:: Textbox.gather()
-
- This method returns the window contents as a string; whether blanks in the
- window are included is affected by the :attr:`stripspaces` member.
-
-
-.. attribute:: Textbox.stripspaces
-
- This data member is a flag which controls the interpretation of blanks in the
- window. When it is on, trailing blanks on each line are ignored; any cursor
- motion that would land the cursor on a trailing blank goes to the end of that
- line instead, and trailing blanks are stripped when the window contents are
- gathered.
+ This is the entry point you will normally use. It accepts editing
+ keystrokes until one of the termination keystrokes is entered. If
+ *validator* is supplied, it must be a function. It will be called for
+ each keystroke entered with the keystroke as a parameter; command dispatch
+ is done on the result. This method returns the window contents as a
+ string; whether blanks in the window are included is affected by the
+ :attr:`stripspaces` member.
+
+
+ .. method:: do_command(ch)
+
+ Process a single command keystroke. Here are the supported special
+ keystrokes:
+
+ +------------------+-------------------------------------------+
+ | Keystroke | Action |
+ +==================+===========================================+
+ | :kbd:`Control-A` | Go to left edge of window. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-B` | Cursor left, wrapping to previous line if |
+ | | appropriate. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-D` | Delete character under cursor. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-E` | Go to right edge (stripspaces off) or end |
+ | | of line (stripspaces on). |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-F` | Cursor right, wrapping to next line when |
+ | | appropriate. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-G` | Terminate, returning the window contents. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-H` | Delete character backward. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-J` | Terminate if the window is 1 line, |
+ | | otherwise insert newline. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-K` | If line is blank, delete it, otherwise |
+ | | clear to end of line. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-L` | Refresh screen. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-N` | Cursor down; move down one line. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-O` | Insert a blank line at cursor location. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-P` | Cursor up; move up one line. |
+ +------------------+-------------------------------------------+
+
+ Move operations do nothing if the cursor is at an edge where the movement
+ is not possible. The following synonyms are supported where possible:
+
+ +------------------------+------------------+
+ | Constant | Keystroke |
+ +========================+==================+
+ | :const:`KEY_LEFT` | :kbd:`Control-B` |
+ +------------------------+------------------+
+ | :const:`KEY_RIGHT` | :kbd:`Control-F` |
+ +------------------------+------------------+
+ | :const:`KEY_UP` | :kbd:`Control-P` |
+ +------------------------+------------------+
+ | :const:`KEY_DOWN` | :kbd:`Control-N` |
+ +------------------------+------------------+
+ | :const:`KEY_BACKSPACE` | :kbd:`Control-h` |
+ +------------------------+------------------+
+
+ All other keystrokes are treated as a command to insert the given
+ character and move right (with line wrapping).
+
+
+ .. method:: gather()
+
+ This method returns the window contents as a string; whether blanks in the
+ window are included is affected by the :attr:`stripspaces` member.
+
+
+ .. attribute:: stripspaces
+
+ This data member is a flag which controls the interpretation of blanks in
+ the window. When it is on, trailing blanks on each line are ignored; any
+ cursor motion that would land the cursor on a trailing blank goes to the
+ end of that line instead, and trailing blanks are stripped when the window
+ contents are gathered.
:mod:`curses.wrapper` --- Terminal handler for curses programs
Modified: python/branches/py3k/Doc/library/decimal.rst
==============================================================================
--- python/branches/py3k/Doc/library/decimal.rst (original)
+++ python/branches/py3k/Doc/library/decimal.rst Fri Apr 25 03:59:09 2008
@@ -340,442 +340,394 @@
Once constructed, :class:`Decimal` objects are immutable.
+ Decimal floating point objects share many properties with the other built-in
+ numeric types such as :class:`float` and :class:`int`. All of the usual math
+ operations and special methods apply. Likewise, decimal objects can be
+ copied, pickled, printed, used as dictionary keys, used as set elements,
+ compared, sorted, and coerced to another type (such as :class:`float` or
+ :class:`long`).
-Decimal floating point objects share many properties with the other built-in
-numeric types such as :class:`float` and :class:`int`. All of the usual math
-operations and special methods apply. Likewise, decimal objects can be copied,
-pickled, printed, used as dictionary keys, used as set elements, compared,
-sorted, and converted to another type (such as :class:`float` or :class:`int`).
+ In addition to the standard numeric properties, decimal floating point
+ objects also have a number of specialized methods:
-In addition to the standard numeric properties, decimal floating point objects
-also have a number of specialized methods:
+ .. method:: adjusted()
-.. method:: Decimal.adjusted()
+ Return the adjusted exponent after shifting out the coefficient's
+ rightmost digits until only the lead digit remains:
+ ``Decimal('321e+5').adjusted()`` returns seven. Used for determining the
+ position of the most significant digit with respect to the decimal point.
- Return the adjusted exponent after shifting out the coefficient's rightmost
- digits until only the lead digit remains: ``Decimal('321e+5').adjusted()``
- returns seven. Used for determining the position of the most significant digit
- with respect to the decimal point.
+ .. method:: as_tuple()
-.. method:: Decimal.as_tuple()
+ Return a :term:`named tuple` representation of the number:
+ ``DecimalTuple(sign, digits, exponent)``.
- Return a :term:`named tuple` representation of the number:
- ``DecimalTuple(sign, digits, exponent)``.
+ .. method:: canonical()
-.. method:: Decimal.canonical()
+ Return the canonical encoding of the argument. Currently, the encoding of
+ a :class:`Decimal` instance is always canonical, so this operation returns
+ its argument unchanged.
- Return the canonical encoding of the argument. Currently, the
- encoding of a :class:`Decimal` instance is always canonical, so
- this operation returns its argument unchanged.
+ .. method:: compare(other[, context])
+ Compare the values of two Decimal instances. This operation behaves in
+ the same way as the usual comparison method :meth:`__cmp__`, except that
+ :meth:`compare` returns a Decimal instance rather than an integer, and if
+ either operand is a NaN then the result is a NaN::
-.. method:: Decimal.compare(other[, context])
+ a or b is a NaN ==> Decimal('NaN')
+ a < b ==> Decimal('-1')
+ a == b ==> Decimal('0')
+ a > b ==> Decimal('1')
- Compare the values of two Decimal instances. This operation
- behaves in the same way as the usual comparison method
- :meth:`__cmp__`, except that :meth:`compare` returns a Decimal
- instance rather than an integer, and if either operand is a NaN
- then the result is a NaN::
+ .. method:: compare_signal(other[, context])
- a or b is a NaN ==> Decimal('NaN')
- a < b ==> Decimal('-1')
- a == b ==> Decimal('0')
- a > b ==> Decimal('1')
+ This operation is identical to the :meth:`compare` method, except that all
+ NaNs signal. That is, if neither operand is a signaling NaN then any
+ quiet NaN operand is treated as though it were a signaling NaN.
-.. method:: Decimal.compare_signal(other[, context])
+ .. method:: compare_total(other)
- This operation is identical to the :meth:`compare` method, except
- that all NaNs signal. That is, if neither operand is a signaling
- NaN then any quiet NaN operand is treated as though it were a
- signaling NaN.
+ Compare two operands using their abstract representation rather than their
+ numerical value. Similar to the :meth:`compare` method, but the result
+ gives a total ordering on :class:`Decimal` instances. Two
+ :class:`Decimal` instances with the same numeric value but different
+ representations compare unequal in this ordering:
+ >>> Decimal('12.0').compare_total(Decimal('12'))
+ Decimal('-1')
-.. method:: Decimal.compare_total(other)
+ Quiet and signaling NaNs are also included in the total ordering. The
+ result of this function is ``Decimal('0')`` if both operands have the same
+ representation, ``Decimal('-1')`` if the first operand is lower in the
+ total order than the second, and ``Decimal('1')`` if the first operand is
+ higher in the total order than the second operand. See the specification
+ for details of the total order.
- Compare two operands using their abstract representation rather
- than their numerical value. Similar to the :meth:`compare` method,
- but the result gives a total ordering on :class:`Decimal`
- instances. Two :class:`Decimal` instances with the same numeric
- value but different representations compare unequal in this
- ordering:
-
- >>> Decimal('12.0').compare_total(Decimal('12'))
- Decimal('-1')
+ .. method:: compare_total_mag(other)
- Quiet and signaling NaNs are also included in the total ordering.
- The result of this function is ``Decimal('0')`` if both operands
- have the same representation, ``Decimal('-1')`` if the first
- operand is lower in the total order than the second, and
- ``Decimal('1')`` if the first operand is higher in the total order
- than the second operand. See the specification for details of the
- total order.
+ Compare two operands using their abstract representation rather than their
+ value as in :meth:`compare_total`, but ignoring the sign of each operand.
+ ``x.compare_total_mag(y)`` is equivalent to
+ ``x.copy_abs().compare_total(y.copy_abs())``.
+ .. method:: copy_abs()
-.. method:: Decimal.compare_total_mag(other)
+ Return the absolute value of the argument. This operation is unaffected
+ by the context and is quiet: no flags are changed and no rounding is
+ performed.
- Compare two operands using their abstract representation rather
- than their value as in :meth:`compare_total`, but ignoring the sign
- of each operand. ``x.compare_total_mag(y)`` is equivalent to
- ``x.copy_abs().compare_total(y.copy_abs())``.
+ .. method:: copy_negate()
+ Return the negation of the argument. This operation is unaffected by the
+ context and is quiet: no flags are changed and no rounding is performed.
-.. method:: Decimal.copy_abs()
+ .. method:: copy_sign(other)
- Return the absolute value of the argument. This operation is
- unaffected by the context and is quiet: no flags are changed and no
- rounding is performed.
+ Return a copy of the first operand with the sign set to be the same as the
+ sign of the second operand. For example:
+ >>> Decimal('2.3').copy_sign(Decimal('-1.5'))
+ Decimal('-2.3')
-.. method:: Decimal.copy_negate()
+ This operation is unaffected by the context and is quiet: no flags are
+ changed and no rounding is performed.
- Return the negation of the argument. This operation is unaffected
- by the context and is quiet: no flags are changed and no rounding
- is performed.
+ .. method:: exp([context])
+ Return the value of the (natural) exponential function ``e**x`` at the
+ given number. The result is correctly rounded using the
+ :const:`ROUND_HALF_EVEN` rounding mode.
-.. method:: Decimal.copy_sign(other)
+ >>> Decimal(1).exp()
+ Decimal('2.718281828459045235360287471')
+ >>> Decimal(321).exp()
+ Decimal('2.561702493119680037517373933E+139')
- Return a copy of the first operand with the sign set to be the
- same as the sign of the second operand. For example:
+ .. method:: fma(other, third[, context])
- >>> Decimal('2.3').copy_sign(Decimal('-1.5'))
- Decimal('-2.3')
-
- This operation is unaffected by the context and is quiet: no flags
- are changed and no rounding is performed.
+ Fused multiply-add. Return self*other+third with no rounding of the
+ intermediate product self*other.
+ >>> Decimal(2).fma(3, 5)
+ Decimal('11')
-.. method:: Decimal.exp([context])
+ .. method:: is_canonical()
- Return the value of the (natural) exponential function ``e**x`` at the
- given number. The result is correctly rounded using the
- :const:`ROUND_HALF_EVEN` rounding mode.
+ Return :const:`True` if the argument is canonical and :const:`False`
+ otherwise. Currently, a :class:`Decimal` instance is always canonical, so
+ this operation always returns :const:`True`.
- >>> Decimal(1).exp()
- Decimal('2.718281828459045235360287471')
- >>> Decimal(321).exp()
- Decimal('2.561702493119680037517373933E+139')
+ .. method:: is_finite()
+ Return :const:`True` if the argument is a finite number, and
+ :const:`False` if the argument is an infinity or a NaN.
-.. method:: Decimal.fma(other, third[, context])
+ .. method:: is_infinite()
- Fused multiply-add. Return self*other+third with no rounding of
- the intermediate product self*other.
+ Return :const:`True` if the argument is either positive or negative
+ infinity and :const:`False` otherwise.
- >>> Decimal(2).fma(3, 5)
- Decimal('11')
+ .. method:: is_nan()
+ Return :const:`True` if the argument is a (quiet or signaling) NaN and
+ :const:`False` otherwise.
-.. method:: Decimal.is_canonical()
+ .. method:: is_normal()
- Return :const:`True` if the argument is canonical and
- :const:`False` otherwise. Currently, a :class:`Decimal` instance
- is always canonical, so this operation always returns
- :const:`True`.
+ Return :const:`True` if the argument is a *normal* finite number. Return
+ :const:`False` if the argument is zero, subnormal, infinite or a NaN.
+ .. method:: is_qnan()
-.. method:: is_finite()
+ Return :const:`True` if the argument is a quiet NaN, and
+ :const:`False` otherwise.
- Return :const:`True` if the argument is a finite number, and
- :const:`False` if the argument is an infinity or a NaN.
+ .. method:: is_signed()
+ Return :const:`True` if the argument has a negative sign and
+ :const:`False` otherwise. Note that zeros and NaNs can both carry signs.
-.. method:: is_infinite()
+ .. method:: is_snan()
- Return :const:`True` if the argument is either positive or
- negative infinity and :const:`False` otherwise.
+ Return :const:`True` if the argument is a signaling NaN and :const:`False`
+ otherwise.
+ .. method:: is_subnormal()
-.. method:: is_nan()
+ Return :const:`True` if the argument is subnormal, and :const:`False`
+ otherwise.
- Return :const:`True` if the argument is a (quiet or signaling)
- NaN and :const:`False` otherwise.
+ .. method:: is_zero()
+ Return :const:`True` if the argument is a (positive or negative) zero and
+ :const:`False` otherwise.
-.. method:: is_normal()
+ .. method:: ln([context])
- Return :const:`True` if the argument is a *normal* finite number.
- Return :const:`False` if the argument is zero, subnormal, infinite
- or a NaN.
+ Return the natural (base e) logarithm of the operand. The result is
+ correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode.
+ .. method:: log10([context])
-.. method:: is_qnan()
+ Return the base ten logarithm of the operand. The result is correctly
+ rounded using the :const:`ROUND_HALF_EVEN` rounding mode.
- Return :const:`True` if the argument is a quiet NaN, and
- :const:`False` otherwise.
+ .. method:: logb([context])
+ For a nonzero number, return the adjusted exponent of its operand as a
+ :class:`Decimal` instance. If the operand is a zero then
+ ``Decimal('-Infinity')`` is returned and the :const:`DivisionByZero` flag
+ is raised. If the operand is an infinity then ``Decimal('Infinity')`` is
+ returned.
-.. method:: is_signed()
+ .. method:: logical_and(other[, context])
- Return :const:`True` if the argument has a negative sign and
- :const:`False` otherwise. Note that zeros and NaNs can both carry
- signs.
+ :meth:`logical_and` is a logical operation which takes two *logical
+ operands* (see :ref:`logical_operands_label`). The result is the
+ digit-wise ``and`` of the two operands.
+ .. method:: logical_invert(other[, context])
-.. method:: is_snan()
+ :meth:`logical_invert` is a logical operation. The argument must
+ be a *logical operand* (see :ref:`logical_operands_label`). The
+ result is the digit-wise inversion of the operand.
- Return :const:`True` if the argument is a signaling NaN and
- :const:`False` otherwise.
+ .. method:: logical_or(other[, context])
+ :meth:`logical_or` is a logical operation which takes two *logical
+ operands* (see :ref:`logical_operands_label`). The result is the
+ digit-wise ``or`` of the two operands.
-.. method:: is_subnormal()
+ .. method:: logical_xor(other[, context])
- Return :const:`True` if the argument is subnormal, and
- :const:`False` otherwise.
+ :meth:`logical_xor` is a logical operation which takes two *logical
+ operands* (see :ref:`logical_operands_label`). The result is the
+ digit-wise exclusive or of the two operands.
+ .. method:: max(other[, context])
-.. method:: is_zero()
+ Like ``max(self, other)`` except that the context rounding rule is applied
+ before returning and that :const:`NaN` values are either signaled or
+ ignored (depending on the context and whether they are signaling or
+ quiet).
- Return :const:`True` if the argument is a (positive or negative)
- zero and :const:`False` otherwise.
+ .. method:: max_mag(other[, context])
+ Similar to the :meth:`max` method, but the comparison is done using the
+ absolute values of the operands.
-.. method:: Decimal.ln([context])
+ .. method:: min(other[, context])
- Return the natural (base e) logarithm of the operand. The result
- is correctly rounded using the :const:`ROUND_HALF_EVEN` rounding
- mode.
+ Like ``min(self, other)`` except that the context rounding rule is applied
+ before returning and that :const:`NaN` values are either signaled or
+ ignored (depending on the context and whether they are signaling or
+ quiet).
+ .. method:: min_mag(other[, context])
-.. method:: Decimal.log10([context])
+ Similar to the :meth:`min` method, but the comparison is done using the
+ absolute values of the operands.
- Return the base ten logarithm of the operand. The result is
- correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode.
+ .. method:: next_minus([context])
+ Return the largest number representable in the given context (or in the
+ current thread's context if no context is given) that is smaller than the
+ given operand.
-.. method:: Decimal.logb([context])
+ .. method:: next_plus([context])
- For a nonzero number, return the adjusted exponent of its operand
- as a :class:`Decimal` instance. If the operand is a zero then
- ``Decimal('-Infinity')`` is returned and the
- :const:`DivisionByZero` flag is raised. If the operand is an
- infinity then ``Decimal('Infinity')`` is returned.
+ Return the smallest number representable in the given context (or in the
+ current thread's context if no context is given) that is larger than the
+ given operand.
+ .. method:: next_toward(other[, context])
-.. method:: Decimal.logical_and(other[, context])
+ If the two operands are unequal, return the number closest to the first
+ operand in the direction of the second operand. If both operands are
+ numerically equal, return a copy of the first operand with the sign set to
+ be the same as the sign of the second operand.
- :meth:`logical_and` is a logical operation which takes two
- *logical operands* (see :ref:`logical_operands_label`). The result
- is the digit-wise ``and`` of the two operands.
+ .. method:: normalize([context])
+ Normalize the number by stripping the rightmost trailing zeros and
+ converting any result equal to :const:`Decimal('0')` to
+ :const:`Decimal('0e0')`. Used for producing canonical values for members
+ of an equivalence class. For example, ``Decimal('32.100')`` and
+ ``Decimal('0.321000e+2')`` both normalize to the equivalent value
+ ``Decimal('32.1')``.
-.. method:: Decimal.logical_invert(other[, context])
+ .. method:: number_class([context])
- :meth:`logical_invert` is a logical operation. The argument must
- be a *logical operand* (see :ref:`logical_operands_label`). The
- result is the digit-wise inversion of the operand.
+ Return a string describing the *class* of the operand. The returned value
+ is one of the following ten strings.
+ * ``"-Infinity"``, indicating that the operand is negative infinity.
+ * ``"-Normal"``, indicating that the operand is a negative normal number.
+ * ``"-Subnormal"``, indicating that the operand is negative and subnormal.
+ * ``"-Zero"``, indicating that the operand is a negative zero.
+ * ``"+Zero"``, indicating that the operand is a positive zero.
+ * ``"+Subnormal"``, indicating that the operand is positive and subnormal.
+ * ``"+Normal"``, indicating that the operand is a positive normal number.
+ * ``"+Infinity"``, indicating that the operand is positive infinity.
+ * ``"NaN"``, indicating that the operand is a quiet NaN (Not a Number).
+ * ``"sNaN"``, indicating that the operand is a signaling NaN.
-.. method:: Decimal.logical_or(other[, context])
+ .. method:: quantize(exp[, rounding[, context[, watchexp]]])
- :meth:`logical_or` is a logical operation which takes two *logical
- operands* (see :ref:`logical_operands_label`). The result is the
- digit-wise ``or`` of the two operands.
+ Return a value equal to the first operand after rounding and having the
+ exponent of the second operand.
+ >>> Decimal('1.41421356').quantize(Decimal('1.000'))
+ Decimal('1.414')
-.. method:: Decimal.logical_xor(other[, context])
+ Unlike other operations, if the length of the coefficient after the
+ quantize operation would be greater than precision, then an
+ :const:`InvalidOperation` is signaled. This guarantees that, unless there
+ is an error condition, the quantized exponent is always equal to that of
+ the right-hand operand.
- :meth:`logical_xor` is a logical operation which takes two
- *logical operands* (see :ref:`logical_operands_label`). The result
- is the digit-wise exclusive or of the two operands.
+ Also unlike other operations, quantize never signals Underflow, even if
+ the result is subnormal and inexact.
+ If the exponent of the second operand is larger than that of the first
+ then rounding may be necessary. In this case, the rounding mode is
+ determined by the ``rounding`` argument if given, else by the given
+ ``context`` argument; if neither argument is given the rounding mode of
+ the current thread's context is used.
-.. method:: Decimal.max(other[, context])
+ If *watchexp* is set (default), then an error is returned whenever the
+ resulting exponent is greater than :attr:`Emax` or less than
+ :attr:`Etiny`.
- Like ``max(self, other)`` except that the context rounding rule is applied
- before returning and that :const:`NaN` values are either signaled or ignored
- (depending on the context and whether they are signaling or quiet).
+ .. method:: radix()
+ Return ``Decimal(10)``, the radix (base) in which the :class:`Decimal`
+ class does all its arithmetic. Included for compatibility with the
+ specification.
-.. method:: Decimal.max_mag(other[, context])
+ .. method:: remainder_near(other[, context])
- Similar to the :meth:`max` method, but the comparison is done using
- the absolute values of the operands.
+ Compute the modulo as either a positive or negative value depending on
+ which is closest to zero. For instance, ``Decimal(10).remainder_near(6)``
+ returns ``Decimal('-2')`` which is closer to zero than ``Decimal('4')``.
+ If both are equally close, the one chosen will have the same sign as
+ *self*.
-.. method:: Decimal.min(other[, context])
+ .. method:: rotate(other[, context])
- Like ``min(self, other)`` except that the context rounding rule is applied
- before returning and that :const:`NaN` values are either signaled or ignored
- (depending on the context and whether they are signaling or quiet).
+ Return the result of rotating the digits of the first operand by an amount
+ specified by the second operand. The second operand must be an integer in
+ the range -precision through precision. The absolute value of the second
+ operand gives the number of places to rotate. If the second operand is
+ positive then rotation is to the left; otherwise rotation is to the right.
+ The coefficient of the first operand is padded on the left with zeros to
+ length precision if necessary. The sign and exponent of the first operand
+ are unchanged.
-.. method:: Decimal.min_mag(other[, context])
+ .. method:: same_quantum(other[, context])
- Similar to the :meth:`min` method, but the comparison is done using
- the absolute values of the operands.
+ Test whether self and other have the same exponent or whether both are
+ :const:`NaN`.
+ .. method:: scaleb(other[, context])
-.. method:: Decimal.next_minus([context])
+ Return the first operand with exponent adjusted by the second.
+ Equivalently, return the first operand multiplied by ``10**other``. The
+ second operand must be an integer.
- Return the largest number representable in the given context (or
- in the current thread's context if no context is given) that is smaller
- than the given operand.
+ .. method:: shift(other[, context])
+ Return the result of shifting the digits of the first operand by an amount
+ specified by the second operand. The second operand must be an integer in
+ the range -precision through precision. The absolute value of the second
+ operand gives the number of places to shift. If the second operand is
+ positive then the shift is to the left; otherwise the shift is to the
+ right. Digits shifted into the coefficient are zeros. The sign and
+ exponent of the first operand are unchanged.
-.. method:: Decimal.next_plus([context])
+ .. method:: sqrt([context])
- Return the smallest number representable in the given context (or
- in the current thread's context if no context is given) that is
- larger than the given operand.
+ Return the square root of the argument to full precision.
-.. method:: Decimal.next_toward(other[, context])
+ .. method:: to_eng_string([context])
- If the two operands are unequal, return the number closest to the
- first operand in the direction of the second operand. If both
- operands are numerically equal, return a copy of the first operand
- with the sign set to be the same as the sign of the second operand.
+ Convert to an engineering-type string.
+ Engineering notation has an exponent which is a multiple of 3, so there
+ are up to 3 digits left of the decimal place. For example, converts
+ ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``
-.. method:: Decimal.normalize([context])
+ .. method:: to_integral([rounding[, context]])
- Normalize the number by stripping the rightmost trailing zeros and converting
- any result equal to :const:`Decimal('0')` to :const:`Decimal('0e0')`. Used for
- producing canonical values for members of an equivalence class. For example,
- ``Decimal('32.100')`` and ``Decimal('0.321000e+2')`` both normalize to the
- equivalent value ``Decimal('32.1')``.
+ Identical to the :meth:`to_integral_value` method. The ``to_integral``
+ name has been kept for compatibility with older versions.
+ .. method:: to_integral_exact([rounding[, context]])
-.. method:: Decimal.number_class([context])
+ Round to the nearest integer, signaling :const:`Inexact` or
+ :const:`Rounded` as appropriate if rounding occurs. The rounding mode is
+ determined by the ``rounding`` parameter if given, else by the given
+ ``context``. If neither parameter is given then the rounding mode of the
+ current context is used.
- Return a string describing the *class* of the operand. The
- returned value is one of the following ten strings.
+ .. method:: to_integral_value([rounding[, context]])
- * ``"-Infinity"``, indicating that the operand is negative infinity.
- * ``"-Normal"``, indicating that the operand is a negative normal number.
- * ``"-Subnormal"``, indicating that the operand is negative and subnormal.
- * ``"-Zero"``, indicating that the operand is a negative zero.
- * ``"+Zero"``, indicating that the operand is a positive zero.
- * ``"+Subnormal"``, indicating that the operand is positive and subnormal.
- * ``"+Normal"``, indicating that the operand is a positive normal number.
- * ``"+Infinity"``, indicating that the operand is positive infinity.
- * ``"NaN"``, indicating that the operand is a quiet NaN (Not a Number).
- * ``"sNaN"``, indicating that the operand is a signaling NaN.
+ Round to the nearest integer without signaling :const:`Inexact` or
+ :const:`Rounded`. If given, applies *rounding*; otherwise, uses the
+ rounding method in either the supplied *context* or the current context.
+ .. method:: trim()
-.. method:: Decimal.quantize(exp[, rounding[, context[, watchexp]]])
-
- Return a value equal to the first operand after rounding and
- having the exponent of the second operand.
-
- >>> Decimal('1.41421356').quantize(Decimal('1.000'))
- Decimal('1.414')
-
- Unlike other operations, if the length of the coefficient after the
- quantize operation would be greater than precision, then an
- :const:`InvalidOperation` is signaled. This guarantees that, unless
- there is an error condition, the quantized exponent is always equal
- to that of the right-hand operand.
-
- Also unlike other operations, quantize never signals Underflow,
- even if the result is subnormal and inexact.
-
- If the exponent of the second operand is larger than that of the
- first then rounding may be necessary. In this case, the rounding
- mode is determined by the ``rounding`` argument if given, else by
- the given ``context`` argument; if neither argument is given the
- rounding mode of the current thread's context is used.
-
- If *watchexp* is set (default), then an error is returned whenever the
- resulting exponent is greater than :attr:`Emax` or less than :attr:`Etiny`.
-
-.. method:: Decimal.radix()
-
- Return ``Decimal(10)``, the radix (base) in which the
- :class:`Decimal` class does all its arithmetic. Included for
- compatibility with the specification.
-
-
-.. method:: Decimal.remainder_near(other[, context])
-
- Compute the modulo as either a positive or negative value depending on which is
- closest to zero. For instance, ``Decimal(10).remainder_near(6)`` returns
- ``Decimal('-2')`` which is closer to zero than ``Decimal('4')``.
-
- If both are equally close, the one chosen will have the same sign as *self*.
-
-.. method:: Decimal.rotate(other[, context])
-
- Return the result of rotating the digits of the first operand by
- an amount specified by the second operand. The second operand
- must be an integer in the range -precision through precision. The
- absolute value of the second operand gives the number of places to
- rotate. If the second operand is positive then rotation is to the
- left; otherwise rotation is to the right. The coefficient of the
- first operand is padded on the left with zeros to length precision
- if necessary. The sign and exponent of the first operand are
- unchanged.
-
-
-.. method:: Decimal.same_quantum(other[, context])
-
- Test whether self and other have the same exponent or whether both are
- :const:`NaN`.
-
-.. method:: Decimal.scaleb(other[, context])
-
- Return the first operand with exponent adjusted by the second.
- Equivalently, return the first operand multiplied by ``10**other``.
- The second operand must be an integer.
-
-
-.. method:: Decimal.shift(other[, context])
-
- Return the result of shifting the digits of the first operand by
- an amount specified by the second operand. The second operand must
- be an integer in the range -precision through precision. The
- absolute value of the second operand gives the number of places to
- shift. If the second operand is positive then the shift is to the
- left; otherwise the shift is to the right. Digits shifted into the
- coefficient are zeros. The sign and exponent of the first operand
- are unchanged.
-
-
-.. method:: Decimal.sqrt([context])
-
- Return the square root of the argument to full precision.
-
-
-.. method:: Decimal.to_eng_string([context])
-
- Convert to an engineering-type string.
-
- Engineering notation has an exponent which is a multiple of 3, so there are up
- to 3 digits left of the decimal place. For example, converts
- ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``
-
-.. method:: Decimal.to_integral([rounding[, context]])
-
- Identical to the :meth:`to_integral_value` method. The ``to_integral``
- name has been kept for compatibility with older versions.
-
-.. method:: Decimal.to_integral_exact([rounding[, context]])
-
- Round to the nearest integer, signaling
- :const:`Inexact` or :const:`Rounded` as appropriate if rounding
- occurs. The rounding mode is determined by the ``rounding``
- parameter if given, else by the given ``context``. If neither
- parameter is given then the rounding mode of the current context is
- used.
-
-
-.. method:: Decimal.to_integral_value([rounding[, context]])
-
- Round to the nearest integer without signaling :const:`Inexact` or
- :const:`Rounded`. If given, applies *rounding*; otherwise, uses the rounding
- method in either the supplied *context* or the current context.
-
-
-.. method:: Decimal.trim()
-
- Return the decimal with *insignificant* trailing zeros removed.
- Here, a trailing zero is considered insignificant either if it
- follows the decimal point, or if the exponent of the argument (that
- is, the last element of the :meth:`as_tuple` representation) is
- positive.
+ Return the decimal with *insignificant* trailing zeros removed. Here, a
+ trailing zero is considered insignificant either if it follows the decimal
+ point, or if the exponent of the argument (that is, the last element of
+ the :meth:`as_tuple` representation) is positive.
.. _logical_operands_label:
@@ -916,150 +868,147 @@
lowercase :const:`e` is used: :const:`Decimal('6.02e+23')`.
-The :class:`Context` class defines several general purpose methods as
-well as a large number of methods for doing arithmetic directly in a
-given context. In addition, for each of the :class:`Decimal` methods
-described above (with the exception of the :meth:`adjusted` and
-:meth:`as_tuple` methods) there is a corresponding :class:`Context`
-method. For example, ``C.exp(x)`` is equivalent to
-``x.exp(context=C)``.
-
-.. method:: Context.clear_flags()
+ The :class:`Context` class defines several general purpose methods as well as
+ a large number of methods for doing arithmetic directly in a given context.
+ In addition, for each of the :class:`Decimal` methods described above (with
+ the exception of the :meth:`adjusted` and :meth:`as_tuple` methods) there is
+ a corresponding :class:`Context` method. For example, ``C.exp(x)`` is
+ equivalent to ``x.exp(context=C)``.
- Resets all of the flags to :const:`0`.
+ .. method:: clear_flags()
-.. method:: Context.copy()
+ Resets all of the flags to :const:`0`.
- Return a duplicate of the context.
+ .. method:: copy()
-.. method:: Context.copy_decimal(num)
+ Return a duplicate of the context.
- Return a copy of the Decimal instance num.
+ .. method:: copy_decimal(num)
-.. method:: Context.create_decimal(num)
+ Return a copy of the Decimal instance num.
- Creates a new Decimal instance from *num* but using *self* as context. Unlike
- the :class:`Decimal` constructor, the context precision, rounding method, flags,
- and traps are applied to the conversion.
+ .. method:: create_decimal(num)
- This is useful because constants are often given to a greater precision than is
- needed by the application. Another benefit is that rounding immediately
- eliminates unintended effects from digits beyond the current precision. In the
- following example, using unrounded inputs means that adding zero to a sum can
- change the result:
+ Creates a new Decimal instance from *num* but using *self* as
+ context. Unlike the :class:`Decimal` constructor, the context precision,
+ rounding method, flags, and traps are applied to the conversion.
- .. doctest:: newcontext
+ This is useful because constants are often given to a greater precision
+ than is needed by the application. Another benefit is that rounding
+ immediately eliminates unintended effects from digits beyond the current
+ precision. In the following example, using unrounded inputs means that
+ adding zero to a sum can change the result:
- >>> getcontext().prec = 3
- >>> Decimal('3.4445') + Decimal('1.0023')
- Decimal('4.45')
- >>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')
- Decimal('4.44')
+ .. doctest:: newcontext
- This method implements the to-number operation of the IBM
- specification. If the argument is a string, no leading or trailing
- whitespace is permitted.
+ >>> getcontext().prec = 3
+ >>> Decimal('3.4445') + Decimal('1.0023')
+ Decimal('4.45')
+ >>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')
+ Decimal('4.44')
-.. method:: Context.Etiny()
+ This method implements the to-number operation of the IBM specification.
+ If the argument is a string, no leading or trailing whitespace is
+ permitted.
- Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent value
- for subnormal results. When underflow occurs, the exponent is set to
- :const:`Etiny`.
+ .. method:: Etiny()
+ Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent
+ value for subnormal results. When underflow occurs, the exponent is set
+ to :const:`Etiny`.
-.. method:: Context.Etop()
- Returns a value equal to ``Emax - prec + 1``.
+ .. method:: Etop()
-The usual approach to working with decimals is to create :class:`Decimal`
-instances and then apply arithmetic operations which take place within the
-current context for the active thread. An alternative approach is to use context
-methods for calculating within a specific context. The methods are similar to
-those for the :class:`Decimal` class and are only briefly recounted here.
+ Returns a value equal to ``Emax - prec + 1``.
+ The usual approach to working with decimals is to create :class:`Decimal`
+ instances and then apply arithmetic operations which take place within the
+ current context for the active thread. An alternative approach is to use
+ context methods for calculating within a specific context. The methods are
+ similar to those for the :class:`Decimal` class and are only briefly
+ recounted here.
-.. method:: Context.abs(x)
- Returns the absolute value of *x*.
+ .. method:: abs(x)
+ Returns the absolute value of *x*.
-.. method:: Context.add(x, y)
- Return the sum of *x* and *y*.
+ .. method:: add(x, y)
+ Return the sum of *x* and *y*.
-.. method:: Context.divide(x, y)
- Return *x* divided by *y*.
+ .. method:: divide(x, y)
+ Return *x* divided by *y*.
-.. method:: Context.divide_int(x, y)
- Return *x* divided by *y*, truncated to an integer.
+ .. method:: divide_int(x, y)
+ Return *x* divided by *y*, truncated to an integer.
-.. method:: Context.divmod(x, y)
- Divides two numbers and returns the integer part of the result.
+ .. method:: divmod(x, y)
+ Divides two numbers and returns the integer part of the result.
-.. method:: Context.minus(x)
- Minus corresponds to the unary prefix minus operator in Python.
+ .. method:: minus(x)
+ Minus corresponds to the unary prefix minus operator in Python.
-.. method:: Context.multiply(x, y)
- Return the product of *x* and *y*.
+ .. method:: multiply(x, y)
+ Return the product of *x* and *y*.
-.. method:: Context.plus(x)
- Plus corresponds to the unary prefix plus operator in Python. This operation
- applies the context precision and rounding, so it is *not* an identity
- operation.
+ .. method:: plus(x)
+ Plus corresponds to the unary prefix plus operator in Python. This
+ operation applies the context precision and rounding, so it is *not* an
+ identity operation.
-.. method:: Context.power(x, y[, modulo])
- Return ``x`` to the power of ``y``, reduced modulo ``modulo`` if
- given.
+ .. method:: power(x, y[, modulo])
- With two arguments, compute ``x**y``. If ``x`` is negative then
- ``y`` must be integral. The result will be inexact unless ``y`` is
- integral and the result is finite and can be expressed exactly in
- 'precision' digits. The result should always be correctly rounded,
- using the rounding mode of the current thread's context.
+ Return ``x`` to the power of ``y``, reduced modulo ``modulo`` if given.
- With three arguments, compute ``(x**y) % modulo``. For the three
- argument form, the following restrictions on the arguments hold:
+ With two arguments, compute ``x**y``. If ``x`` is negative then ``y``
+ must be integral. The result will be inexact unless ``y`` is integral and
+ the result is finite and can be expressed exactly in 'precision' digits.
+ The result should always be correctly rounded, using the rounding mode of
+ the current thread's context.
- - all three arguments must be integral
- - ``y`` must be nonnegative
- - at least one of ``x`` or ``y`` must be nonzero
- - ``modulo`` must be nonzero and have at most 'precision' digits
+ With three arguments, compute ``(x**y) % modulo``. For the three argument
+ form, the following restrictions on the arguments hold:
- The result of ``Context.power(x, y, modulo)`` is identical to
- the result that would be obtained by computing ``(x**y) %
- modulo`` with unbounded precision, but is computed more
- efficiently. It is always exact.
+ - all three arguments must be integral
+ - ``y`` must be nonnegative
+ - at least one of ``x`` or ``y`` must be nonzero
+ - ``modulo`` must be nonzero and have at most 'precision' digits
+ The result of ``Context.power(x, y, modulo)`` is identical to the result
+ that would be obtained by computing ``(x**y) % modulo`` with unbounded
+ precision, but is computed more efficiently. It is always exact.
-.. method:: Context.remainder(x, y)
+ .. method:: remainder(x, y)
- Returns the remainder from integer division.
+ Returns the remainder from integer division.
- The sign of the result, if non-zero, is the same as that of the original
- dividend.
+ The sign of the result, if non-zero, is the same as that of the original
+ dividend.
-.. method:: Context.subtract(x, y)
+ .. method:: subtract(x, y)
- Return the difference between *x* and *y*.
+ Return the difference between *x* and *y*.
-.. method:: Context.to_sci_string(x)
+ .. method:: to_sci_string(x)
- Converts a number to a string using scientific notation.
+ Converts a number to a string using scientific notation.
.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -1138,28 +1087,29 @@
Numerical overflow.
- Indicates the exponent is larger than :attr:`Emax` after rounding has occurred.
- If not trapped, the result depends on the rounding mode, either pulling inward
- to the largest representable finite number or rounding outward to
- :const:`Infinity`. In either case, :class:`Inexact` and :class:`Rounded` are
- also signaled.
+ Indicates the exponent is larger than :attr:`Emax` after rounding has
+ occurred. If not trapped, the result depends on the rounding mode, either
+ pulling inward to the largest representable finite number or rounding outward
+ to :const:`Infinity`. In either case, :class:`Inexact` and :class:`Rounded`
+ are also signaled.
.. class:: Rounded
Rounding occurred though possibly no information was lost.
- Signaled whenever rounding discards digits; even if those digits are zero (such
- as rounding :const:`5.00` to :const:`5.0`). If not trapped, returns the result
- unchanged. This signal is used to detect loss of significant digits.
+ Signaled whenever rounding discards digits; even if those digits are zero
+ (such as rounding :const:`5.00` to :const:`5.0`). If not trapped, returns
+ the result unchanged. This signal is used to detect loss of significant
+ digits.
.. class:: Subnormal
Exponent was lower than :attr:`Emin` prior to rounding.
- Occurs when an operation result is subnormal (the exponent is too small). If not
- trapped, returns the result unchanged.
+ Occurs when an operation result is subnormal (the exponent is too small). If
+ not trapped, returns the result unchanged.
.. class:: Underflow
Modified: python/branches/py3k/Doc/library/difflib.rst
==============================================================================
--- python/branches/py3k/Doc/library/difflib.rst (original)
+++ python/branches/py3k/Doc/library/difflib.rst Fri Apr 25 03:59:09 2008
@@ -343,166 +343,171 @@
The optional arguments *a* and *b* are sequences to be compared; both default to
empty strings. The elements of both sequences must be :term:`hashable`.
-:class:`SequenceMatcher` objects have the following methods:
+ :class:`SequenceMatcher` objects have the following methods:
-.. method:: SequenceMatcher.set_seqs(a, b)
+ .. method:: set_seqs(a, b)
- Set the two sequences to be compared.
+ Set the two sequences to be compared.
-:class:`SequenceMatcher` computes and caches detailed information about the
-second sequence, so if you want to compare one sequence against many sequences,
-use :meth:`set_seq2` to set the commonly used sequence once and call
-:meth:`set_seq1` repeatedly, once for each of the other sequences.
+ :class:`SequenceMatcher` computes and caches detailed information about the
+ second sequence, so if you want to compare one sequence against many
+ sequences, use :meth:`set_seq2` to set the commonly used sequence once and
+ call :meth:`set_seq1` repeatedly, once for each of the other sequences.
-.. method:: SequenceMatcher.set_seq1(a)
+ .. method:: set_seq1(a)
- Set the first sequence to be compared. The second sequence to be compared is
- not changed.
+ Set the first sequence to be compared. The second sequence to be compared
+ is not changed.
-.. method:: SequenceMatcher.set_seq2(b)
+ .. method:: set_seq2(b)
- Set the second sequence to be compared. The first sequence to be compared is
- not changed.
+ Set the second sequence to be compared. The first sequence to be compared
+ is not changed.
-.. method:: SequenceMatcher.find_longest_match(alo, ahi, blo, bhi)
+ .. method:: find_longest_match(alo, ahi, blo, bhi)
- Find longest matching block in ``a[alo:ahi]`` and ``b[blo:bhi]``.
+ Find longest matching block in ``a[alo:ahi]`` and ``b[blo:bhi]``.
- If *isjunk* was omitted or ``None``, :meth:`find_longest_match` returns ``(i, j,
- k)`` such that ``a[i:i+k]`` is equal to ``b[j:j+k]``, where ``alo <= i <= i+k <=
- ahi`` and ``blo <= j <= j+k <= bhi``. For all ``(i', j', k')`` meeting those
- conditions, the additional conditions ``k >= k'``, ``i <= i'``, and if ``i ==
- i'``, ``j <= j'`` are also met. In other words, of all maximal matching blocks,
- return one that starts earliest in *a*, and of all those maximal matching blocks
- that start earliest in *a*, return the one that starts earliest in *b*.
+ If *isjunk* was omitted or ``None``, :meth:`find_longest_match` returns
+ ``(i, j, k)`` such that ``a[i:i+k]`` is equal to ``b[j:j+k]``, where ``alo
+ <= i <= i+k <= ahi`` and ``blo <= j <= j+k <= bhi``. For all ``(i', j',
+ k')`` meeting those conditions, the additional conditions ``k >= k'``, ``i
+ <= i'``, and if ``i == i'``, ``j <= j'`` are also met. In other words, of
+ all maximal matching blocks, return one that starts earliest in *a*, and
+ of all those maximal matching blocks that start earliest in *a*, return
+ the one that starts earliest in *b*.
- >>> s = SequenceMatcher(None, " abcd", "abcd abcd")
- >>> s.find_longest_match(0, 5, 0, 9)
- Match(a=0, b=4, size=5)
+ >>> s = SequenceMatcher(None, " abcd", "abcd abcd")
+ >>> s.find_longest_match(0, 5, 0, 9)
+ Match(a=0, b=4, size=5)
- If *isjunk* was provided, first the longest matching block is determined as
- above, but with the additional restriction that no junk element appears in the
- block. Then that block is extended as far as possible by matching (only) junk
- elements on both sides. So the resulting block never matches on junk except as
- identical junk happens to be adjacent to an interesting match.
+ If *isjunk* was provided, first the longest matching block is determined
+ as above, but with the additional restriction that no junk element appears
+ in the block. Then that block is extended as far as possible by matching
+ (only) junk elements on both sides. So the resulting block never matches
+ on junk except as identical junk happens to be adjacent to an interesting
+ match.
- Here's the same example as before, but considering blanks to be junk. That
- prevents ``' abcd'`` from matching the ``' abcd'`` at the tail end of the second
- sequence directly. Instead only the ``'abcd'`` can match, and matches the
- leftmost ``'abcd'`` in the second sequence:
+ Here's the same example as before, but considering blanks to be junk. That
+ prevents ``' abcd'`` from matching the ``' abcd'`` at the tail end of the
+ second sequence directly. Instead only the ``'abcd'`` can match, and
+ matches the leftmost ``'abcd'`` in the second sequence:
- >>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
- >>> s.find_longest_match(0, 5, 0, 9)
- Match(a=1, b=0, size=4)
+ >>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
+ >>> s.find_longest_match(0, 5, 0, 9)
+ Match(a=1, b=0, size=4)
- If no blocks match, this returns ``(alo, blo, 0)``.
+ If no blocks match, this returns ``(alo, blo, 0)``.
- This method returns a :term:`named tuple` ``Match(a, b, size)``.
+ This method returns a :term:`named tuple` ``Match(a, b, size)``.
-.. method:: SequenceMatcher.get_matching_blocks()
+ .. method:: get_matching_blocks()
- Return list of triples describing matching subsequences. Each triple is of the
- form ``(i, j, n)``, and means that ``a[i:i+n] == b[j:j+n]``. The triples are
- monotonically increasing in *i* and *j*.
+ Return list of triples describing matching subsequences. Each triple is of
+ the form ``(i, j, n)``, and means that ``a[i:i+n] == b[j:j+n]``. The
+ triples are monotonically increasing in *i* and *j*.
- The last triple is a dummy, and has the value ``(len(a), len(b), 0)``. It is
- the only triple with ``n == 0``. If ``(i, j, n)`` and ``(i', j', n')`` are
- adjacent triples in the list, and the second is not the last triple in the list,
- then ``i+n != i'`` or ``j+n != j'``; in other words, adjacent triples always
- describe non-adjacent equal blocks.
+ The last triple is a dummy, and has the value ``(len(a), len(b), 0)``. It
+ is the only triple with ``n == 0``. If ``(i, j, n)`` and ``(i', j', n')``
+ are adjacent triples in the list, and the second is not the last triple in
+ the list, then ``i+n != i'`` or ``j+n != j'``; in other words, adjacent
+ triples always describe non-adjacent equal blocks.
- .. XXX Explain why a dummy is used!
+ .. XXX Explain why a dummy is used!
- .. doctest::
+ .. doctest::
- >>> s = SequenceMatcher(None, "abxcd", "abcd")
- >>> s.get_matching_blocks()
- [Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)]
+ >>> s = SequenceMatcher(None, "abxcd", "abcd")
+ >>> s.get_matching_blocks()
+ [Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)]
-.. method:: SequenceMatcher.get_opcodes()
+ .. method:: get_opcodes()
- Return list of 5-tuples describing how to turn *a* into *b*. Each tuple is of
- the form ``(tag, i1, i2, j1, j2)``. The first tuple has ``i1 == j1 == 0``, and
- remaining tuples have *i1* equal to the *i2* from the preceding tuple, and,
- likewise, *j1* equal to the previous *j2*.
+ Return list of 5-tuples describing how to turn *a* into *b*. Each tuple is
+ of the form ``(tag, i1, i2, j1, j2)``. The first tuple has ``i1 == j1 ==
+ 0``, and remaining tuples have *i1* equal to the *i2* from the preceding
+ tuple, and, likewise, *j1* equal to the previous *j2*.
- The *tag* values are strings, with these meanings:
+ The *tag* values are strings, with these meanings:
- +---------------+---------------------------------------------+
- | Value | Meaning |
- +===============+=============================================+
- | ``'replace'`` | ``a[i1:i2]`` should be replaced by |
- | | ``b[j1:j2]``. |
- +---------------+---------------------------------------------+
- | ``'delete'`` | ``a[i1:i2]`` should be deleted. Note that |
- | | ``j1 == j2`` in this case. |
- +---------------+---------------------------------------------+
- | ``'insert'`` | ``b[j1:j2]`` should be inserted at |
- | | ``a[i1:i1]``. Note that ``i1 == i2`` in |
- | | this case. |
- +---------------+---------------------------------------------+
- | ``'equal'`` | ``a[i1:i2] == b[j1:j2]`` (the sub-sequences |
- | | are equal). |
- +---------------+---------------------------------------------+
+ +---------------+---------------------------------------------+
+ | Value | Meaning |
+ +===============+=============================================+
+ | ``'replace'`` | ``a[i1:i2]`` should be replaced by |
+ | | ``b[j1:j2]``. |
+ +---------------+---------------------------------------------+
+ | ``'delete'`` | ``a[i1:i2]`` should be deleted. Note that |
+ | | ``j1 == j2`` in this case. |
+ +---------------+---------------------------------------------+
+ | ``'insert'`` | ``b[j1:j2]`` should be inserted at |
+ | | ``a[i1:i1]``. Note that ``i1 == i2`` in |
+ | | this case. |
+ +---------------+---------------------------------------------+
+ | ``'equal'`` | ``a[i1:i2] == b[j1:j2]`` (the sub-sequences |
+ | | are equal). |
+ +---------------+---------------------------------------------+
- For example:
+ For example:
- >>> a = "qabxcd"
- >>> b = "abycdf"
- >>> s = SequenceMatcher(None, a, b)
- >>> for tag, i1, i2, j1, j2 in s.get_opcodes():
- ... print(("%7s a[%d:%d] (%s) b[%d:%d] (%s)" %
- ... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2])))
- delete a[0:1] (q) b[0:0] ()
- equal a[1:3] (ab) b[0:2] (ab)
- replace a[3:4] (x) b[2:3] (y)
- equal a[4:6] (cd) b[3:5] (cd)
- insert a[6:6] () b[5:6] (f)
+ >>> a = "qabxcd"
+ >>> b = "abycdf"
+ >>> s = SequenceMatcher(None, a, b)
+ >>> for tag, i1, i2, j1, j2 in s.get_opcodes():
+ ... print(("%7s a[%d:%d] (%s) b[%d:%d] (%s)" %
+ ... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2])))
+ delete a[0:1] (q) b[0:0] ()
+ equal a[1:3] (ab) b[0:2] (ab)
+ replace a[3:4] (x) b[2:3] (y)
+ equal a[4:6] (cd) b[3:5] (cd)
+ insert a[6:6] () b[5:6] (f)
-.. method:: SequenceMatcher.get_grouped_opcodes([n])
+ .. method:: get_grouped_opcodes([n])
- Return a :term:`generator` of groups with up to *n* lines of context.
+ Return a :term:`generator` of groups with up to *n* lines of context.
- Starting with the groups returned by :meth:`get_opcodes`, this method splits out
- smaller change clusters and eliminates intervening ranges which have no changes.
+ Starting with the groups returned by :meth:`get_opcodes`, this method
+ splits out smaller change clusters and eliminates intervening ranges which
+ have no changes.
- The groups are returned in the same format as :meth:`get_opcodes`.
+ The groups are returned in the same format as :meth:`get_opcodes`.
-.. method:: SequenceMatcher.ratio()
+ .. method:: ratio()
- Return a measure of the sequences' similarity as a float in the range [0, 1].
+ Return a measure of the sequences' similarity as a float in the range [0,
+ 1].
- Where T is the total number of elements in both sequences, and M is the number
- of matches, this is 2.0\*M / T. Note that this is ``1.0`` if the sequences are
- identical, and ``0.0`` if they have nothing in common.
+ Where T is the total number of elements in both sequences, and M is the
+ number of matches, this is 2.0\*M / T. Note that this is ``1.0`` if the
+ sequences are identical, and ``0.0`` if they have nothing in common.
- This is expensive to compute if :meth:`get_matching_blocks` or
- :meth:`get_opcodes` hasn't already been called, in which case you may want to
- try :meth:`quick_ratio` or :meth:`real_quick_ratio` first to get an upper bound.
+ This is expensive to compute if :meth:`get_matching_blocks` or
+ :meth:`get_opcodes` hasn't already been called, in which case you may want
+ to try :meth:`quick_ratio` or :meth:`real_quick_ratio` first to get an
+ upper bound.
-.. method:: SequenceMatcher.quick_ratio()
+ .. method:: quick_ratio()
- Return an upper bound on :meth:`ratio` relatively quickly.
+ Return an upper bound on :meth:`ratio` relatively quickly.
- This isn't defined beyond that it is an upper bound on :meth:`ratio`, and is
- faster to compute.
+ This isn't defined beyond that it is an upper bound on :meth:`ratio`, and
+ is faster to compute.
-.. method:: SequenceMatcher.real_quick_ratio()
+ .. method:: real_quick_ratio()
- Return an upper bound on :meth:`ratio` very quickly.
+ Return an upper bound on :meth:`ratio` very quickly.
- This isn't defined beyond that it is an upper bound on :meth:`ratio`, and is
- faster to compute than either :meth:`ratio` or :meth:`quick_ratio`.
+ This isn't defined beyond that it is an upper bound on :meth:`ratio`, and
+ is faster to compute than either :meth:`ratio` or :meth:`quick_ratio`.
The three methods that return the ratio of matching to total characters can give
different results due to differing levels of approximation, although
@@ -589,17 +594,17 @@
length 1), and returns true if the character is junk. The default is ``None``,
meaning that no character is considered junk.
-:class:`Differ` objects are used (deltas generated) via a single method:
+ :class:`Differ` objects are used (deltas generated) via a single method:
-.. method:: Differ.compare(a, b)
+ .. method:: Differ.compare(a, b)
- Compare two sequences of lines, and generate the delta (a sequence of lines).
+ Compare two sequences of lines, and generate the delta (a sequence of lines).
- Each sequence must contain individual single-line strings ending with newlines.
- Such sequences can be obtained from the :meth:`readlines` method of file-like
- objects. The delta generated also consists of newline-terminated strings, ready
- to be printed as-is via the :meth:`writelines` method of a file-like object.
+ Each sequence must contain individual single-line strings ending with newlines.
+ Such sequences can be obtained from the :meth:`readlines` method of file-like
+ objects. The delta generated also consists of newline-terminated strings, ready
+ to be printed as-is via the :meth:`writelines` method of a file-like object.
.. _differ-examples:
Modified: python/branches/py3k/Doc/library/doctest.rst
==============================================================================
--- python/branches/py3k/Doc/library/doctest.rst (original)
+++ python/branches/py3k/Doc/library/doctest.rst Fri Apr 25 03:59:09 2008
@@ -1113,48 +1113,48 @@
names.
-:class:`DocTest` defines the following member variables. They are initialized
-by the constructor, and should not be modified directly.
+ :class:`DocTest` defines the following member variables. They are initialized by
+ the constructor, and should not be modified directly.
-.. attribute:: DocTest.examples
+ .. attribute:: examples
- A list of :class:`Example` objects encoding the individual interactive Python
- examples that should be run by this test.
+ A list of :class:`Example` objects encoding the individual interactive Python
+ examples that should be run by this test.
-.. attribute:: DocTest.globs
+ .. attribute:: globs
- The namespace (aka globals) that the examples should be run in. This is a
- dictionary mapping names to values. Any changes to the namespace made by the
- examples (such as binding new variables) will be reflected in :attr:`globs`
- after the test is run.
+ The namespace (aka globals) that the examples should be run in. This is a
+ dictionary mapping names to values. Any changes to the namespace made by the
+ examples (such as binding new variables) will be reflected in :attr:`globs`
+ after the test is run.
-.. attribute:: DocTest.name
+ .. attribute:: name
- A string name identifying the :class:`DocTest`. Typically, this is the name of
- the object or file that the test was extracted from.
+ A string name identifying the :class:`DocTest`. Typically, this is the name
+ of the object or file that the test was extracted from.
-.. attribute:: DocTest.filename
+ .. attribute:: filename
- The name of the file that this :class:`DocTest` was extracted from; or ``None``
- if the filename is unknown, or if the :class:`DocTest` was not extracted from a
- file.
+ The name of the file that this :class:`DocTest` was extracted from; or
+ ``None`` if the filename is unknown, or if the :class:`DocTest` was not
+ extracted from a file.
-.. attribute:: DocTest.lineno
+ .. attribute:: lineno
- The line number within :attr:`filename` where this :class:`DocTest` begins, or
- ``None`` if the line number is unavailable. This line number is zero-based with
- respect to the beginning of the file.
+ The line number within :attr:`filename` where this :class:`DocTest` begins, or
+ ``None`` if the line number is unavailable. This line number is zero-based
+ with respect to the beginning of the file.
-.. attribute:: DocTest.docstring
+ .. attribute:: docstring
- The string that the test was extracted from, or 'None' if the string is
- unavailable, or if the test was not extracted from a string.
+ The string that the test was extracted from, or 'None' if the string is
+ unavailable, or if the test was not extracted from a string.
.. _doctest-example:
@@ -1170,53 +1170,53 @@
of the same names.
-:class:`Example` defines the following member variables. They are initialized
-by the constructor, and should not be modified directly.
+ :class:`Example` defines the following member variables. They are initialized by
+ the constructor, and should not be modified directly.
-.. attribute:: Example.source
+ .. attribute:: source
- A string containing the example's source code. This source code consists of a
- single Python statement, and always ends with a newline; the constructor adds a
- newline when necessary.
+ A string containing the example's source code. This source code consists of a
+ single Python statement, and always ends with a newline; the constructor adds
+ a newline when necessary.
-.. attribute:: Example.want
+ .. attribute:: want
- The expected output from running the example's source code (either from stdout,
- or a traceback in case of exception). :attr:`want` ends with a newline unless
- no output is expected, in which case it's an empty string. The constructor adds
- a newline when necessary.
+ The expected output from running the example's source code (either from
+ stdout, or a traceback in case of exception). :attr:`want` ends with a
+ newline unless no output is expected, in which case it's an empty string. The
+ constructor adds a newline when necessary.
-.. attribute:: Example.exc_msg
+ .. attribute:: exc_msg
- The exception message generated by the example, if the example is expected to
- generate an exception; or ``None`` if it is not expected to generate an
- exception. This exception message is compared against the return value of
- :func:`traceback.format_exception_only`. :attr:`exc_msg` ends with a newline
- unless it's ``None``. The constructor adds a newline if needed.
+ The exception message generated by the example, if the example is expected to
+ generate an exception; or ``None`` if it is not expected to generate an
+ exception. This exception message is compared against the return value of
+ :func:`traceback.format_exception_only`. :attr:`exc_msg` ends with a newline
+ unless it's ``None``. The constructor adds a newline if needed.
-.. attribute:: Example.lineno
+ .. attribute:: lineno
- The line number within the string containing this example where the example
- begins. This line number is zero-based with respect to the beginning of the
- containing string.
+ The line number within the string containing this example where the example
+ begins. This line number is zero-based with respect to the beginning of the
+ containing string.
-.. attribute:: Example.indent
+ .. attribute:: indent
- The example's indentation in the containing string, i.e., the number of space
- characters that precede the example's first prompt.
+ The example's indentation in the containing string, i.e., the number of space
+ characters that precede the example's first prompt.
-.. attribute:: Example.options
+ .. attribute:: options
- A dictionary mapping from option flags to ``True`` or ``False``, which is used
- to override default options for this example. Any option flags not contained in
- this dictionary are left at their default value (as specified by the
- :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
+ A dictionary mapping from option flags to ``True`` or ``False``, which is used
+ to override default options for this example. Any option flags not contained
+ in this dictionary are left at their default value (as specified by the
+ :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
.. _doctest-doctestfinder:
@@ -1246,44 +1246,44 @@
:meth:`DocTestFinder.find` will include tests for objects with empty docstrings.
-:class:`DocTestFinder` defines the following method:
+ :class:`DocTestFinder` defines the following method:
-.. method:: DocTestFinder.find(obj[, name][, module][, globs][, extraglobs])
+ .. method:: find(obj[, name][, module][, globs][, extraglobs])
- Return a list of the :class:`DocTest`\ s that are defined by *obj*'s docstring,
- or by any of its contained objects' docstrings.
+ Return a list of the :class:`DocTest`\ s that are defined by *obj*'s
+ docstring, or by any of its contained objects' docstrings.
- The optional argument *name* specifies the object's name; this name will be used
- to construct names for the returned :class:`DocTest`\ s. If *name* is not
- specified, then ``obj.__name__`` is used.
+ The optional argument *name* specifies the object's name; this name will be
+ used to construct names for the returned :class:`DocTest`\ s. If *name* is
+ not specified, then ``obj.__name__`` is used.
- The optional parameter *module* is the module that contains the given object.
- If the module is not specified or is None, then the test finder will attempt to
- automatically determine the correct module. The object's module is used:
+ The optional parameter *module* is the module that contains the given object.
+ If the module is not specified or is None, then the test finder will attempt
+ to automatically determine the correct module. The object's module is used:
- * As a default namespace, if *globs* is not specified.
+ * As a default namespace, if *globs* is not specified.
- * To prevent the DocTestFinder from extracting DocTests from objects that are
- imported from other modules. (Contained objects with modules other than
- *module* are ignored.)
+ * To prevent the DocTestFinder from extracting DocTests from objects that are
+ imported from other modules. (Contained objects with modules other than
+ *module* are ignored.)
- * To find the name of the file containing the object.
+ * To find the name of the file containing the object.
- * To help find the line number of the object within its file.
+ * To help find the line number of the object within its file.
- If *module* is ``False``, no attempt to find the module will be made. This is
- obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
- is ``None`` but cannot be found automatically, then all objects are considered
- to belong to the (non-existent) module, so all contained objects will
- (recursively) be searched for doctests.
+ If *module* is ``False``, no attempt to find the module will be made. This is
+ obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
+ is ``None`` but cannot be found automatically, then all objects are considered
+ to belong to the (non-existent) module, so all contained objects will
+ (recursively) be searched for doctests.
- The globals for each :class:`DocTest` is formed by combining *globs* and
- *extraglobs* (bindings in *extraglobs* override bindings in *globs*). A new
- shallow copy of the globals dictionary is created for each :class:`DocTest`. If
- *globs* is not specified, then it defaults to the module's *__dict__*, if
- specified, or ``{}`` otherwise. If *extraglobs* is not specified, then it
- defaults to ``{}``.
+ The globals for each :class:`DocTest` is formed by combining *globs* and
+ *extraglobs* (bindings in *extraglobs* override bindings in *globs*). A new
+ shallow copy of the globals dictionary is created for each :class:`DocTest`.
+ If *globs* is not specified, then it defaults to the module's *__dict__*, if
+ specified, or ``{}`` otherwise. If *extraglobs* is not specified, then it
+ defaults to ``{}``.
.. _doctest-doctestparser:
@@ -1298,32 +1298,32 @@
them to create a :class:`DocTest` object.
-:class:`DocTestParser` defines the following methods:
+ :class:`DocTestParser` defines the following methods:
-.. method:: DocTestParser.get_doctest(string, globs, name, filename, lineno)
+ .. method:: get_doctest(string, globs, name, filename, lineno)
- Extract all doctest examples from the given string, and collect them into a
- :class:`DocTest` object.
+ Extract all doctest examples from the given string, and collect them into a
+ :class:`DocTest` object.
- *globs*, *name*, *filename*, and *lineno* are attributes for the new
- :class:`DocTest` object. See the documentation for :class:`DocTest` for more
- information.
+ *globs*, *name*, *filename*, and *lineno* are attributes for the new
+ :class:`DocTest` object. See the documentation for :class:`DocTest` for more
+ information.
-.. method:: DocTestParser.get_examples(string[, name])
+ .. method:: get_examples(string[, name])
- Extract all doctest examples from the given string, and return them as a list of
- :class:`Example` objects. Line numbers are 0-based. The optional argument
- *name* is a name identifying this string, and is only used for error messages.
+ Extract all doctest examples from the given string, and return them as a list
+ of :class:`Example` objects. Line numbers are 0-based. The optional argument
+ *name* is a name identifying this string, and is only used for error messages.
-.. method:: DocTestParser.parse(string[, name])
+ .. method:: parse(string[, name])
- Divide the given string into examples and intervening text, and return them as a
- list of alternating :class:`Example`\ s and strings. Line numbers for the
- :class:`Example`\ s are 0-based. The optional argument *name* is a name
- identifying this string, and is only used for error messages.
+ Divide the given string into examples and intervening text, and return them as
+ a list of alternating :class:`Example`\ s and strings. Line numbers for the
+ :class:`Example`\ s are 0-based. The optional argument *name* is a name
+ identifying this string, and is only used for error messages.
.. _doctest-doctestrunner:
@@ -1366,81 +1366,81 @@
For more information, see section :ref:`doctest-options`.
-:class:`DocTestParser` defines the following methods:
+ :class:`DocTestParser` defines the following methods:
-.. method:: DocTestRunner.report_start(out, test, example)
+ .. method:: report_start(out, test, example)
- Report that the test runner is about to process the given example. This method
- is provided to allow subclasses of :class:`DocTestRunner` to customize their
- output; it should not be called directly.
+ Report that the test runner is about to process the given example. This method
+ is provided to allow subclasses of :class:`DocTestRunner` to customize their
+ output; it should not be called directly.
- *example* is the example about to be processed. *test* is the test containing
- *example*. *out* is the output function that was passed to
- :meth:`DocTestRunner.run`.
+ *example* is the example about to be processed. *test* is the test
+ *containing example*. *out* is the output function that was passed to
+ :meth:`DocTestRunner.run`.
-.. method:: DocTestRunner.report_success(out, test, example, got)
+ .. method:: report_success(out, test, example, got)
- Report that the given example ran successfully. This method is provided to
- allow subclasses of :class:`DocTestRunner` to customize their output; it should
- not be called directly.
+ Report that the given example ran successfully. This method is provided to
+ allow subclasses of :class:`DocTestRunner` to customize their output; it
+ should not be called directly.
- *example* is the example about to be processed. *got* is the actual output from
- the example. *test* is the test containing *example*. *out* is the output
- function that was passed to :meth:`DocTestRunner.run`.
+ *example* is the example about to be processed. *got* is the actual output
+ from the example. *test* is the test containing *example*. *out* is the
+ output function that was passed to :meth:`DocTestRunner.run`.
-.. method:: DocTestRunner.report_failure(out, test, example, got)
+ .. method:: report_failure(out, test, example, got)
- Report that the given example failed. This method is provided to allow
- subclasses of :class:`DocTestRunner` to customize their output; it should not be
- called directly.
+ Report that the given example failed. This method is provided to allow
+ subclasses of :class:`DocTestRunner` to customize their output; it should not
+ be called directly.
- *example* is the example about to be processed. *got* is the actual output from
- the example. *test* is the test containing *example*. *out* is the output
- function that was passed to :meth:`DocTestRunner.run`.
+ *example* is the example about to be processed. *got* is the actual output
+ from the example. *test* is the test containing *example*. *out* is the
+ output function that was passed to :meth:`DocTestRunner.run`.
-.. method:: DocTestRunner.report_unexpected_exception(out, test, example, exc_info)
+ .. method:: report_unexpected_exception(out, test, example, exc_info)
- Report that the given example raised an unexpected exception. This method is
- provided to allow subclasses of :class:`DocTestRunner` to customize their
- output; it should not be called directly.
+ Report that the given example raised an unexpected exception. This method is
+ provided to allow subclasses of :class:`DocTestRunner` to customize their
+ output; it should not be called directly.
- *example* is the example about to be processed. *exc_info* is a tuple containing
- information about the unexpected exception (as returned by
- :func:`sys.exc_info`). *test* is the test containing *example*. *out* is the
- output function that was passed to :meth:`DocTestRunner.run`.
+ *example* is the example about to be processed. *exc_info* is a tuple
+ containing information about the unexpected exception (as returned by
+ :func:`sys.exc_info`). *test* is the test containing *example*. *out* is the
+ output function that was passed to :meth:`DocTestRunner.run`.
-.. method:: DocTestRunner.run(test[, compileflags][, out][, clear_globs])
+ .. method:: run(test[, compileflags][, out][, clear_globs])
- Run the examples in *test* (a :class:`DocTest` object), and display the results
- using the writer function *out*.
+ Run the examples in *test* (a :class:`DocTest` object), and display the
+ results using the writer function *out*.
- The examples are run in the namespace ``test.globs``. If *clear_globs* is true
- (the default), then this namespace will be cleared after the test runs, to help
- with garbage collection. If you would like to examine the namespace after the
- test completes, then use *clear_globs=False*.
+ The examples are run in the namespace ``test.globs``. If *clear_globs* is
+ true (the default), then this namespace will be cleared after the test runs,
+ to help with garbage collection. If you would like to examine the namespace
+ after the test completes, then use *clear_globs=False*.
- *compileflags* gives the set of flags that should be used by the Python compiler
- when running the examples. If not specified, then it will default to the set of
- future-import flags that apply to *globs*.
+ *compileflags* gives the set of flags that should be used by the Python
+ compiler when running the examples. If not specified, then it will default to
+ the set of future-import flags that apply to *globs*.
- The output of each example is checked using the :class:`DocTestRunner`'s output
- checker, and the results are formatted by the :meth:`DocTestRunner.report_\*`
- methods.
+ The output of each example is checked using the :class:`DocTestRunner`'s
+ output checker, and the results are formatted by the
+ :meth:`DocTestRunner.report_\*` methods.
-.. method:: DocTestRunner.summarize([verbose])
+ .. method:: summarize([verbose])
- Print a summary of all the test cases that have been run by this DocTestRunner,
- and return a :term:`named tuple` ``TestResults(failed, attempted)``.
-
- The optional *verbose* argument controls how detailed the summary is. If the
- verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is used.
+ Print a summary of all the test cases that have been run by this DocTestRunner,
+ and return a :term:`named tuple` ``TestResults(failed, attempted)``.
+ The optional *verbose* argument controls how detailed the summary is. If the
+ verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is
+ used.
.. _doctest-outputchecker:
@@ -1457,22 +1457,22 @@
the differences between two outputs.
-:class:`OutputChecker` defines the following methods:
+ :class:`OutputChecker` defines the following methods:
-.. method:: OutputChecker.check_output(want, got, optionflags)
+ .. method:: check_output(want, got, optionflags)
- Return ``True`` iff the actual output from an example (*got*) matches the
- expected output (*want*). These strings are always considered to match if they
- are identical; but depending on what option flags the test runner is using,
- several non-exact match types are also possible. See section
- :ref:`doctest-options` for more information about option flags.
+ Return ``True`` iff the actual output from an example (*got*) matches the
+ expected output (*want*). These strings are always considered to match if
+ they are identical; but depending on what option flags the test runner is
+ using, several non-exact match types are also possible. See section
+ :ref:`doctest-options` for more information about option flags.
-.. method:: OutputChecker.output_difference(example, got, optionflags)
+ .. method:: output_difference(example, got, optionflags)
- Return a string describing the differences between the expected output for a
- given example (*example*) and the actual output (*got*). *optionflags* is the
- set of option flags used to compare *want* and *got*.
+ Return a string describing the differences between the expected output for a
+ given example (*example*) and the actual output (*got*). *optionflags* is the
+ set of option flags used to compare *want* and *got*.
.. _doctest-debugging:
Modified: python/branches/py3k/Doc/library/email.charset.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.charset.rst (original)
+++ python/branches/py3k/Doc/library/email.charset.rst Fri Apr 25 03:59:09 2008
@@ -38,164 +38,168 @@
will not be encoded, but output text will be converted from the ``euc-jp``
character set to the ``iso-2022-jp`` character set.
-:class:`Charset` instances have the following data attributes:
+ :class:`Charset` instances have the following data attributes:
-.. data:: input_charset
+ .. attribute:: input_charset
- The initial character set specified. Common aliases are converted to their
- *official* email names (e.g. ``latin_1`` is converted to ``iso-8859-1``).
- Defaults to 7-bit ``us-ascii``.
+ The initial character set specified. Common aliases are converted to
+ their *official* email names (e.g. ``latin_1`` is converted to
+ ``iso-8859-1``). Defaults to 7-bit ``us-ascii``.
-.. data:: header_encoding
+ .. attribute:: header_encoding
- If the character set must be encoded before it can be used in an email header,
- this attribute will be set to ``Charset.QP`` (for quoted-printable),
- ``Charset.BASE64`` (for base64 encoding), or ``Charset.SHORTEST`` for the
- shortest of QP or BASE64 encoding. Otherwise, it will be ``None``.
+ If the character set must be encoded before it can be used in an email
+ header, this attribute will be set to ``Charset.QP`` (for
+ quoted-printable), ``Charset.BASE64`` (for base64 encoding), or
+ ``Charset.SHORTEST`` for the shortest of QP or BASE64 encoding. Otherwise,
+ it will be ``None``.
-.. data:: body_encoding
+ .. attribute:: body_encoding
- Same as *header_encoding*, but describes the encoding for the mail message's
- body, which indeed may be different than the header encoding.
- ``Charset.SHORTEST`` is not allowed for *body_encoding*.
+ Same as *header_encoding*, but describes the encoding for the mail
+ message's body, which indeed may be different than the header encoding.
+ ``Charset.SHORTEST`` is not allowed for *body_encoding*.
-.. data:: output_charset
+ .. attribute:: output_charset
- Some character sets must be converted before they can be used in email headers
- or bodies. If the *input_charset* is one of them, this attribute will contain
- the name of the character set output will be converted to. Otherwise, it will
- be ``None``.
+ Some character sets must be converted before they can be used in email headers
+ or bodies. If the *input_charset* is one of them, this attribute will
+ contain the name of the character set output will be converted to. Otherwise, it will
+ be ``None``.
-.. data:: input_codec
+ .. attribute:: input_codec
- The name of the Python codec used to convert the *input_charset* to Unicode. If
- no conversion codec is necessary, this attribute will be ``None``.
+ The name of the Python codec used to convert the *input_charset* to
+ Unicode. If no conversion codec is necessary, this attribute will be
+ ``None``.
-.. data:: output_codec
+ .. attribute:: output_codec
- The name of the Python codec used to convert Unicode to the *output_charset*.
- If no conversion codec is necessary, this attribute will have the same value as
- the *input_codec*.
+ The name of the Python codec used to convert Unicode to the
+ *output_charset*. If no conversion codec is necessary, this attribute
+ will have the same value as the *input_codec*.
-:class:`Charset` instances also have the following methods:
+ :class:`Charset` instances also have the following methods:
-.. method:: Charset.get_body_encoding()
+ .. method:: get_body_encoding()
- Return the content transfer encoding used for body encoding.
+ Return the content transfer encoding used for body encoding.
- This is either the string ``quoted-printable`` or ``base64`` depending on the
- encoding used, or it is a function, in which case you should call the function
- with a single argument, the Message object being encoded. The function should
- then set the :mailheader:`Content-Transfer-Encoding` header itself to whatever
- is appropriate.
+ This is either the string ``quoted-printable`` or ``base64`` depending on
+ the encoding used, or it is a function, in which case you should call the
+ function with a single argument, the Message object being encoded. The
+ function should then set the :mailheader:`Content-Transfer-Encoding`
+ header itself to whatever is appropriate.
- Returns the string ``quoted-printable`` if *body_encoding* is ``QP``, returns
- the string ``base64`` if *body_encoding* is ``BASE64``, and returns the string
- ``7bit`` otherwise.
+ Returns the string ``quoted-printable`` if *body_encoding* is ``QP``,
+ returns the string ``base64`` if *body_encoding* is ``BASE64``, and
+ returns the string ``7bit`` otherwise.
-.. method:: Charset.convert(s)
+ .. method:: convert(s)
- Convert the string *s* from the *input_codec* to the *output_codec*.
+ Convert the string *s* from the *input_codec* to the *output_codec*.
-.. method:: Charset.to_splittable(s)
+ .. method:: to_splittable(s)
- Convert a possibly multibyte string to a safely splittable format. *s* is the
- string to split.
+ Convert a possibly multibyte string to a safely splittable format. *s* is
+ the string to split.
- Uses the *input_codec* to try and convert the string to Unicode, so it can be
- safely split on character boundaries (even for multibyte characters).
+ Uses the *input_codec* to try and convert the string to Unicode, so it can
+ be safely split on character boundaries (even for multibyte characters).
- Returns the string as-is if it isn't known how to convert *s* to Unicode with
- the *input_charset*.
+ Returns the string as-is if it isn't known how to convert *s* to Unicode
+ with the *input_charset*.
- Characters that could not be converted to Unicode will be replaced with the
- Unicode replacement character ``'U+FFFD'``.
+ Characters that could not be converted to Unicode will be replaced with
+ the Unicode replacement character ``'U+FFFD'``.
-.. method:: Charset.from_splittable(ustr[, to_output])
+ .. method:: from_splittable(ustr[, to_output])
- Convert a splittable string back into an encoded string. *ustr* is a Unicode
- string to "unsplit".
+ Convert a splittable string back into an encoded string. *ustr* is a
+ Unicode string to "unsplit".
- This method uses the proper codec to try and convert the string from Unicode
- back into an encoded format. Return the string as-is if it is not Unicode, or
- if it could not be converted from Unicode.
+ This method uses the proper codec to try and convert the string from
+ Unicode back into an encoded format. Return the string as-is if it is not
+ Unicode, or if it could not be converted from Unicode.
- Characters that could not be converted from Unicode will be replaced with an
- appropriate character (usually ``'?'``).
+ Characters that could not be converted from Unicode will be replaced with
+ an appropriate character (usually ``'?'``).
- If *to_output* is ``True`` (the default), uses *output_codec* to convert to an
- encoded format. If *to_output* is ``False``, it uses *input_codec*.
+ If *to_output* is ``True`` (the default), uses *output_codec* to convert
+ to an encoded format. If *to_output* is ``False``, it uses *input_codec*.
-.. method:: Charset.get_output_charset()
+ .. method:: get_output_charset()
- Return the output character set.
+ Return the output character set.
- This is the *output_charset* attribute if that is not ``None``, otherwise it is
- *input_charset*.
+ This is the *output_charset* attribute if that is not ``None``, otherwise
+ it is *input_charset*.
-.. method:: Charset.encoded_header_len()
+ .. method:: encoded_header_len()
- Return the length of the encoded header string, properly calculating for
- quoted-printable or base64 encoding.
+ Return the length of the encoded header string, properly calculating for
+ quoted-printable or base64 encoding.
-.. method:: Charset.header_encode(s[, convert])
+ .. method:: header_encode(s[, convert])
- Header-encode the string *s*.
+ Header-encode the string *s*.
- If *convert* is ``True``, the string will be converted from the input charset to
- the output charset automatically. This is not useful for multibyte character
- sets, which have line length issues (multibyte characters must be split on a
- character, not a byte boundary); use the higher-level :class:`Header` class to
- deal with these issues (see :mod:`email.header`). *convert* defaults to
- ``False``.
+ If *convert* is ``True``, the string will be converted from the input
+ charset to the output charset automatically. This is not useful for
+ multibyte character sets, which have line length issues (multibyte
+ characters must be split on a character, not a byte boundary); use the
+ higher-level :class:`Header` class to deal with these issues (see
+ :mod:`email.header`). *convert* defaults to ``False``.
- The type of encoding (base64 or quoted-printable) will be based on the
- *header_encoding* attribute.
+ The type of encoding (base64 or quoted-printable) will be based on the
+ *header_encoding* attribute.
-.. method:: Charset.body_encode(s[, convert])
+ .. method:: body_encode(s[, convert])
- Body-encode the string *s*.
+ Body-encode the string *s*.
- If *convert* is ``True`` (the default), the string will be converted from the
- input charset to output charset automatically. Unlike :meth:`header_encode`,
- there are no issues with byte boundaries and multibyte charsets in email bodies,
- so this is usually pretty safe.
+ If *convert* is ``True`` (the default), the string will be converted from
+ the input charset to output charset automatically. Unlike
+ :meth:`header_encode`, there are no issues with byte boundaries and
+ multibyte charsets in email bodies, so this is usually pretty safe.
- The type of encoding (base64 or quoted-printable) will be based on the
- *body_encoding* attribute.
+ The type of encoding (base64 or quoted-printable) will be based on the
+ *body_encoding* attribute.
-The :class:`Charset` class also provides a number of methods to support standard
-operations and built-in functions.
+ The :class:`Charset` class also provides a number of methods to support
+ standard operations and built-in functions.
-.. method:: Charset.__str__()
+ .. method:: __str__()
- Returns *input_charset* as a string coerced to lower case. :meth:`__repr__` is
- an alias for :meth:`__str__`.
+ Returns *input_charset* as a string coerced to lower
+ case. :meth:`__repr__` is an alias for :meth:`__str__`.
-.. method:: Charset.__eq__(other)
+ .. method:: __eq__(other)
- This method allows you to compare two :class:`Charset` instances for equality.
+ This method allows you to compare two :class:`Charset` instances for
+ equality.
-.. method:: Header.__ne__(other)
+ .. method:: __ne__(other)
- This method allows you to compare two :class:`Charset` instances for inequality.
+ This method allows you to compare two :class:`Charset` instances for
+ inequality.
The :mod:`email.charset` module also provides the following functions for adding
new entries to the global character set, alias, and codec registries:
Modified: python/branches/py3k/Doc/library/email.generator.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.generator.rst (original)
+++ python/branches/py3k/Doc/library/email.generator.rst Fri Apr 25 03:59:09 2008
@@ -44,35 +44,34 @@
:mod:`email.header.Header` class. Set to zero to disable header wrapping. The
default is 78, as recommended (but not required) by :rfc:`2822`.
-The other public :class:`Generator` methods are:
+ The other public :class:`Generator` methods are:
-.. method:: Generator.flatten(msg[, unixfrom])
+ .. method:: flatten(msg[, unixfrom])
- Print the textual representation of the message object structure rooted at *msg*
- to the output file specified when the :class:`Generator` instance was created.
- Subparts are visited depth-first and the resulting text will be properly MIME
- encoded.
+ Print the textual representation of the message object structure rooted at
+ *msg* to the output file specified when the :class:`Generator` instance
+ was created. Subparts are visited depth-first and the resulting text will
+ be properly MIME encoded.
- Optional *unixfrom* is a flag that forces the printing of the envelope header
- delimiter before the first :rfc:`2822` header of the root message object. If
- the root object has no envelope header, a standard one is crafted. By default,
- this is set to ``False`` to inhibit the printing of the envelope delimiter.
+ Optional *unixfrom* is a flag that forces the printing of the envelope
+ header delimiter before the first :rfc:`2822` header of the root message
+ object. If the root object has no envelope header, a standard one is
+ crafted. By default, this is set to ``False`` to inhibit the printing of
+ the envelope delimiter.
- Note that for subparts, no envelope header is ever printed.
+ Note that for subparts, no envelope header is ever printed.
+ .. method:: clone(fp)
-.. method:: Generator.clone(fp)
+ Return an independent clone of this :class:`Generator` instance with the
+ exact same options.
- Return an independent clone of this :class:`Generator` instance with the exact
- same options.
+ .. method:: write(s)
-
-.. method:: Generator.write(s)
-
- Write the string *s* to the underlying file object, i.e. *outfp* passed to
- :class:`Generator`'s constructor. This provides just enough file-like API for
- :class:`Generator` instances to be used in the :func:`print` function.
+ Write the string *s* to the underlying file object, i.e. *outfp* passed to
+ :class:`Generator`'s constructor. This provides just enough file-like API
+ for :class:`Generator` instances to be used in the :func:`print` function.
As a convenience, see the methods :meth:`Message.as_string` and
``str(aMessage)``, a.k.a. :meth:`Message.__str__`, which simplify the generation
Modified: python/branches/py3k/Doc/library/email.header.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.header.rst (original)
+++ python/branches/py3k/Doc/library/email.header.rst Fri Apr 25 03:59:09 2008
@@ -74,65 +74,66 @@
and is usually either a space or a hard tab character. This character will be
prepended to continuation lines.
-Optional *errors* is passed straight through to the :meth:`append` method.
+ Optional *errors* is passed straight through to the :meth:`append` method.
-.. method:: Header.append(s[, charset[, errors]])
+ .. method:: append(s[, charset[, errors]])
- Append the string *s* to the MIME header.
+ Append the string *s* to the MIME header.
- Optional *charset*, if given, should be a :class:`Charset` instance (see
- :mod:`email.charset`) or the name of a character set, which will be converted to
- a :class:`Charset` instance. A value of ``None`` (the default) means that the
- *charset* given in the constructor is used.
+ Optional *charset*, if given, should be a :class:`Charset` instance (see
+ :mod:`email.charset`) or the name of a character set, which will be
+ converted to a :class:`Charset` instance. A value of ``None`` (the
+ default) means that the *charset* given in the constructor is used.
- *s* may be an instance of :class:`bytes` or :class:`str`. If it is an instance
- of :class:`bytes`, then *charset* is the encoding of that byte string, and a
- :exc:`UnicodeError` will be raised if the string cannot be decoded with that
- character set.
+ *s* may be an instance of :class:`bytes` or :class:`str`. If it is an
+ instance of :class:`bytes`, then *charset* is the encoding of that byte
+ string, and a :exc:`UnicodeError` will be raised if the string cannot be
+ decoded with that character set.
- If *s* is an instance of :class:`str`, then *charset* is a hint specifying the
- character set of the characters in the string. In this case, when producing an
- :rfc:`2822`\ -compliant header using :rfc:`2047` rules, the Unicode string will
- be encoded using the following charsets in order: ``us-ascii``, the *charset*
- hint, ``utf-8``. The first character set to not provoke a :exc:`UnicodeError`
- is used.
+ If *s* is an instance of :class:`str`, then *charset* is a hint specifying
+ the character set of the characters in the string. In this case, when
+ producing an :rfc:`2822`\ -compliant header using :rfc:`2047` rules, the
+ Unicode string will be encoded using the following charsets in order:
+ ``us-ascii``, the *charset* hint, ``utf-8``. The first character set to
+ not provoke a :exc:`UnicodeError` is used.
- Optional *errors* is passed through to any :func:`encode` or
- :func:`ustr.encode` call, and defaults to "strict".
+ Optional *errors* is passed through to any :func:`encode` or
+ :func:`ustr.encode` call, and defaults to "strict".
-.. method:: Header.encode([splitchars])
+ .. method:: encode([splitchars])
- Encode a message header into an RFC-compliant format, possibly wrapping long
- lines and encapsulating non-ASCII parts in base64 or quoted-printable encodings.
- Optional *splitchars* is a string containing characters to split long ASCII
- lines on, in rough support of :rfc:`2822`'s *highest level syntactic breaks*.
- This doesn't affect :rfc:`2047` encoded lines.
+ Encode a message header into an RFC-compliant format, possibly wrapping
+ long lines and encapsulating non-ASCII parts in base64 or quoted-printable
+ encodings. Optional *splitchars* is a string containing characters to
+ split long ASCII lines on, in rough support of :rfc:`2822`'s *highest
+ level syntactic breaks*. This doesn't affect :rfc:`2047` encoded lines.
-The :class:`Header` class also provides a number of methods to support standard
-operators and built-in functions.
+ The :class:`Header` class also provides a number of methods to support
+ standard operators and built-in functions.
-.. method:: Header.__str__()
+ .. method:: __str__()
- A synonym for :meth:`Header.encode`. Useful for ``str(aHeader)``.
+ A synonym for :meth:`Header.encode`. Useful for ``str(aHeader)``.
-.. method:: Header.__unicode__()
+ .. method:: __unicode__()
- A helper for :class:`str`'s :func:`encode` method. Returns the header as a
- Unicode string.
+ A helper for :class:`str`'s :func:`encode` method. Returns the header as
+ a Unicode string.
+ .. method:: __eq__(other)
-.. method:: Header.__eq__(other)
+ This method allows you to compare two :class:`Header` instances for
+ equality.
- This method allows you to compare two :class:`Header` instances for equality.
+ .. method:: __ne__(other)
-.. method:: Header.__ne__(other)
-
- This method allows you to compare two :class:`Header` instances for inequality.
+ This method allows you to compare two :class:`Header` instances for
+ inequality.
The :mod:`email.header` module also provides the following convenient functions.
Modified: python/branches/py3k/Doc/library/email.message.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.message.rst (original)
+++ python/branches/py3k/Doc/library/email.message.rst Fri Apr 25 03:59:09 2008
@@ -36,472 +36,489 @@
The constructor takes no arguments.
-.. method:: Message.as_string([unixfrom])
+ .. method:: as_string([unixfrom])
- Return the entire message flattened as a string. When optional *unixfrom* is
- ``True``, the envelope header is included in the returned string. *unixfrom*
- defaults to ``False``.
+ Return the entire message flattened as a string. When optional *unixfrom*
+ is ``True``, the envelope header is included in the returned string.
+ *unixfrom* defaults to ``False``.
- Note that this method is provided as a convenience and may not always format the
- message the way you want. For example, by default it mangles lines that begin
- with ``From``. For more flexibility, instantiate a :class:`Generator` instance
- and use its :meth:`flatten` method directly. For example::
+ Note that this method is provided as a convenience and may not always
+ format the message the way you want. For example, by default it mangles
+ lines that begin with ``From``. For more flexibility, instantiate a
+ :class:`Generator` instance and use its :meth:`flatten` method directly.
+ For example::
- from cStringIO import StringIO
- from email.generator import Generator
- fp = StringIO()
- g = Generator(fp, mangle_from_=False, maxheaderlen=60)
- g.flatten(msg)
- text = fp.getvalue()
+ from cStringIO import StringIO
+ from email.generator import Generator
+ fp = StringIO()
+ g = Generator(fp, mangle_from_=False, maxheaderlen=60)
+ g.flatten(msg)
+ text = fp.getvalue()
-.. method:: Message.__str__()
+ .. method:: __str__()
- Equivalent to ``as_string(unixfrom=True)``.
+ Equivalent to ``as_string(unixfrom=True)``.
-.. method:: Message.is_multipart()
+ .. method:: is_multipart()
- Return ``True`` if the message's payload is a list of sub-\ :class:`Message`
- objects, otherwise return ``False``. When :meth:`is_multipart` returns False,
- the payload should be a string object.
+ Return ``True`` if the message's payload is a list of sub-\
+ :class:`Message` objects, otherwise return ``False``. When
+ :meth:`is_multipart` returns False, the payload should be a string object.
-.. method:: Message.set_unixfrom(unixfrom)
+ .. method:: set_unixfrom(unixfrom)
- Set the message's envelope header to *unixfrom*, which should be a string.
+ Set the message's envelope header to *unixfrom*, which should be a string.
-.. method:: Message.get_unixfrom()
+ .. method:: get_unixfrom()
- Return the message's envelope header. Defaults to ``None`` if the envelope
- header was never set.
+ Return the message's envelope header. Defaults to ``None`` if the
+ envelope header was never set.
-.. method:: Message.attach(payload)
+ .. method:: attach(payload)
- Add the given *payload* to the current payload, which must be ``None`` or a list
- of :class:`Message` objects before the call. After the call, the payload will
- always be a list of :class:`Message` objects. If you want to set the payload to
- a scalar object (e.g. a string), use :meth:`set_payload` instead.
+ Add the given *payload* to the current payload, which must be ``None`` or
+ a list of :class:`Message` objects before the call. After the call, the
+ payload will always be a list of :class:`Message` objects. If you want to
+ set the payload to a scalar object (e.g. a string), use
+ :meth:`set_payload` instead.
-.. method:: Message.get_payload([i[, decode]])
+ .. method:: get_payload([i[, decode]])
- Return a reference the current payload, which will be a list of :class:`Message`
- objects when :meth:`is_multipart` is ``True``, or a string when
- :meth:`is_multipart` is ``False``. If the payload is a list and you mutate the
- list object, you modify the message's payload in place.
+ Return a reference the current payload, which will be a list of
+ :class:`Message` objects when :meth:`is_multipart` is ``True``, or a
+ string when :meth:`is_multipart` is ``False``. If the payload is a list
+ and you mutate the list object, you modify the message's payload in place.
- With optional argument *i*, :meth:`get_payload` will return the *i*-th element
- of the payload, counting from zero, if :meth:`is_multipart` is ``True``. An
- :exc:`IndexError` will be raised if *i* is less than 0 or greater than or equal
- to the number of items in the payload. If the payload is a string (i.e.
- :meth:`is_multipart` is ``False``) and *i* is given, a :exc:`TypeError` is
- raised.
+ With optional argument *i*, :meth:`get_payload` will return the *i*-th
+ element of the payload, counting from zero, if :meth:`is_multipart` is
+ ``True``. An :exc:`IndexError` will be raised if *i* is less than 0 or
+ greater than or equal to the number of items in the payload. If the
+ payload is a string (i.e. :meth:`is_multipart` is ``False``) and *i* is
+ given, a :exc:`TypeError` is raised.
- Optional *decode* is a flag indicating whether the payload should be decoded or
- not, according to the :mailheader:`Content-Transfer-Encoding` header. When
- ``True`` and the message is not a multipart, the payload will be decoded if this
- header's value is ``quoted-printable`` or ``base64``. If some other encoding is
- used, or :mailheader:`Content-Transfer-Encoding` header is missing, or if the
- payload has bogus base64 data, the payload is returned as-is (undecoded). If
- the message is a multipart and the *decode* flag is ``True``, then ``None`` is
- returned. The default for *decode* is ``False``.
+ Optional *decode* is a flag indicating whether the payload should be
+ decoded or not, according to the :mailheader:`Content-Transfer-Encoding`
+ header. When ``True`` and the message is not a multipart, the payload will
+ be decoded if this header's value is ``quoted-printable`` or ``base64``.
+ If some other encoding is used, or :mailheader:`Content-Transfer-Encoding`
+ header is missing, or if the payload has bogus base64 data, the payload is
+ returned as-is (undecoded). If the message is a multipart and the
+ *decode* flag is ``True``, then ``None`` is returned. The default for
+ *decode* is ``False``.
-.. method:: Message.set_payload(payload[, charset])
+ .. method:: set_payload(payload[, charset])
- Set the entire message object's payload to *payload*. It is the client's
- responsibility to ensure the payload invariants. Optional *charset* sets the
- message's default character set; see :meth:`set_charset` for details.
+ Set the entire message object's payload to *payload*. It is the client's
+ responsibility to ensure the payload invariants. Optional *charset* sets
+ the message's default character set; see :meth:`set_charset` for details.
+ .. method:: set_charset(charset)
-.. method:: Message.set_charset(charset)
+ Set the character set of the payload to *charset*, which can either be a
+ :class:`Charset` instance (see :mod:`email.charset`), a string naming a
+ character set, or ``None``. If it is a string, it will be converted to a
+ :class:`Charset` instance. If *charset* is ``None``, the ``charset``
+ parameter will be removed from the :mailheader:`Content-Type`
+ header. Anything else will generate a :exc:`TypeError`.
- Set the character set of the payload to *charset*, which can either be a
- :class:`Charset` instance (see :mod:`email.charset`), a string naming a
- character set, or ``None``. If it is a string, it will be converted to a
- :class:`Charset` instance. If *charset* is ``None``, the ``charset`` parameter
- will be removed from the :mailheader:`Content-Type` header. Anything else will
- generate a :exc:`TypeError`.
+ The message will be assumed to be of type :mimetype:`text/\*` encoded with
+ *charset.input_charset*. It will be converted to *charset.output_charset*
+ and encoded properly, if needed, when generating the plain text
+ representation of the message. MIME headers (:mailheader:`MIME-Version`,
+ :mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will
+ be added as needed.
- The message will be assumed to be of type :mimetype:`text/\*` encoded with
- *charset.input_charset*. It will be converted to *charset.output_charset* and
- encoded properly, if needed, when generating the plain text representation of
- the message. MIME headers (:mailheader:`MIME-Version`,
- :mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will be
- added as needed.
+ .. method:: get_charset()
+ Return the :class:`Charset` instance associated with the message's
+ payload.
-.. method:: Message.get_charset()
+ The following methods implement a mapping-like interface for accessing the
+ message's :rfc:`2822` headers. Note that there are some semantic differences
+ between these methods and a normal mapping (i.e. dictionary) interface. For
+ example, in a dictionary there are no duplicate keys, but here there may be
+ duplicate message headers. Also, in dictionaries there is no guaranteed
+ order to the keys returned by :meth:`keys`, but in a :class:`Message` object,
+ headers are always returned in the order they appeared in the original
+ message, or were added to the message later. Any header deleted and then
+ re-added are always appended to the end of the header list.
- Return the :class:`Charset` instance associated with the message's payload.
+ These semantic differences are intentional and are biased toward maximal
+ convenience.
-The following methods implement a mapping-like interface for accessing the
-message's :rfc:`2822` headers. Note that there are some semantic differences
-between these methods and a normal mapping (i.e. dictionary) interface. For
-example, in a dictionary there are no duplicate keys, but here there may be
-duplicate message headers. Also, in dictionaries there is no guaranteed order
-to the keys returned by :meth:`keys`, but in a :class:`Message` object, headers
-are always returned in the order they appeared in the original message, or were
-added to the message later. Any header deleted and then re-added are always
-appended to the end of the header list.
+ Note that in all cases, any envelope header present in the message is not
+ included in the mapping interface.
-These semantic differences are intentional and are biased toward maximal
-convenience.
-Note that in all cases, any envelope header present in the message is not
-included in the mapping interface.
+ .. method:: __len__()
+ Return the total number of headers, including duplicates.
-.. method:: Message.__len__()
- Return the total number of headers, including duplicates.
+ .. method:: __contains__(name)
+ Return true if the message object has a field named *name*. Matching is
+ done case-insensitively and *name* should not include the trailing colon.
+ Used for the ``in`` operator, e.g.::
-.. method:: Message.__contains__(name)
+ if 'message-id' in myMessage:
+ print('Message-ID:', myMessage['message-id'])
- Return true if the message object has a field named *name*. Matching is done
- case-insensitively and *name* should not include the trailing colon. Used for
- the ``in`` operator, e.g.::
- if 'message-id' in myMessage:
- print('Message-ID:', myMessage['message-id'])
+ .. method:: __getitem__(name)
+ Return the value of the named header field. *name* should not include the
+ colon field separator. If the header is missing, ``None`` is returned; a
+ :exc:`KeyError` is never raised.
-.. method:: Message.__getitem__(name)
+ Note that if the named field appears more than once in the message's
+ headers, exactly which of those field values will be returned is
+ undefined. Use the :meth:`get_all` method to get the values of all the
+ extant named headers.
- Return the value of the named header field. *name* should not include the colon
- field separator. If the header is missing, ``None`` is returned; a
- :exc:`KeyError` is never raised.
- Note that if the named field appears more than once in the message's headers,
- exactly which of those field values will be returned is undefined. Use the
- :meth:`get_all` method to get the values of all the extant named headers.
+ .. method:: __setitem__(name, val)
+ Add a header to the message with field name *name* and value *val*. The
+ field is appended to the end of the message's existing fields.
-.. method:: Message.__setitem__(name, val)
+ Note that this does *not* overwrite or delete any existing header with the same
+ name. If you want to ensure that the new header is the only one present in the
+ message with field name *name*, delete the field first, e.g.::
- Add a header to the message with field name *name* and value *val*. The field
- is appended to the end of the message's existing fields.
+ del msg['subject']
+ msg['subject'] = 'Python roolz!'
- Note that this does *not* overwrite or delete any existing header with the same
- name. If you want to ensure that the new header is the only one present in the
- message with field name *name*, delete the field first, e.g.::
- del msg['subject']
- msg['subject'] = 'Python roolz!'
+ .. method:: __delitem__(name)
+ Delete all occurrences of the field with name *name* from the message's
+ headers. No exception is raised if the named field isn't present in the headers.
-.. method:: Message.__delitem__(name)
- Delete all occurrences of the field with name *name* from the message's headers.
- No exception is raised if the named field isn't present in the headers.
+ .. method:: Message.__contains__(name)
+ Return true if the message contains a header field named *name*, otherwise
+ return false.
-.. method:: Message.__contains__(name)
- Return true if the message contains a header field named *name*, otherwise
- return false.
+ .. method:: keys()
+ Return a list of all the message's header field names.
-.. method:: Message.keys()
- Return a list of all the message's header field names.
+ .. method:: values()
+ Return a list of all the message's field values.
-.. method:: Message.values()
- Return a list of all the message's field values.
+ .. method:: items()
+ Return a list of 2-tuples containing all the message's field headers and
+ values.
-.. method:: Message.items()
- Return a list of 2-tuples containing all the message's field headers and values.
+ .. method:: get(name[, failobj])
+ Return the value of the named header field. This is identical to
+ :meth:`__getitem__` except that optional *failobj* is returned if the
+ named header is missing (defaults to ``None``).
-.. method:: Message.get(name[, failobj])
+ Here are some additional useful methods:
- Return the value of the named header field. This is identical to
- :meth:`__getitem__` except that optional *failobj* is returned if the named
- header is missing (defaults to ``None``).
-Here are some additional useful methods:
+ .. method:: get_all(name[, failobj])
+ Return a list of all the values for the field named *name*. If there are
+ no such named headers in the message, *failobj* is returned (defaults to
+ ``None``).
-.. method:: Message.get_all(name[, failobj])
- Return a list of all the values for the field named *name*. If there are no such
- named headers in the message, *failobj* is returned (defaults to ``None``).
+ .. method:: add_header(_name, _value, **_params)
+ Extended header setting. This method is similar to :meth:`__setitem__`
+ except that additional header parameters can be provided as keyword
+ arguments. *_name* is the header field to add and *_value* is the
+ *primary* value for the header.
-.. method:: Message.add_header(_name, _value, **_params)
+ For each item in the keyword argument dictionary *_params*, the key is
+ taken as the parameter name, with underscores converted to dashes (since
+ dashes are illegal in Python identifiers). Normally, the parameter will
+ be added as ``key="value"`` unless the value is ``None``, in which case
+ only the key will be added.
- Extended header setting. This method is similar to :meth:`__setitem__` except
- that additional header parameters can be provided as keyword arguments. *_name*
- is the header field to add and *_value* is the *primary* value for the header.
+ Here's an example::
- For each item in the keyword argument dictionary *_params*, the key is taken as
- the parameter name, with underscores converted to dashes (since dashes are
- illegal in Python identifiers). Normally, the parameter will be added as
- ``key="value"`` unless the value is ``None``, in which case only the key will be
- added.
+ msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
- Here's an example::
+ This will add a header that looks like ::
- msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
+ Content-Disposition: attachment; filename="bud.gif"
- This will add a header that looks like ::
- Content-Disposition: attachment; filename="bud.gif"
+ .. method:: replace_header(_name, _value)
+ Replace a header. Replace the first header found in the message that
+ matches *_name*, retaining header order and field name case. If no
+ matching header was found, a :exc:`KeyError` is raised.
-.. method:: Message.replace_header(_name, _value)
- Replace a header. Replace the first header found in the message that matches
- *_name*, retaining header order and field name case. If no matching header was
- found, a :exc:`KeyError` is raised.
+ .. method:: get_content_type()
+ Return the message's content type. The returned string is coerced to
+ lower case of the form :mimetype:`maintype/subtype`. If there was no
+ :mailheader:`Content-Type` header in the message the default type as given
+ by :meth:`get_default_type` will be returned. Since according to
+ :rfc:`2045`, messages always have a default type, :meth:`get_content_type`
+ will always return a value.
-.. method:: Message.get_content_type()
+ :rfc:`2045` defines a message's default type to be :mimetype:`text/plain`
+ unless it appears inside a :mimetype:`multipart/digest` container, in
+ which case it would be :mimetype:`message/rfc822`. If the
+ :mailheader:`Content-Type` header has an invalid type specification,
+ :rfc:`2045` mandates that the default type be :mimetype:`text/plain`.
- Return the message's content type. The returned string is coerced to lower case
- of the form :mimetype:`maintype/subtype`. If there was no
- :mailheader:`Content-Type` header in the message the default type as given by
- :meth:`get_default_type` will be returned. Since according to :rfc:`2045`,
- messages always have a default type, :meth:`get_content_type` will always return
- a value.
- :rfc:`2045` defines a message's default type to be :mimetype:`text/plain` unless
- it appears inside a :mimetype:`multipart/digest` container, in which case it
- would be :mimetype:`message/rfc822`. If the :mailheader:`Content-Type` header
- has an invalid type specification, :rfc:`2045` mandates that the default type be
- :mimetype:`text/plain`.
+ .. method:: get_content_maintype()
+ Return the message's main content type. This is the :mimetype:`maintype`
+ part of the string returned by :meth:`get_content_type`.
-.. method:: Message.get_content_maintype()
- Return the message's main content type. This is the :mimetype:`maintype` part
- of the string returned by :meth:`get_content_type`.
+ .. method:: get_content_subtype()
+ Return the message's sub-content type. This is the :mimetype:`subtype`
+ part of the string returned by :meth:`get_content_type`.
-.. method:: Message.get_content_subtype()
- Return the message's sub-content type. This is the :mimetype:`subtype` part of
- the string returned by :meth:`get_content_type`.
+ .. method:: get_default_type()
+ Return the default content type. Most messages have a default content
+ type of :mimetype:`text/plain`, except for messages that are subparts of
+ :mimetype:`multipart/digest` containers. Such subparts have a default
+ content type of :mimetype:`message/rfc822`.
-.. method:: Message.get_default_type()
- Return the default content type. Most messages have a default content type of
- :mimetype:`text/plain`, except for messages that are subparts of
- :mimetype:`multipart/digest` containers. Such subparts have a default content
- type of :mimetype:`message/rfc822`.
+ .. method:: set_default_type(ctype)
+ Set the default content type. *ctype* should either be
+ :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is not
+ enforced. The default content type is not stored in the
+ :mailheader:`Content-Type` header.
-.. method:: Message.set_default_type(ctype)
- Set the default content type. *ctype* should either be :mimetype:`text/plain`
- or :mimetype:`message/rfc822`, although this is not enforced. The default
- content type is not stored in the :mailheader:`Content-Type` header.
+ .. method:: get_params([failobj[, header[, unquote]]])
+ Return the message's :mailheader:`Content-Type` parameters, as a list.
+ The elements of the returned list are 2-tuples of key/value pairs, as
+ split on the ``'='`` sign. The left hand side of the ``'='`` is the key,
+ while the right hand side is the value. If there is no ``'='`` sign in
+ the parameter the value is the empty string, otherwise the value is as
+ described in :meth:`get_param` and is unquoted if optional *unquote* is
+ ``True`` (the default).
-.. method:: Message.get_params([failobj[, header[, unquote]]])
+ Optional *failobj* is the object to return if there is no
+ :mailheader:`Content-Type` header. Optional *header* is the header to
+ search instead of :mailheader:`Content-Type`.
- Return the message's :mailheader:`Content-Type` parameters, as a list. The
- elements of the returned list are 2-tuples of key/value pairs, as split on the
- ``'='`` sign. The left hand side of the ``'='`` is the key, while the right
- hand side is the value. If there is no ``'='`` sign in the parameter the value
- is the empty string, otherwise the value is as described in :meth:`get_param`
- and is unquoted if optional *unquote* is ``True`` (the default).
- Optional *failobj* is the object to return if there is no
- :mailheader:`Content-Type` header. Optional *header* is the header to search
- instead of :mailheader:`Content-Type`.
+ .. method:: get_param(param[, failobj[, header[, unquote]]])
+ Return the value of the :mailheader:`Content-Type` header's parameter
+ *param* as a string. If the message has no :mailheader:`Content-Type`
+ header or if there is no such parameter, then *failobj* is returned
+ (defaults to ``None``).
-.. method:: Message.get_param(param[, failobj[, header[, unquote]]])
+ Optional *header* if given, specifies the message header to use instead of
+ :mailheader:`Content-Type`.
- Return the value of the :mailheader:`Content-Type` header's parameter *param* as
- a string. If the message has no :mailheader:`Content-Type` header or if there
- is no such parameter, then *failobj* is returned (defaults to ``None``).
+ Parameter keys are always compared case insensitively. The return value
+ can either be a string, or a 3-tuple if the parameter was :rfc:`2231`
+ encoded. When it's a 3-tuple, the elements of the value are of the form
+ ``(CHARSET, LANGUAGE, VALUE)``. Note that both ``CHARSET`` and
+ ``LANGUAGE`` can be ``None``, in which case you should consider ``VALUE``
+ to be encoded in the ``us-ascii`` charset. You can usually ignore
+ ``LANGUAGE``.
- Optional *header* if given, specifies the message header to use instead of
- :mailheader:`Content-Type`.
+ If your application doesn't care whether the parameter was encoded as in
+ :rfc:`2231`, you can collapse the parameter value by calling
+ :func:`email.Utils.collapse_rfc2231_value`, passing in the return value
+ from :meth:`get_param`. This will return a suitably decoded Unicode
+ string whn the value is a tuple, or the original string unquoted if it
+ isn't. For example::
- Parameter keys are always compared case insensitively. The return value can
- either be a string, or a 3-tuple if the parameter was :rfc:`2231` encoded. When
- it's a 3-tuple, the elements of the value are of the form ``(CHARSET, LANGUAGE,
- VALUE)``. Note that both ``CHARSET`` and ``LANGUAGE`` can be ``None``, in which
- case you should consider ``VALUE`` to be encoded in the ``us-ascii`` charset.
- You can usually ignore ``LANGUAGE``.
+ rawparam = msg.get_param('foo')
+ param = email.Utils.collapse_rfc2231_value(rawparam)
- If your application doesn't care whether the parameter was encoded as in
- :rfc:`2231`, you can collapse the parameter value by calling
- :func:`email.Utils.collapse_rfc2231_value`, passing in the return value from
- :meth:`get_param`. This will return a suitably decoded Unicode string whn the
- value is a tuple, or the original string unquoted if it isn't. For example::
+ In any case, the parameter value (either the returned string, or the
+ ``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set
+ to ``False``.
- rawparam = msg.get_param('foo')
- param = email.Utils.collapse_rfc2231_value(rawparam)
- In any case, the parameter value (either the returned string, or the ``VALUE``
- item in the 3-tuple) is always unquoted, unless *unquote* is set to ``False``.
+ .. method:: set_param(param, value[, header[, requote[, charset[, language]]]])
+ Set a parameter in the :mailheader:`Content-Type` header. If the
+ parameter already exists in the header, its value will be replaced with
+ *value*. If the :mailheader:`Content-Type` header as not yet been defined
+ for this message, it will be set to :mimetype:`text/plain` and the new
+ parameter value will be appended as per :rfc:`2045`.
-.. method:: Message.set_param(param, value[, header[, requote[, charset[, language]]]])
+ Optional *header* specifies an alternative header to
+ :mailheader:`Content-Type`, and all parameters will be quoted as necessary
+ unless optional *requote* is ``False`` (the default is ``True``).
- Set a parameter in the :mailheader:`Content-Type` header. If the parameter
- already exists in the header, its value will be replaced with *value*. If the
- :mailheader:`Content-Type` header as not yet been defined for this message, it
- will be set to :mimetype:`text/plain` and the new parameter value will be
- appended as per :rfc:`2045`.
+ If optional *charset* is specified, the parameter will be encoded
+ according to :rfc:`2231`. Optional *language* specifies the RFC 2231
+ language, defaulting to the empty string. Both *charset* and *language*
+ should be strings.
- Optional *header* specifies an alternative header to :mailheader:`Content-Type`,
- and all parameters will be quoted as necessary unless optional *requote* is
- ``False`` (the default is ``True``).
- If optional *charset* is specified, the parameter will be encoded according to
- :rfc:`2231`. Optional *language* specifies the RFC 2231 language, defaulting to
- the empty string. Both *charset* and *language* should be strings.
+ .. method:: del_param(param[, header[, requote]])
+ Remove the given parameter completely from the :mailheader:`Content-Type`
+ header. The header will be re-written in place without the parameter or
+ its value. All values will be quoted as necessary unless *requote* is
+ ``False`` (the default is ``True``). Optional *header* specifies an
+ alternative to :mailheader:`Content-Type`.
-.. method:: Message.del_param(param[, header[, requote]])
- Remove the given parameter completely from the :mailheader:`Content-Type`
- header. The header will be re-written in place without the parameter or its
- value. All values will be quoted as necessary unless *requote* is ``False``
- (the default is ``True``). Optional *header* specifies an alternative to
- :mailheader:`Content-Type`.
+ .. method:: set_type(type[, header][, requote])
+ Set the main type and subtype for the :mailheader:`Content-Type`
+ header. *type* must be a string in the form :mimetype:`maintype/subtype`,
+ otherwise a :exc:`ValueError` is raised.
-.. method:: Message.set_type(type[, header][, requote])
+ This method replaces the :mailheader:`Content-Type` header, keeping all
+ the parameters in place. If *requote* is ``False``, this leaves the
+ existing header's quoting as is, otherwise the parameters will be quoted
+ (the default).
- Set the main type and subtype for the :mailheader:`Content-Type` header. *type*
- must be a string in the form :mimetype:`maintype/subtype`, otherwise a
- :exc:`ValueError` is raised.
+ An alternative header can be specified in the *header* argument. When the
+ :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version`
+ header is also added.
- This method replaces the :mailheader:`Content-Type` header, keeping all the
- parameters in place. If *requote* is ``False``, this leaves the existing
- header's quoting as is, otherwise the parameters will be quoted (the default).
- An alternative header can be specified in the *header* argument. When the
- :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version` header is
- also added.
+ .. method:: get_filename([failobj])
+ Return the value of the ``filename`` parameter of the
+ :mailheader:`Content-Disposition` header of the message. If the header
+ does not have a ``filename`` parameter, this method falls back to looking
+ for the ``name`` parameter. If neither is found, or the header is
+ missing, then *failobj* is returned. The returned string will always be
+ unquoted as per :meth:`Utils.unquote`.
-.. method:: Message.get_filename([failobj])
- Return the value of the ``filename`` parameter of the
- :mailheader:`Content-Disposition` header of the message. If the header does not
- have a ``filename`` parameter, this method falls back to looking for the
- ``name`` parameter. If neither is found, or the header is missing, then
- *failobj* is returned. The returned string will always be unquoted as per
- :meth:`Utils.unquote`.
+ .. method:: get_boundary([failobj])
+ Return the value of the ``boundary`` parameter of the
+ :mailheader:`Content-Type` header of the message, or *failobj* if either
+ the header is missing, or has no ``boundary`` parameter. The returned
+ string will always be unquoted as per :meth:`Utils.unquote`.
-.. method:: Message.get_boundary([failobj])
- Return the value of the ``boundary`` parameter of the :mailheader:`Content-Type`
- header of the message, or *failobj* if either the header is missing, or has no
- ``boundary`` parameter. The returned string will always be unquoted as per
- :meth:`Utils.unquote`.
+ .. method:: set_boundary(boundary)
+ Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
+ *boundary*. :meth:`set_boundary` will always quote *boundary* if
+ necessary. A :exc:`HeaderParseError` is raised if the message object has
+ no :mailheader:`Content-Type` header.
-.. method:: Message.set_boundary(boundary)
+ Note that using this method is subtly different than deleting the old
+ :mailheader:`Content-Type` header and adding a new one with the new
+ boundary via :meth:`add_header`, because :meth:`set_boundary` preserves
+ the order of the :mailheader:`Content-Type` header in the list of
+ headers. However, it does *not* preserve any continuation lines which may
+ have been present in the original :mailheader:`Content-Type` header.
- Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
- *boundary*. :meth:`set_boundary` will always quote *boundary* if necessary. A
- :exc:`HeaderParseError` is raised if the message object has no
- :mailheader:`Content-Type` header.
- Note that using this method is subtly different than deleting the old
- :mailheader:`Content-Type` header and adding a new one with the new boundary via
- :meth:`add_header`, because :meth:`set_boundary` preserves the order of the
- :mailheader:`Content-Type` header in the list of headers. However, it does *not*
- preserve any continuation lines which may have been present in the original
- :mailheader:`Content-Type` header.
+ .. method:: get_content_charset([failobj])
+ Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
+ coerced to lower case. If there is no :mailheader:`Content-Type` header, or if
+ that header has no ``charset`` parameter, *failobj* is returned.
-.. method:: Message.get_content_charset([failobj])
+ Note that this method differs from :meth:`get_charset` which returns the
+ :class:`Charset` instance for the default encoding of the message body.
- Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
- coerced to lower case. If there is no :mailheader:`Content-Type` header, or if
- that header has no ``charset`` parameter, *failobj* is returned.
- Note that this method differs from :meth:`get_charset` which returns the
- :class:`Charset` instance for the default encoding of the message body.
+ .. method:: get_charsets([failobj])
+ Return a list containing the character set names in the message. If the
+ message is a :mimetype:`multipart`, then the list will contain one element
+ for each subpart in the payload, otherwise, it will be a list of length 1.
-.. method:: Message.get_charsets([failobj])
+ Each item in the list will be a string which is the value of the
+ ``charset`` parameter in the :mailheader:`Content-Type` header for the
+ represented subpart. However, if the subpart has no
+ :mailheader:`Content-Type` header, no ``charset`` parameter, or is not of
+ the :mimetype:`text` main MIME type, then that item in the returned list
+ will be *failobj*.
- Return a list containing the character set names in the message. If the message
- is a :mimetype:`multipart`, then the list will contain one element for each
- subpart in the payload, otherwise, it will be a list of length 1.
- Each item in the list will be a string which is the value of the ``charset``
- parameter in the :mailheader:`Content-Type` header for the represented subpart.
- However, if the subpart has no :mailheader:`Content-Type` header, no ``charset``
- parameter, or is not of the :mimetype:`text` main MIME type, then that item in
- the returned list will be *failobj*.
+ .. method:: walk()
+ The :meth:`walk` method is an all-purpose generator which can be used to
+ iterate over all the parts and subparts of a message object tree, in
+ depth-first traversal order. You will typically use :meth:`walk` as the
+ iterator in a ``for`` loop; each iteration returns the next subpart.
-.. method:: Message.walk()
+ Here's an example that prints the MIME type of every part of a multipart
+ message structure::
- The :meth:`walk` method is an all-purpose generator which can be used to iterate
- over all the parts and subparts of a message object tree, in depth-first
- traversal order. You will typically use :meth:`walk` as the iterator in a
- ``for`` loop; each iteration returns the next subpart.
+ >>> for part in msg.walk():
+ ... print(part.get_content_type())
+ multipart/report
+ text/plain
+ message/delivery-status
+ text/plain
+ text/plain
+ message/rfc822
- Here's an example that prints the MIME type of every part of a multipart message
- structure::
+ :class:`Message` objects can also optionally contain two instance attributes,
+ which can be used when generating the plain text of a MIME message.
- >>> for part in msg.walk():
- ... print(part.get_content_type())
- multipart/report
- text/plain
- message/delivery-status
- text/plain
- text/plain
- message/rfc822
-:class:`Message` objects can also optionally contain two instance attributes,
-which can be used when generating the plain text of a MIME message.
+ .. attribute:: preamble
+ The format of a MIME document allows for some text between the blank line
+ following the headers, and the first multipart boundary string. Normally,
+ this text is never visible in a MIME-aware mail reader because it falls
+ outside the standard MIME armor. However, when viewing the raw text of
+ the message, or when viewing the message in a non-MIME aware reader, this
+ text can become visible.
-.. data:: preamble
+ The *preamble* attribute contains this leading extra-armor text for MIME
+ documents. When the :class:`Parser` discovers some text after the headers
+ but before the first boundary string, it assigns this text to the
+ message's *preamble* attribute. When the :class:`Generator` is writing
+ out the plain text representation of a MIME message, and it finds the
+ message has a *preamble* attribute, it will write this text in the area
+ between the headers and the first boundary. See :mod:`email.parser` and
+ :mod:`email.generator` for details.
- The format of a MIME document allows for some text between the blank line
- following the headers, and the first multipart boundary string. Normally, this
- text is never visible in a MIME-aware mail reader because it falls outside the
- standard MIME armor. However, when viewing the raw text of the message, or when
- viewing the message in a non-MIME aware reader, this text can become visible.
+ Note that if the message object has no preamble, the *preamble* attribute
+ will be ``None``.
- The *preamble* attribute contains this leading extra-armor text for MIME
- documents. When the :class:`Parser` discovers some text after the headers but
- before the first boundary string, it assigns this text to the message's
- *preamble* attribute. When the :class:`Generator` is writing out the plain text
- representation of a MIME message, and it finds the message has a *preamble*
- attribute, it will write this text in the area between the headers and the first
- boundary. See :mod:`email.parser` and :mod:`email.generator` for details.
- Note that if the message object has no preamble, the *preamble* attribute will
- be ``None``.
+ .. attribute:: epilogue
+ The *epilogue* attribute acts the same way as the *preamble* attribute,
+ except that it contains text that appears between the last boundary and
+ the end of the message.
-.. data:: epilogue
+ You do not need to set the epilogue to the empty string in order for the
+ :class:`Generator` to print a newline at the end of the file.
- The *epilogue* attribute acts the same way as the *preamble* attribute, except
- that it contains text that appears between the last boundary and the end of the
- message.
- You do not need to set the epilogue to the empty string in order for the
- :class:`Generator` to print a newline at the end of the file.
+ .. attribute:: defects
-
-.. data:: defects
-
- The *defects* attribute contains a list of all the problems found when parsing
- this message. See :mod:`email.errors` for a detailed description of the
- possible parsing defects.
+ The *defects* attribute contains a list of all the problems found when
+ parsing this message. See :mod:`email.errors` for a detailed description
+ of the possible parsing defects.
Modified: python/branches/py3k/Doc/library/email.parser.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.parser.rst (original)
+++ python/branches/py3k/Doc/library/email.parser.rst Fri Apr 25 03:59:09 2008
@@ -65,20 +65,21 @@
defaults to the :class:`email.message.Message` class.
-.. method:: FeedParser.feed(data)
+ .. method:: feed(data)
- Feed the :class:`FeedParser` some more data. *data* should be a string
- containing one or more lines. The lines can be partial and the
- :class:`FeedParser` will stitch such partial lines together properly. The lines
- in the string can have any of the common three line endings, carriage return,
- newline, or carriage return and newline (they can even be mixed).
+ Feed the :class:`FeedParser` some more data. *data* should be a string
+ containing one or more lines. The lines can be partial and the
+ :class:`FeedParser` will stitch such partial lines together properly. The
+ lines in the string can have any of the common three line endings,
+ carriage return, newline, or carriage return and newline (they can even be
+ mixed).
-.. method:: FeedParser.close()
+ .. method:: close()
- Closing a :class:`FeedParser` completes the parsing of all previously fed data,
- and returns the root message object. It is undefined what happens if you feed
- more data to a closed :class:`FeedParser`.
+ Closing a :class:`FeedParser` completes the parsing of all previously fed
+ data, and returns the root message object. It is undefined what happens
+ if you feed more data to a closed :class:`FeedParser`.
Parser class API
@@ -111,33 +112,33 @@
effectively non-strict. You should simply stop passing a *strict* flag to
the :class:`Parser` constructor.
-The other public :class:`Parser` methods are:
+ The other public :class:`Parser` methods are:
-.. method:: Parser.parse(fp[, headersonly])
+ .. method:: parse(fp[, headersonly])
- Read all the data from the file-like object *fp*, parse the resulting text, and
- return the root message object. *fp* must support both the :meth:`readline` and
- the :meth:`read` methods on file-like objects.
+ Read all the data from the file-like object *fp*, parse the resulting
+ text, and return the root message object. *fp* must support both the
+ :meth:`readline` and the :meth:`read` methods on file-like objects.
- The text contained in *fp* must be formatted as a block of :rfc:`2822` style
- headers and header continuation lines, optionally preceded by a envelope
- header. The header block is terminated either by the end of the data or by a
- blank line. Following the header block is the body of the message (which may
- contain MIME-encoded subparts).
+ The text contained in *fp* must be formatted as a block of :rfc:`2822`
+ style headers and header continuation lines, optionally preceded by a
+ envelope header. The header block is terminated either by the end of the
+ data or by a blank line. Following the header block is the body of the
+ message (which may contain MIME-encoded subparts).
- Optional *headersonly* is as with the :meth:`parse` method.
+ Optional *headersonly* is as with the :meth:`parse` method.
+ .. method:: parsestr(text[, headersonly])
-.. method:: Parser.parsestr(text[, headersonly])
+ Similar to the :meth:`parse` method, except it takes a string object
+ instead of a file-like object. Calling this method on a string is exactly
+ equivalent to wrapping *text* in a :class:`StringIO` instance first and
+ calling :meth:`parse`.
- Similar to the :meth:`parse` method, except it takes a string object instead of
- a file-like object. Calling this method on a string is exactly equivalent to
- wrapping *text* in a :class:`StringIO` instance first and calling :meth:`parse`.
-
- Optional *headersonly* is a flag specifying whether to stop parsing after
- reading the headers or not. The default is ``False``, meaning it parses the
- entire contents of the file.
+ Optional *headersonly* is a flag specifying whether to stop parsing after
+ reading the headers or not. The default is ``False``, meaning it parses
+ the entire contents of the file.
Since creating a message object structure from a string or a file object is such
Modified: python/branches/py3k/Doc/library/filecmp.rst
==============================================================================
--- python/branches/py3k/Doc/library/filecmp.rst (original)
+++ python/branches/py3k/Doc/library/filecmp.rst Fri Apr 25 03:59:09 2008
@@ -66,88 +66,91 @@
'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir,
os.pardir]``.
-The :class:`dircmp` class provides the following methods:
+ The :class:`dircmp` class provides the following methods:
-.. method:: dircmp.report()
+ .. method:: report()
- Print (to ``sys.stdout``) a comparison between *a* and *b*.
+ Print (to ``sys.stdout``) a comparison between *a* and *b*.
-.. method:: dircmp.report_partial_closure()
+ .. method:: report_partial_closure()
- Print a comparison between *a* and *b* and common immediate subdirectories.
+ Print a comparison between *a* and *b* and common immediate
+ subdirectories.
-.. method:: dircmp.report_full_closure()
+ .. method:: report_full_closure()
- Print a comparison between *a* and *b* and common subdirectories (recursively).
+ Print a comparison between *a* and *b* and common subdirectories
+ (recursively).
-The :class:`dircmp` offers a number of interesting attributes that may be used
-to get various bits of information about the directory trees being compared.
+ The :class:`dircmp` offers a number of interesting attributes that may be
+ used to get various bits of information about the directory trees being
+ compared.
-Note that via :meth:`__getattr__` hooks, all attributes are computed lazily, so
-there is no speed penalty if only those attributes which are lightweight to
-compute are used.
+ Note that via :meth:`__getattr__` hooks, all attributes are computed lazily,
+ so there is no speed penalty if only those attributes which are lightweight
+ to compute are used.
-.. attribute:: dircmp.left_list
+ .. attribute:: left_list
- Files and subdirectories in *a*, filtered by *hide* and *ignore*.
+ Files and subdirectories in *a*, filtered by *hide* and *ignore*.
-.. attribute:: dircmp.right_list
+ .. attribute:: right_list
- Files and subdirectories in *b*, filtered by *hide* and *ignore*.
+ Files and subdirectories in *b*, filtered by *hide* and *ignore*.
-.. attribute:: dircmp.common
+ .. attribute:: common
- Files and subdirectories in both *a* and *b*.
+ Files and subdirectories in both *a* and *b*.
-.. attribute:: dircmp.left_only
+ .. attribute:: left_only
- Files and subdirectories only in *a*.
+ Files and subdirectories only in *a*.
-.. attribute:: dircmp.right_only
+ .. attribute:: right_only
- Files and subdirectories only in *b*.
+ Files and subdirectories only in *b*.
-.. attribute:: dircmp.common_dirs
+ .. attribute:: common_dirs
- Subdirectories in both *a* and *b*.
+ Subdirectories in both *a* and *b*.
-.. attribute:: dircmp.common_files
+ .. attribute:: common_files
- Files in both *a* and *b*
+ Files in both *a* and *b*
-.. attribute:: dircmp.common_funny
+ .. attribute:: common_funny
- Names in both *a* and *b*, such that the type differs between the directories,
- or names for which :func:`os.stat` reports an error.
+ Names in both *a* and *b*, such that the type differs between the
+ directories, or names for which :func:`os.stat` reports an error.
-.. attribute:: dircmp.same_files
+ .. attribute:: same_files
- Files which are identical in both *a* and *b*.
+ Files which are identical in both *a* and *b*.
-.. attribute:: dircmp.diff_files
+ .. attribute:: diff_files
- Files which are in both *a* and *b*, whose contents differ.
+ Files which are in both *a* and *b*, whose contents differ.
-.. attribute:: dircmp.funny_files
+ .. attribute:: funny_files
- Files which are in both *a* and *b*, but could not be compared.
+ Files which are in both *a* and *b*, but could not be compared.
-.. attribute:: dircmp.subdirs
+ .. attribute:: subdirs
- A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.
+ A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.
Modified: python/branches/py3k/Doc/library/fractions.rst
==============================================================================
--- python/branches/py3k/Doc/library/fractions.rst (original)
+++ python/branches/py3k/Doc/library/fractions.rst Fri Apr 25 03:59:09 2008
@@ -30,60 +30,58 @@
:class:`numbers.Rational` and is immutable and hashable.
-.. method:: Fraction.from_float(flt)
+ .. method:: from_float(flt)
- This classmethod constructs a :class:`Fraction` representing the
- exact value of *flt*, which must be a :class:`float`. Beware that
- ``Fraction.from_float(0.3)`` is not the same value as ``Rational(3,
- 10)``
+ This classmethod constructs a :class:`Fraction` representing the exact
+ value of *flt*, which must be a :class:`float`. Beware that
+ ``Fraction.from_float(0.3)`` is not the same value as ``Rational(3, 10)``
-.. method:: Fraction.from_decimal(dec)
+ .. method:: from_decimal(dec)
- This classmethod constructs a :class:`Fraction` representing the
- exact value of *dec*, which must be a
- :class:`decimal.Decimal`.
+ This classmethod constructs a :class:`Fraction` representing the exact
+ value of *dec*, which must be a :class:`decimal.Decimal`.
-.. method:: Fraction.limit_denominator(max_denominator=1000000)
+ .. method:: limit_denominator(max_denominator=1000000)
- Finds and returns the closest :class:`Fraction` to ``self`` that
- has denominator at most max_denominator. This method is useful for
- finding rational approximations to a given floating-point number:
+ Finds and returns the closest :class:`Fraction` to ``self`` that has
+ denominator at most max_denominator. This method is useful for finding
+ rational approximations to a given floating-point number:
- >>> from fractions import Fraction
- >>> Fraction('3.1415926535897932').limit_denominator(1000)
- Fraction(355L, 113L)
+ >>> from fractions import Fraction
+ >>> Fraction('3.1415926535897932').limit_denominator(1000)
+ Fraction(355L, 113L)
- or for recovering a rational number that's represented as a float:
+ or for recovering a rational number that's represented as a float:
- >>> from math import pi, cos
- >>> Fraction.from_float(cos(pi/3))
- Fraction(4503599627370497L, 9007199254740992L)
- >>> Fraction.from_float(cos(pi/3)).limit_denominator()
- Fraction(1L, 2L)
+ >>> from math import pi, cos
+ >>> Fraction.from_float(cos(pi/3))
+ Fraction(4503599627370497L, 9007199254740992L)
+ >>> Fraction.from_float(cos(pi/3)).limit_denominator()
+ Fraction(1L, 2L)
-.. method:: Fraction.__floor__()
+ .. method:: __floor__()
- Returns the greatest :class:`int` ``<= self``. Will be accessible
- through :func:`math.floor` in Py3k.
+ Returns the greatest :class:`int` ``<= self``. Will be accessible through
+ :func:`math.floor` in Py3k.
-.. method:: Fraction.__ceil__()
+ .. method:: __ceil__()
- Returns the least :class:`int` ``>= self``. Will be accessible
- through :func:`math.ceil` in Py3k.
+ Returns the least :class:`int` ``>= self``. Will be accessible through
+ :func:`math.ceil` in Py3k.
-.. method:: Fraction.__round__()
- Fraction.__round__(ndigits)
+ .. method:: __round__()
+ __round__(ndigits)
- The first version returns the nearest :class:`int` to ``self``,
- rounding half to even. The second version rounds ``self`` to the
- nearest multiple of ``Fraction(1, 10**ndigits)`` (logically, if
- ``ndigits`` is negative), again rounding half toward even. Will be
- accessible through :func:`round` in Py3k.
+ The first version returns the nearest :class:`int` to ``self``, rounding
+ half to even. The second version rounds ``self`` to the nearest multiple
+ of ``Fraction(1, 10**ndigits)`` (logically, if ``ndigits`` is negative),
+ again rounding half toward even. Will be accessible through :func:`round`
+ in Py3k.
.. seealso::
Modified: python/branches/py3k/Doc/library/ftplib.rst
==============================================================================
--- python/branches/py3k/Doc/library/ftplib.rst (original)
+++ python/branches/py3k/Doc/library/ftplib.rst Fri Apr 25 03:59:09 2008
@@ -47,33 +47,34 @@
or passed as None, the global default timeout setting will be used).
-.. data:: all_errors
+ .. attribute:: all_errors
- The set of all exceptions (as a tuple) that methods of :class:`FTP` instances
- may raise as a result of problems with the FTP connection (as opposed to
- programming errors made by the caller). This set includes the four exceptions
- listed below as well as :exc:`socket.error` and :exc:`IOError`.
+ The set of all exceptions (as a tuple) that methods of :class:`FTP`
+ instances may raise as a result of problems with the FTP connection (as
+ opposed to programming errors made by the caller). This set includes the
+ four exceptions listed below as well as :exc:`socket.error` and
+ :exc:`IOError`.
-.. exception:: error_reply
+ .. exception:: error_reply
- Exception raised when an unexpected reply is received from the server.
+ Exception raised when an unexpected reply is received from the server.
-.. exception:: error_temp
+ .. exception:: error_temp
- Exception raised when an error code in the range 400--499 is received.
+ Exception raised when an error code in the range 400--499 is received.
-.. exception:: error_perm
+ .. exception:: error_perm
- Exception raised when an error code in the range 500--599 is received.
+ Exception raised when an error code in the range 500--599 is received.
-.. exception:: error_proto
+ .. exception:: error_proto
- Exception raised when a reply is received from the server that does not begin
- with a digit in the range 1--5.
+ Exception raised when a reply is received from the server that does not
+ begin with a digit in the range 1--5.
.. seealso::
Modified: python/branches/py3k/Doc/library/gettext.rst
==============================================================================
--- python/branches/py3k/Doc/library/gettext.rst (original)
+++ python/branches/py3k/Doc/library/gettext.rst Fri Apr 25 03:59:09 2008
@@ -218,7 +218,7 @@
are the methods of :class:`NullTranslations`:
-.. method:: NullTranslations.__init__([fp])
+.. class:: NullTranslations([fp])
Takes an optional file object *fp*, which is ignored by the base class.
Initializes "protected" instance variables *_info* and *_charset* which are set
@@ -227,105 +227,107 @@
``None``.
-.. method:: NullTranslations._parse(fp)
+ .. method:: _parse(fp)
- No-op'd in the base class, this method takes file object *fp*, and reads the
- data from the file, initializing its message catalog. If you have an
- unsupported message catalog file format, you should override this method to
- parse your format.
+ No-op'd in the base class, this method takes file object *fp*, and reads
+ the data from the file, initializing its message catalog. If you have an
+ unsupported message catalog file format, you should override this method
+ to parse your format.
-.. method:: NullTranslations.add_fallback(fallback)
+ .. method:: add_fallback(fallback)
- Add *fallback* as the fallback object for the current translation object. A
- translation object should consult the fallback if it cannot provide a
- translation for a given message.
+ Add *fallback* as the fallback object for the current translation
+ object. A translation object should consult the fallback if it cannot provide a
+ translation for a given message.
-.. method:: NullTranslations.gettext(message)
+ .. method:: gettext(message)
- If a fallback has been set, forward :meth:`gettext` to the fallback. Otherwise,
- return the translated message. Overridden in derived classes.
+ If a fallback has been set, forward :meth:`gettext` to the
+ fallback. Otherwise, return the translated message. Overridden in derived
+ classes.
-.. method:: NullTranslations.lgettext(message)
+ .. method:: lgettext(message)
- If a fallback has been set, forward :meth:`lgettext` to the fallback. Otherwise,
- return the translated message. Overridden in derived classes.
+ If a fallback has been set, forward :meth:`lgettext` to the
+ fallback. Otherwise, return the translated message. Overridden in derived
+ classes.
+ .. method:: ugettext(message)
-.. method:: NullTranslations.ugettext(message)
+ If a fallback has been set, forward :meth:`ugettext` to the
+ fallback. Otherwise, return the translated message as a string. Overridden
+ in derived classes.
- If a fallback has been set, forward :meth:`ugettext` to the fallback. Otherwise,
- return the translated message as a string. Overridden in derived classes.
+ .. method:: ngettext(singular, plural, n)
-.. method:: NullTranslations.ngettext(singular, plural, n)
+ If a fallback has been set, forward :meth:`ngettext` to the
+ fallback. Otherwise, return the translated message. Overridden in derived
+ classes.
- If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise,
- return the translated message. Overridden in derived classes.
+ .. method:: lngettext(singular, plural, n)
+ If a fallback has been set, forward :meth:`ngettext` to the
+ fallback. Otherwise, return the translated message. Overridden in derived
+ classes.
-.. method:: NullTranslations.lngettext(singular, plural, n)
+ .. method:: ungettext(singular, plural, n)
- If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise,
- return the translated message. Overridden in derived classes.
+ If a fallback has been set, forward :meth:`ungettext` to the fallback.
+ Otherwise, return the translated message as a string. Overridden in
+ derived classes.
+ .. method:: info()
-.. method:: NullTranslations.ungettext(singular, plural, n)
+ Return the "protected" :attr:`_info` variable.
- If a fallback has been set, forward :meth:`ungettext` to the fallback.
- Otherwise, return the translated message as a string. Overridden in
- derived classes.
+ .. method:: charset()
-.. method:: NullTranslations.info()
+ Return the "protected" :attr:`_charset` variable.
- Return the "protected" :attr:`_info` variable.
+ .. method:: output_charset()
-.. method:: NullTranslations.charset()
+ Return the "protected" :attr:`_output_charset` variable, which defines the
+ encoding used to return translated messages.
- Return the "protected" :attr:`_charset` variable.
+ .. method:: set_output_charset(charset)
-.. method:: NullTranslations.output_charset()
+ Change the "protected" :attr:`_output_charset` variable, which defines the
+ encoding used to return translated messages.
- Return the "protected" :attr:`_output_charset` variable, which defines the
- encoding used to return translated messages.
+ .. method:: install([unicode [, names]])
-.. method:: NullTranslations.set_output_charset(charset)
+ If the *unicode* flag is false, this method installs :meth:`self.gettext`
+ into the built-in namespace, binding it to ``_``. If *unicode* is true,
+ it binds :meth:`self.ugettext` instead. By default, *unicode* is false.
- Change the "protected" :attr:`_output_charset` variable, which defines the
- encoding used to return translated messages.
+ If the *names* parameter is given, it must be a sequence containing the
+ names of functions you want to install in the builtin namespace in
+ addition to :func:`_`. Supported names are ``'gettext'`` (bound to
+ :meth:`self.gettext` or :meth:`self.ugettext` according to the *unicode*
+ flag), ``'ngettext'`` (bound to :meth:`self.ngettext` or
+ :meth:`self.ungettext` according to the *unicode* flag), ``'lgettext'``
+ and ``'lngettext'``.
+ Note that this is only one way, albeit the most convenient way, to make
+ the :func:`_` function available to your application. Because it affects
+ the entire application globally, and specifically the built-in namespace,
+ localized modules should never install :func:`_`. Instead, they should use
+ this code to make :func:`_` available to their module::
-.. method:: NullTranslations.install([unicode [, names]])
+ import gettext
+ t = gettext.translation('mymodule', ...)
+ _ = t.gettext
- If the *unicode* flag is false, this method installs :meth:`self.gettext` into
- the built-in namespace, binding it to ``_``. If *unicode* is true, it binds
- :meth:`self.ugettext` instead. By default, *unicode* is false.
-
- If the *names* parameter is given, it must be a sequence containing the names of
- functions you want to install in the builtin namespace in addition to :func:`_`.
- Supported names are ``'gettext'`` (bound to :meth:`self.gettext` or
- :meth:`self.ugettext` according to the *unicode* flag), ``'ngettext'`` (bound to
- :meth:`self.ngettext` or :meth:`self.ungettext` according to the *unicode*
- flag), ``'lgettext'`` and ``'lngettext'``.
-
- Note that this is only one way, albeit the most convenient way, to make the
- :func:`_` function available to your application. Because it affects the entire
- application globally, and specifically the built-in namespace, localized modules
- should never install :func:`_`. Instead, they should use this code to make
- :func:`_` available to their module::
-
- import gettext
- t = gettext.translation('mymodule', ...)
- _ = t.gettext
-
- This puts :func:`_` only in the module's global namespace and so only affects
- calls within this module.
+ This puts :func:`_` only in the module's global namespace and so only
+ affects calls within this module.
The :class:`GNUTranslations` class
Modified: python/branches/py3k/Doc/library/logging.rst
==============================================================================
--- python/branches/py3k/Doc/library/logging.rst (original)
+++ python/branches/py3k/Doc/library/logging.rst Fri Apr 25 03:59:09 2008
@@ -1491,19 +1491,19 @@
will be used.
-.. method:: StreamHandler.emit(record)
+ .. method:: emit(record)
- If a formatter is specified, it is used to format the record. The record is then
- written to the stream with a trailing newline. If exception information is
- present, it is formatted using :func:`traceback.print_exception` and appended to
- the stream.
+ If a formatter is specified, it is used to format the record. The record
+ is then written to the stream with a trailing newline. If exception
+ information is present, it is formatted using
+ :func:`traceback.print_exception` and appended to the stream.
-.. method:: StreamHandler.flush()
+ .. method:: flush()
- Flushes the stream by calling its :meth:`flush` method. Note that the
- :meth:`close` method is inherited from :class:`Handler` and so does nothing, so
- an explicit :meth:`flush` call may be needed at times.
+ Flushes the stream by calling its :meth:`flush` method. Note that the
+ :meth:`close` method is inherited from :class:`Handler` and so does
+ nothing, so an explicit :meth:`flush` call may be needed at times.
FileHandler
@@ -1523,14 +1523,14 @@
first call to :meth:`emit`. By default, the file grows indefinitely.
-.. method:: FileHandler.close()
+ .. method:: close()
- Closes the file.
+ Closes the file.
-.. method:: FileHandler.emit(record)
+ .. method:: emit(record)
- Outputs the record to the file.
+ Outputs the record to the file.
WatchedFileHandler
@@ -1563,11 +1563,11 @@
first call to :meth:`emit`. By default, the file grows indefinitely.
-.. method:: WatchedFileHandler.emit(record)
+ .. method:: emit(record)
- Outputs the record to the file, but first checks to see if the file has changed.
- If it has, the existing stream is flushed and closed and the file opened again,
- before outputting the record to the file.
+ Outputs the record to the file, but first checks to see if the file has
+ changed. If it has, the existing stream is flushed and closed and the
+ file opened again, before outputting the record to the file.
RotatingFileHandler
@@ -1599,14 +1599,15 @@
:file:`app.log.2`, :file:`app.log.3` etc. respectively.
-.. method:: RotatingFileHandler.doRollover()
+ .. method:: doRollover()
- Does a rollover, as described above.
+ Does a rollover, as described above.
-.. method:: RotatingFileHandler.emit(record)
+ .. method:: emit(record)
- Outputs the record to the file, catering for rollover as described previously.
+ Outputs the record to the file, catering for rollover as described
+ previously.
TimedRotatingFileHandler
@@ -1652,14 +1653,14 @@
files to delete, so changing the interval may leave old files lying around.
-.. method:: TimedRotatingFileHandler.doRollover()
+ .. method:: doRollover()
- Does a rollover, as described above.
+ Does a rollover, as described above.
-.. method:: TimedRotatingFileHandler.emit(record)
+ .. method:: emit(record)
- Outputs the record to the file, catering for rollover as described above.
+ Outputs the record to the file, catering for rollover as described above.
SocketHandler
@@ -1675,43 +1676,44 @@
communicate with a remote machine whose address is given by *host* and *port*.
-.. method:: SocketHandler.close()
+ .. method:: close()
- Closes the socket.
+ Closes the socket.
-.. method:: SocketHandler.emit()
+ .. method:: emit()
- Pickles the record's attribute dictionary and writes it to the socket in binary
- format. If there is an error with the socket, silently drops the packet. If the
- connection was previously lost, re-establishes the connection. To unpickle the
- record at the receiving end into a :class:`LogRecord`, use the
- :func:`makeLogRecord` function.
+ Pickles the record's attribute dictionary and writes it to the socket in
+ binary format. If there is an error with the socket, silently drops the
+ packet. If the connection was previously lost, re-establishes the
+ connection. To unpickle the record at the receiving end into a
+ :class:`LogRecord`, use the :func:`makeLogRecord` function.
-.. method:: SocketHandler.handleError()
+ .. method:: handleError()
- Handles an error which has occurred during :meth:`emit`. The most likely cause
- is a lost connection. Closes the socket so that we can retry on the next event.
+ Handles an error which has occurred during :meth:`emit`. The most likely
+ cause is a lost connection. Closes the socket so that we can retry on the
+ next event.
-.. method:: SocketHandler.makeSocket()
+ .. method:: makeSocket()
- This is a factory method which allows subclasses to define the precise type of
- socket they want. The default implementation creates a TCP socket
- (:const:`socket.SOCK_STREAM`).
+ This is a factory method which allows subclasses to define the precise
+ type of socket they want. The default implementation creates a TCP socket
+ (:const:`socket.SOCK_STREAM`).
-.. method:: SocketHandler.makePickle(record)
+ .. method:: makePickle(record)
- Pickles the record's attribute dictionary in binary format with a length prefix,
- and returns it ready for transmission across the socket.
+ Pickles the record's attribute dictionary in binary format with a length
+ prefix, and returns it ready for transmission across the socket.
-.. method:: SocketHandler.send(packet)
+ .. method:: send(packet)
- Send a pickled string *packet* to the socket. This function allows for partial
- sends which can happen when the network is busy.
+ Send a pickled string *packet* to the socket. This function allows for
+ partial sends which can happen when the network is busy.
DatagramHandler
@@ -1728,23 +1730,23 @@
communicate with a remote machine whose address is given by *host* and *port*.
-.. method:: DatagramHandler.emit()
+ .. method:: emit()
- Pickles the record's attribute dictionary and writes it to the socket in binary
- format. If there is an error with the socket, silently drops the packet. To
- unpickle the record at the receiving end into a :class:`LogRecord`, use the
- :func:`makeLogRecord` function.
+ Pickles the record's attribute dictionary and writes it to the socket in
+ binary format. If there is an error with the socket, silently drops the
+ packet. To unpickle the record at the receiving end into a
+ :class:`LogRecord`, use the :func:`makeLogRecord` function.
-.. method:: DatagramHandler.makeSocket()
+ .. method:: makeSocket()
- The factory method of :class:`SocketHandler` is here overridden to create a UDP
- socket (:const:`socket.SOCK_DGRAM`).
+ The factory method of :class:`SocketHandler` is here overridden to create
+ a UDP socket (:const:`socket.SOCK_DGRAM`).
-.. method:: DatagramHandler.send(s)
+ .. method:: send(s)
- Send a pickled string to a socket.
+ Send a pickled string to a socket.
SysLogHandler
@@ -1766,22 +1768,22 @@
:const:`LOG_USER` is used.
-.. method:: SysLogHandler.close()
+ .. method:: close()
- Closes the socket to the remote host.
+ Closes the socket to the remote host.
-.. method:: SysLogHandler.emit(record)
+ .. method:: emit(record)
- The record is formatted, and then sent to the syslog server. If exception
- information is present, it is *not* sent to the server.
+ The record is formatted, and then sent to the syslog server. If exception
+ information is present, it is *not* sent to the server.
-.. method:: SysLogHandler.encodePriority(facility, priority)
+ .. method:: encodePriority(facility, priority)
- Encodes the facility and priority into an integer. You can pass in strings or
- integers - if strings are passed, internal mapping dictionaries are used to
- convert them to integers.
+ Encodes the facility and priority into an integer. You can pass in strings
+ or integers - if strings are passed, internal mapping dictionaries are
+ used to convert them to integers.
NTEventLogHandler
@@ -1809,45 +1811,45 @@
defaults to ``'Application'``.
-.. method:: NTEventLogHandler.close()
+ .. method:: close()
- At this point, you can remove the application name from the registry as a source
- of event log entries. However, if you do this, you will not be able to see the
- events as you intended in the Event Log Viewer - it needs to be able to access
- the registry to get the .dll name. The current version does not do this (in fact
- it doesn't do anything).
+ At this point, you can remove the application name from the registry as a
+ source of event log entries. However, if you do this, you will not be able
+ to see the events as you intended in the Event Log Viewer - it needs to be
+ able to access the registry to get the .dll name. The current version does
+ not do this (in fact it doesn't do anything).
-.. method:: NTEventLogHandler.emit(record)
+ .. method:: emit(record)
- Determines the message ID, event category and event type, and then logs the
- message in the NT event log.
+ Determines the message ID, event category and event type, and then logs
+ the message in the NT event log.
-.. method:: NTEventLogHandler.getEventCategory(record)
+ .. method:: getEventCategory(record)
- Returns the event category for the record. Override this if you want to specify
- your own categories. This version returns 0.
+ Returns the event category for the record. Override this if you want to
+ specify your own categories. This version returns 0.
-.. method:: NTEventLogHandler.getEventType(record)
+ .. method:: getEventType(record)
- Returns the event type for the record. Override this if you want to specify your
- own types. This version does a mapping using the handler's typemap attribute,
- which is set up in :meth:`__init__` to a dictionary which contains mappings for
- :const:`DEBUG`, :const:`INFO`, :const:`WARNING`, :const:`ERROR` and
- :const:`CRITICAL`. If you are using your own levels, you will either need to
- override this method or place a suitable dictionary in the handler's *typemap*
- attribute.
+ Returns the event type for the record. Override this if you want to
+ specify your own types. This version does a mapping using the handler's
+ typemap attribute, which is set up in :meth:`__init__` to a dictionary
+ which contains mappings for :const:`DEBUG`, :const:`INFO`,
+ :const:`WARNING`, :const:`ERROR` and :const:`CRITICAL`. If you are using
+ your own levels, you will either need to override this method or place a
+ suitable dictionary in the handler's *typemap* attribute.
-.. method:: NTEventLogHandler.getMessageID(record)
+ .. method:: getMessageID(record)
- Returns the message ID for the record. If you are using your own messages, you
- could do this by having the *msg* passed to the logger being an ID rather than a
- format string. Then, in here, you could use a dictionary lookup to get the
- message ID. This version returns 1, which is the base message ID in
- :file:`win32service.pyd`.
+ Returns the message ID for the record. If you are using your own messages,
+ you could do this by having the *msg* passed to the logger being an ID
+ rather than a format string. Then, in here, you could use a dictionary
+ lookup to get the message ID. This version returns 1, which is the base
+ message ID in :file:`win32service.pyd`.
SMTPHandler
@@ -1867,15 +1869,15 @@
can specify a (username, password) tuple for the *credentials* argument.
-.. method:: SMTPHandler.emit(record)
+ .. method:: emit(record)
- Formats the record and sends it to the specified addressees.
+ Formats the record and sends it to the specified addressees.
-.. method:: SMTPHandler.getSubject(record)
+ .. method:: getSubject(record)
- If you want to specify a subject line which is record-dependent, override this
- method.
+ If you want to specify a subject line which is record-dependent, override
+ this method.
MemoryHandler
@@ -1898,22 +1900,22 @@
Initializes the handler with a buffer of the specified capacity.
-.. method:: BufferingHandler.emit(record)
+ .. method:: emit(record)
- Appends the record to the buffer. If :meth:`shouldFlush` returns true, calls
- :meth:`flush` to process the buffer.
+ Appends the record to the buffer. If :meth:`shouldFlush` returns true,
+ calls :meth:`flush` to process the buffer.
-.. method:: BufferingHandler.flush()
+ .. method:: flush()
- You can override this to implement custom flushing behavior. This version just
- zaps the buffer to empty.
+ You can override this to implement custom flushing behavior. This version
+ just zaps the buffer to empty.
-.. method:: BufferingHandler.shouldFlush(record)
+ .. method:: shouldFlush(record)
- Returns true if the buffer is up to capacity. This method can be overridden to
- implement custom flushing strategies.
+ Returns true if the buffer is up to capacity. This method can be
+ overridden to implement custom flushing strategies.
.. class:: MemoryHandler(capacity[, flushLevel [, target]])
@@ -1924,25 +1926,27 @@
set using :meth:`setTarget` before this handler does anything useful.
-.. method:: MemoryHandler.close()
+ .. method:: close()
- Calls :meth:`flush`, sets the target to :const:`None` and clears the buffer.
+ Calls :meth:`flush`, sets the target to :const:`None` and clears the
+ buffer.
-.. method:: MemoryHandler.flush()
+ .. method:: flush()
- For a :class:`MemoryHandler`, flushing means just sending the buffered records
- to the target, if there is one. Override if you want different behavior.
+ For a :class:`MemoryHandler`, flushing means just sending the buffered
+ records to the target, if there is one. Override if you want different
+ behavior.
-.. method:: MemoryHandler.setTarget(target)
+ .. method:: setTarget(target)
- Sets the target handler for this handler.
+ Sets the target handler for this handler.
-.. method:: MemoryHandler.shouldFlush(record)
+ .. method:: shouldFlush(record)
- Checks for buffer full or a record at the *flushLevel* or higher.
+ Checks for buffer full or a record at the *flushLevel* or higher.
HTTPHandler
@@ -1961,9 +1965,9 @@
*method* is specified, ``GET`` is used.
-.. method:: HTTPHandler.emit(record)
+ .. method:: emit(record)
- Sends the record to the Web server as an URL-encoded dictionary.
+ Sends the record to the Web server as an URL-encoded dictionary.
.. _formatter-objects:
@@ -2048,38 +2052,42 @@
is used.
-.. method:: Formatter.format(record)
+ .. method:: format(record)
- The record's attribute dictionary is used as the operand to a string formatting
- operation. Returns the resulting string. Before formatting the dictionary, a
- couple of preparatory steps are carried out. The *message* attribute of the
- record is computed using *msg* % *args*. If the formatting string contains
- ``'(asctime)'``, :meth:`formatTime` is called to format the event time. If there
- is exception information, it is formatted using :meth:`formatException` and
- appended to the message. Note that the formatted exception information is cached
- in attribute *exc_text*. This is useful because the exception information can
- be pickled and sent across the wire, but you should be careful if you have more
- than one :class:`Formatter` subclass which customizes the formatting of exception
- information. In this case, you will have to clear the cached value after a
- formatter has done its formatting, so that the next formatter to handle the event
- doesn't use the cached value but recalculates it afresh.
-
-
-.. method:: Formatter.formatTime(record[, datefmt])
-
- This method should be called from :meth:`format` by a formatter which wants to
- make use of a formatted time. This method can be overridden in formatters to
- provide for any specific requirement, but the basic behavior is as follows: if
- *datefmt* (a string) is specified, it is used with :func:`time.strftime` to
- format the creation time of the record. Otherwise, the ISO8601 format is used.
- The resulting string is returned.
-
-
-.. method:: Formatter.formatException(exc_info)
-
- Formats the specified exception information (a standard exception tuple as
- returned by :func:`sys.exc_info`) as a string. This default implementation just
- uses :func:`traceback.print_exception`. The resulting string is returned.
+ The record's attribute dictionary is used as the operand to a string
+ formatting operation. Returns the resulting string. Before formatting the
+ dictionary, a couple of preparatory steps are carried out. The *message*
+ attribute of the record is computed using *msg* % *args*. If the
+ formatting string contains ``'(asctime)'``, :meth:`formatTime` is called
+ to format the event time. If there is exception information, it is
+ formatted using :meth:`formatException` and appended to the message. Note
+ that the formatted exception information is cached in attribute
+ *exc_text*. This is useful because the exception information can be
+ pickled and sent across the wire, but you should be careful if you have
+ more than one :class:`Formatter` subclass which customizes the formatting
+ of exception information. In this case, you will have to clear the cached
+ value after a formatter has done its formatting, so that the next
+ formatter to handle the event doesn't use the cached value but
+ recalculates it afresh.
+
+
+ .. method:: formatTime(record[, datefmt])
+
+ This method should be called from :meth:`format` by a formatter which
+ wants to make use of a formatted time. This method can be overridden in
+ formatters to provide for any specific requirement, but the basic behavior
+ is as follows: if *datefmt* (a string) is specified, it is used with
+ :func:`time.strftime` to format the creation time of the
+ record. Otherwise, the ISO8601 format is used. The resulting string is
+ returned.
+
+
+ .. method:: formatException(exc_info)
+
+ Formats the specified exception information (a standard exception tuple as
+ returned by :func:`sys.exc_info`) as a string. This default implementation
+ just uses :func:`traceback.print_exception`. The resulting string is
+ returned.
Filter Objects
@@ -2100,10 +2108,11 @@
through the filter. If no name is specified, allows every event.
-.. method:: Filter.filter(record)
+ .. method:: filter(record)
- Is the specified record to be logged? Returns zero for no, nonzero for yes. If
- deemed appropriate, the record may be modified in-place by this method.
+ Is the specified record to be logged? Returns zero for no, nonzero for
+ yes. If deemed appropriate, the record may be modified in-place by this
+ method.
LogRecord Objects
@@ -2131,10 +2140,11 @@
specified, it defaults to ``None``.
-.. method:: LogRecord.getMessage()
+ .. method:: getMessage()
+
+ Returns the message for this :class:`LogRecord` instance after merging any
+ user-supplied arguments with the message.
- Returns the message for this :class:`LogRecord` instance after merging any
- user-supplied arguments with the message.
LoggerAdapter Objects
---------------------
@@ -2150,13 +2160,13 @@
Returns an instance of :class:`LoggerAdapter` initialized with an
underlying :class:`Logger` instance and a dict-like object.
-.. method:: LoggerAdapter.process(msg, kwargs)
+ .. method:: process(msg, kwargs)
- Modifies the message and/or keyword arguments passed to a logging call in
- order to insert contextual information. This implementation takes the
- object passed as *extra* to the constructor and adds it to *kwargs* using
- key 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
- (possibly modified) versions of the arguments passed in.
+ Modifies the message and/or keyword arguments passed to a logging call in
+ order to insert contextual information. This implementation takes the object
+ passed as *extra* to the constructor and adds it to *kwargs* using key
+ 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
+ (possibly modified) versions of the arguments passed in.
In addition to the above, :class:`LoggerAdapter` supports all the logging
methods of :class:`Logger`, i.e. :meth:`debug`, :meth:`info`, :meth:`warning`,
Modified: python/branches/py3k/Doc/library/mailbox.rst
==============================================================================
--- python/branches/py3k/Doc/library/mailbox.rst (original)
+++ python/branches/py3k/Doc/library/mailbox.rst Fri Apr 25 03:59:09 2008
@@ -32,237 +32,243 @@
A mailbox, which may be inspected and modified.
-The :class:`Mailbox` class defines an interface and is not intended to be
-instantiated. Instead, format-specific subclasses should inherit from
-:class:`Mailbox` and your code should instantiate a particular subclass.
+ The :class:`Mailbox` class defines an interface and is not intended to be
+ instantiated. Instead, format-specific subclasses should inherit from
+ :class:`Mailbox` and your code should instantiate a particular subclass.
+
+ The :class:`Mailbox` interface is dictionary-like, with small keys
+ corresponding to messages. Keys are issued by the :class:`Mailbox` instance
+ with which they will be used and are only meaningful to that :class:`Mailbox`
+ instance. A key continues to identify a message even if the corresponding
+ message is modified, such as by replacing it with another message.
+
+ Messages may be added to a :class:`Mailbox` instance using the set-like
+ method :meth:`add` and removed using a ``del`` statement or the set-like
+ methods :meth:`remove` and :meth:`discard`.
+
+ :class:`Mailbox` interface semantics differ from dictionary semantics in some
+ noteworthy ways. Each time a message is requested, a new representation
+ (typically a :class:`Message` instance) is generated based upon the current
+ state of the mailbox. Similarly, when a message is added to a
+ :class:`Mailbox` instance, the provided message representation's contents are
+ copied. In neither case is a reference to the message representation kept by
+ the :class:`Mailbox` instance.
+
+ The default :class:`Mailbox` iterator iterates over message representations,
+ not keys as the default dictionary iterator does. Moreover, modification of a
+ mailbox during iteration is safe and well-defined. Messages added to the
+ mailbox after an iterator is created will not be seen by the
+ iterator. Messages removed from the mailbox before the iterator yields them
+ will be silently skipped, though using a key from an iterator may result in a
+ :exc:`KeyError` exception if the corresponding message is subsequently
+ removed.
-The :class:`Mailbox` interface is dictionary-like, with small keys corresponding
-to messages. Keys are issued by the :class:`Mailbox` instance with which they
-will be used and are only meaningful to that :class:`Mailbox` instance. A key
-continues to identify a message even if the corresponding message is modified,
-such as by replacing it with another message.
-
-Messages may be added to a :class:`Mailbox` instance using the set-like method
-:meth:`add` and removed using a ``del`` statement or the set-like methods
-:meth:`remove` and :meth:`discard`.
-
-:class:`Mailbox` interface semantics differ from dictionary semantics in some
-noteworthy ways. Each time a message is requested, a new representation
-(typically a :class:`Message` instance) is generated based upon the current
-state of the mailbox. Similarly, when a message is added to a :class:`Mailbox`
-instance, the provided message representation's contents are copied. In neither
-case is a reference to the message representation kept by the :class:`Mailbox`
-instance.
+ .. warning::
-The default :class:`Mailbox` iterator iterates over message representations, not
-keys as the default dictionary iterator does. Moreover, modification of a
-mailbox during iteration is safe and well-defined. Messages added to the mailbox
-after an iterator is created will not be seen by the iterator. Messages removed
-from the mailbox before the iterator yields them will be silently skipped,
-though using a key from an iterator may result in a :exc:`KeyError` exception if
-the corresponding message is subsequently removed.
+ Be very cautious when modifying mailboxes that might be simultaneously
+ changed by some other process. The safest mailbox format to use for such
+ tasks is Maildir; try to avoid using single-file formats such as mbox for
+ concurrent writing. If you're modifying a mailbox, you *must* lock it by
+ calling the :meth:`lock` and :meth:`unlock` methods *before* reading any
+ messages in the file or making any changes by adding or deleting a
+ message. Failing to lock the mailbox runs the risk of losing messages or
+ corrupting the entire mailbox.
-.. warning::
+ :class:`Mailbox` instances have the following methods:
- Be very cautious when modifying mailboxes that might be simultaneously changed
- by some other process. The safest mailbox format to use for such tasks is
- Maildir; try to avoid using single-file formats such as mbox for concurrent
- writing. If you're modifying a mailbox, you *must* lock it by calling the
- :meth:`lock` and :meth:`unlock` methods *before* reading any messages in the
- file or making any changes by adding or deleting a message. Failing to lock the
- mailbox runs the risk of losing messages or corrupting the entire mailbox.
-:class:`Mailbox` instances have the following methods:
+ .. method:: add(message)
+ Add *message* to the mailbox and return the key that has been assigned to
+ it.
-.. method:: Mailbox.add(message)
+ Parameter *message* may be a :class:`Message` instance, an
+ :class:`email.Message.Message` instance, a string, or a file-like object
+ (which should be open in text mode). If *message* is an instance of the
+ appropriate format-specific :class:`Message` subclass (e.g., if it's an
+ :class:`mboxMessage` instance and this is an :class:`mbox` instance), its
+ format-specific information is used. Otherwise, reasonable defaults for
+ format-specific information are used.
- Add *message* to the mailbox and return the key that has been assigned to it.
- Parameter *message* may be a :class:`Message` instance, an
- :class:`email.Message.Message` instance, a string, or a file-like object (which
- should be open in text mode). If *message* is an instance of the appropriate
- format-specific :class:`Message` subclass (e.g., if it's an :class:`mboxMessage`
- instance and this is an :class:`mbox` instance), its format-specific information
- is used. Otherwise, reasonable defaults for format-specific information are
- used.
+ .. method:: remove(key)
+ __delitem__(key)
+ discard(key)
+ Delete the message corresponding to *key* from the mailbox.
-.. method:: Mailbox.remove(key)
- Mailbox.__delitem__(key)
- Mailbox.discard(key)
+ If no such message exists, a :exc:`KeyError` exception is raised if the
+ method was called as :meth:`remove` or :meth:`__delitem__` but no
+ exception is raised if the method was called as :meth:`discard`. The
+ behavior of :meth:`discard` may be preferred if the underlying mailbox
+ format supports concurrent modification by other processes.
- Delete the message corresponding to *key* from the mailbox.
- If no such message exists, a :exc:`KeyError` exception is raised if the method
- was called as :meth:`remove` or :meth:`__delitem__` but no exception is raised
- if the method was called as :meth:`discard`. The behavior of :meth:`discard` may
- be preferred if the underlying mailbox format supports concurrent modification
- by other processes.
+ .. method:: __setitem__(key, message)
+ Replace the message corresponding to *key* with *message*. Raise a
+ :exc:`KeyError` exception if no message already corresponds to *key*.
-.. method:: Mailbox.__setitem__(key, message)
+ As with :meth:`add`, parameter *message* may be a :class:`Message`
+ instance, an :class:`email.Message.Message` instance, a string, or a
+ file-like object (which should be open in text mode). If *message* is an
+ instance of the appropriate format-specific :class:`Message` subclass
+ (e.g., if it's an :class:`mboxMessage` instance and this is an
+ :class:`mbox` instance), its format-specific information is
+ used. Otherwise, the format-specific information of the message that
+ currently corresponds to *key* is left unchanged.
- Replace the message corresponding to *key* with *message*. Raise a
- :exc:`KeyError` exception if no message already corresponds to *key*.
- As with :meth:`add`, parameter *message* may be a :class:`Message` instance, an
- :class:`email.Message.Message` instance, a string, or a file-like object (which
- should be open in text mode). If *message* is an instance of the appropriate
- format-specific :class:`Message` subclass (e.g., if it's an :class:`mboxMessage`
- instance and this is an :class:`mbox` instance), its format-specific information
- is used. Otherwise, the format-specific information of the message that
- currently corresponds to *key* is left unchanged.
+ .. method:: iterkeys()
+ keys()
+ Return an iterator over all keys if called as :meth:`iterkeys` or return a
+ list of keys if called as :meth:`keys`.
-.. method:: Mailbox.iterkeys()
- Mailbox.keys()
- Return an iterator over all keys if called as :meth:`iterkeys` or return a list
- of keys if called as :meth:`keys`.
+ .. method:: itervalues()
+ __iter__()
+ values()
+ Return an iterator over representations of all messages if called as
+ :meth:`itervalues` or :meth:`__iter__` or return a list of such
+ representations if called as :meth:`values`. The messages are represented
+ as instances of the appropriate format-specific :class:`Message` subclass
+ unless a custom message factory was specified when the :class:`Mailbox`
+ instance was initialized.
-.. method:: Mailbox.itervalues()
- Mailbox.__iter__()
- Mailbox.values()
+ .. note::
- Return an iterator over representations of all messages if called as
- :meth:`itervalues` or :meth:`__iter__` or return a list of such representations
- if called as :meth:`values`. The messages are represented as instances of the
- appropriate format-specific :class:`Message` subclass unless a custom message
- factory was specified when the :class:`Mailbox` instance was initialized.
+ The behavior of :meth:`__iter__` is unlike that of dictionaries, which
+ iterate over keys.
- .. note::
- The behavior of :meth:`__iter__` is unlike that of dictionaries, which iterate
- over keys.
+ .. method:: iteritems()
+ items()
+ Return an iterator over (*key*, *message*) pairs, where *key* is a key and
+ *message* is a message representation, if called as :meth:`iteritems` or
+ return a list of such pairs if called as :meth:`items`. The messages are
+ represented as instances of the appropriate format-specific
+ :class:`Message` subclass unless a custom message factory was specified
+ when the :class:`Mailbox` instance was initialized.
-.. method:: Mailbox.iteritems()
- Mailbox.items()
- Return an iterator over (*key*, *message*) pairs, where *key* is a key and
- *message* is a message representation, if called as :meth:`iteritems` or return
- a list of such pairs if called as :meth:`items`. The messages are represented as
- instances of the appropriate format-specific :class:`Message` subclass unless a
- custom message factory was specified when the :class:`Mailbox` instance was
- initialized.
+ .. method:: get(key[, default=None])
+ __getitem__(key)
+ Return a representation of the message corresponding to *key*. If no such
+ message exists, *default* is returned if the method was called as
+ :meth:`get` and a :exc:`KeyError` exception is raised if the method was
+ called as :meth:`__getitem__`. The message is represented as an instance
+ of the appropriate format-specific :class:`Message` subclass unless a
+ custom message factory was specified when the :class:`Mailbox` instance
+ was initialized.
-.. method:: Mailbox.get(key[, default=None])
- Mailbox.__getitem__(key)
- Return a representation of the message corresponding to *key*. If no such
- message exists, *default* is returned if the method was called as :meth:`get`
- and a :exc:`KeyError` exception is raised if the method was called as
- :meth:`__getitem__`. The message is represented as an instance of the
- appropriate format-specific :class:`Message` subclass unless a custom message
- factory was specified when the :class:`Mailbox` instance was initialized.
+ .. method:: get_message(key)
+ Return a representation of the message corresponding to *key* as an
+ instance of the appropriate format-specific :class:`Message` subclass, or
+ raise a :exc:`KeyError` exception if no such message exists.
-.. method:: Mailbox.get_message(key)
- Return a representation of the message corresponding to *key* as an instance of
- the appropriate format-specific :class:`Message` subclass, or raise a
- :exc:`KeyError` exception if no such message exists.
+ .. method:: get_string(key)
+ Return a string representation of the message corresponding to *key*, or
+ raise a :exc:`KeyError` exception if no such message exists.
-.. method:: Mailbox.get_string(key)
- Return a string representation of the message corresponding to *key*, or raise a
- :exc:`KeyError` exception if no such message exists.
+ .. method:: get_file(key)
+ Return a file-like representation of the message corresponding to *key*,
+ or raise a :exc:`KeyError` exception if no such message exists. The
+ file-like object behaves as if open in binary mode. This file should be
+ closed once it is no longer needed.
-.. method:: Mailbox.get_file(key)
+ .. note::
- Return a file-like representation of the message corresponding to *key*, or
- raise a :exc:`KeyError` exception if no such message exists. The file-like
- object behaves as if open in binary mode. This file should be closed once it is
- no longer needed.
+ Unlike other representations of messages, file-like representations are
+ not necessarily independent of the :class:`Mailbox` instance that
+ created them or of the underlying mailbox. More specific documentation
+ is provided by each subclass.
- .. note::
- Unlike other representations of messages, file-like representations are not
- necessarily independent of the :class:`Mailbox` instance that created them or of
- the underlying mailbox. More specific documentation is provided by each
- subclass.
+ .. method:: __contains__(key)
+ Return ``True`` if *key* corresponds to a message, ``False`` otherwise.
-.. method:: Mailbox.__contains__(key)
- Return ``True`` if *key* corresponds to a message, ``False`` otherwise.
+ .. method:: __len__()
+ Return a count of messages in the mailbox.
-.. method:: Mailbox.__len__()
- Return a count of messages in the mailbox.
+ .. method:: clear()
+ Delete all messages from the mailbox.
-.. method:: Mailbox.clear()
- Delete all messages from the mailbox.
+ .. method:: pop(key[, default])
+ Return a representation of the message corresponding to *key* and delete
+ the message. If no such message exists, return *default* if it was
+ supplied or else raise a :exc:`KeyError` exception. The message is
+ represented as an instance of the appropriate format-specific
+ :class:`Message` subclass unless a custom message factory was specified
+ when the :class:`Mailbox` instance was initialized.
-.. method:: Mailbox.pop(key[, default])
- Return a representation of the message corresponding to *key* and delete the
- message. If no such message exists, return *default* if it was supplied or else
- raise a :exc:`KeyError` exception. The message is represented as an instance of
- the appropriate format-specific :class:`Message` subclass unless a custom
- message factory was specified when the :class:`Mailbox` instance was
- initialized.
+ .. method:: popitem()
+ Return an arbitrary (*key*, *message*) pair, where *key* is a key and
+ *message* is a message representation, and delete the corresponding
+ message. If the mailbox is empty, raise a :exc:`KeyError` exception. The
+ message is represented as an instance of the appropriate format-specific
+ :class:`Message` subclass unless a custom message factory was specified
+ when the :class:`Mailbox` instance was initialized.
-.. method:: Mailbox.popitem()
- Return an arbitrary (*key*, *message*) pair, where *key* is a key and *message*
- is a message representation, and delete the corresponding message. If the
- mailbox is empty, raise a :exc:`KeyError` exception. The message is represented
- as an instance of the appropriate format-specific :class:`Message` subclass
- unless a custom message factory was specified when the :class:`Mailbox` instance
- was initialized.
+ .. method:: update(arg)
+ Parameter *arg* should be a *key*-to-*message* mapping or an iterable of
+ (*key*, *message*) pairs. Updates the mailbox so that, for each given
+ *key* and *message*, the message corresponding to *key* is set to
+ *message* as if by using :meth:`__setitem__`. As with :meth:`__setitem__`,
+ each *key* must already correspond to a message in the mailbox or else a
+ :exc:`KeyError` exception will be raised, so in general it is incorrect
+ for *arg* to be a :class:`Mailbox` instance.
-.. method:: Mailbox.update(arg)
+ .. note::
- Parameter *arg* should be a *key*-to-*message* mapping or an iterable of (*key*,
- *message*) pairs. Updates the mailbox so that, for each given *key* and
- *message*, the message corresponding to *key* is set to *message* as if by using
- :meth:`__setitem__`. As with :meth:`__setitem__`, each *key* must already
- correspond to a message in the mailbox or else a :exc:`KeyError` exception will
- be raised, so in general it is incorrect for *arg* to be a :class:`Mailbox`
- instance.
+ Unlike with dictionaries, keyword arguments are not supported.
- .. note::
- Unlike with dictionaries, keyword arguments are not supported.
+ .. method:: flush()
+ Write any pending changes to the filesystem. For some :class:`Mailbox`
+ subclasses, changes are always written immediately and :meth:`flush` does
+ nothing, but you should still make a habit of calling this method.
-.. method:: Mailbox.flush()
- Write any pending changes to the filesystem. For some :class:`Mailbox`
- subclasses, changes are always written immediately and :meth:`flush` does
- nothing, but you should still make a habit of calling this method.
+ .. method:: lock()
+ Acquire an exclusive advisory lock on the mailbox so that other processes
+ know not to modify it. An :exc:`ExternalClashError` is raised if the lock
+ is not available. The particular locking mechanisms used depend upon the
+ mailbox format. You should *always* lock the mailbox before making any
+ modifications to its contents.
-.. method:: Mailbox.lock()
- Acquire an exclusive advisory lock on the mailbox so that other processes know
- not to modify it. An :exc:`ExternalClashError` is raised if the lock is not
- available. The particular locking mechanisms used depend upon the mailbox
- format. You should *always* lock the mailbox before making any modifications
- to its contents.
+ .. method:: unlock()
+ Release the lock on the mailbox, if any.
-.. method:: Mailbox.unlock()
- Release the lock on the mailbox, if any.
+ .. method:: close()
-
-.. method:: Mailbox.close()
-
- Flush the mailbox, unlock it if necessary, and close any open files. For some
- :class:`Mailbox` subclasses, this method does nothing.
+ Flush the mailbox, unlock it if necessary, and close any open files. For
+ some :class:`Mailbox` subclasses, this method does nothing.
.. _mailbox-maildir:
@@ -285,113 +291,115 @@
instance that behaves like instances of other :class:`Mailbox` subclasses, set
*factory* to ``None``.
-Maildir is a directory-based mailbox format invented for the qmail mail transfer
-agent and now widely supported by other programs. Messages in a Maildir mailbox
-are stored in separate files within a common directory structure. This design
-allows Maildir mailboxes to be accessed and modified by multiple unrelated
-programs without data corruption, so file locking is unnecessary.
-
-Maildir mailboxes contain three subdirectories, namely: :file:`tmp`,
-:file:`new`, and :file:`cur`. Messages are created momentarily in the
-:file:`tmp` subdirectory and then moved to the :file:`new` subdirectory to
-finalize delivery. A mail user agent may subsequently move the message to the
-:file:`cur` subdirectory and store information about the state of the message in
-a special "info" section appended to its file name.
+ Maildir is a directory-based mailbox format invented for the qmail mail
+ transfer agent and now widely supported by other programs. Messages in a
+ Maildir mailbox are stored in separate files within a common directory
+ structure. This design allows Maildir mailboxes to be accessed and modified
+ by multiple unrelated programs without data corruption, so file locking is
+ unnecessary.
+
+ Maildir mailboxes contain three subdirectories, namely: :file:`tmp`,
+ :file:`new`, and :file:`cur`. Messages are created momentarily in the
+ :file:`tmp` subdirectory and then moved to the :file:`new` subdirectory to
+ finalize delivery. A mail user agent may subsequently move the message to the
+ :file:`cur` subdirectory and store information about the state of the message
+ in a special "info" section appended to its file name.
+
+ Folders of the style introduced by the Courier mail transfer agent are also
+ supported. Any subdirectory of the main mailbox is considered a folder if
+ ``'.'`` is the first character in its name. Folder names are represented by
+ :class:`Maildir` without the leading ``'.'``. Each folder is itself a Maildir
+ mailbox but should not contain other folders. Instead, a logical nesting is
+ indicated using ``'.'`` to delimit levels, e.g., "Archived.2005.07".
-Folders of the style introduced by the Courier mail transfer agent are also
-supported. Any subdirectory of the main mailbox is considered a folder if
-``'.'`` is the first character in its name. Folder names are represented by
-:class:`Maildir` without the leading ``'.'``. Each folder is itself a Maildir
-mailbox but should not contain other folders. Instead, a logical nesting is
-indicated using ``'.'`` to delimit levels, e.g., "Archived.2005.07".
-
-.. note::
+ .. note::
- The Maildir specification requires the use of a colon (``':'``) in certain
- message file names. However, some operating systems do not permit this character
- in file names, If you wish to use a Maildir-like format on such an operating
- system, you should specify another character to use instead. The exclamation
- point (``'!'``) is a popular choice. For example::
+ The Maildir specification requires the use of a colon (``':'``) in certain
+ message file names. However, some operating systems do not permit this
+ character in file names, If you wish to use a Maildir-like format on such
+ an operating system, you should specify another character to use
+ instead. The exclamation point (``'!'``) is a popular choice. For
+ example::
- import mailbox
- mailbox.Maildir.colon = '!'
+ import mailbox
+ mailbox.Maildir.colon = '!'
- The :attr:`colon` attribute may also be set on a per-instance basis.
+ The :attr:`colon` attribute may also be set on a per-instance basis.
-:class:`Maildir` instances have all of the methods of :class:`Mailbox` in
-addition to the following:
+ :class:`Maildir` instances have all of the methods of :class:`Mailbox` in
+ addition to the following:
-.. method:: Maildir.list_folders()
+ .. method:: list_folders()
- Return a list of the names of all folders.
+ Return a list of the names of all folders.
-.. method:: Maildir.get_folder(folder)
+ .. method:: .et_folder(folder)
- Return a :class:`Maildir` instance representing the folder whose name is
- *folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder does not
- exist.
+ Return a :class:`Maildir` instance representing the folder whose name is
+ *folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder
+ does not exist.
-.. method:: Maildir.add_folder(folder)
+ .. method:: add_folder(folder)
- Create a folder whose name is *folder* and return a :class:`Maildir` instance
- representing it.
+ Create a folder whose name is *folder* and return a :class:`Maildir`
+ instance representing it.
-.. method:: Maildir.remove_folder(folder)
+ .. method:: remove_folder(folder)
- Delete the folder whose name is *folder*. If the folder contains any messages, a
- :exc:`NotEmptyError` exception will be raised and the folder will not be
- deleted.
+ Delete the folder whose name is *folder*. If the folder contains any
+ messages, a :exc:`NotEmptyError` exception will be raised and the folder
+ will not be deleted.
-.. method:: Maildir.clean()
+ .. method:: clean()
- Delete temporary files from the mailbox that have not been accessed in the last
- 36 hours. The Maildir specification says that mail-reading programs should do
- this occasionally.
+ Delete temporary files from the mailbox that have not been accessed in the
+ last 36 hours. The Maildir specification says that mail-reading programs
+ should do this occasionally.
-Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special
-remarks:
+ Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special
+ remarks:
-.. method:: Maildir.add(message)
- Maildir.__setitem__(key, message)
- Maildir.update(arg)
+ .. method:: add(message)
+ __setitem__(key, message)
+ update(arg)
- .. warning::
+ .. warning::
- These methods generate unique file names based upon the current process ID. When
- using multiple threads, undetected name clashes may occur and cause corruption
- of the mailbox unless threads are coordinated to avoid using these methods to
- manipulate the same mailbox simultaneously.
+ These methods generate unique file names based upon the current process
+ ID. When using multiple threads, undetected name clashes may occur and
+ cause corruption of the mailbox unless threads are coordinated to avoid
+ using these methods to manipulate the same mailbox simultaneously.
-.. method:: Maildir.flush()
+ .. method:: flush()
- All changes to Maildir mailboxes are immediately applied, so this method does
- nothing.
+ All changes to Maildir mailboxes are immediately applied, so this method
+ does nothing.
-.. method:: Maildir.lock()
- Maildir.unlock()
+ .. method:: lock()
+ unlock()
- Maildir mailboxes do not support (or require) locking, so these methods do
- nothing.
+ Maildir mailboxes do not support (or require) locking, so these methods do
+ nothing.
-.. method:: Maildir.close()
+ .. method:: close()
- :class:`Maildir` instances do not keep any open files and the underlying
- mailboxes do not support locking, so this method does nothing.
+ :class:`Maildir` instances do not keep any open files and the underlying
+ mailboxes do not support locking, so this method does nothing.
-.. method:: Maildir.get_file(key)
+ .. method:: get_file(key)
- Depending upon the host platform, it may not be possible to modify or remove the
- underlying message while the returned file remains open.
+ Depending upon the host platform, it may not be possible to modify or
+ remove the underlying message while the returned file remains open.
.. seealso::
@@ -423,33 +431,34 @@
representation. If *create* is ``True``, the mailbox is created if it does not
exist.
-The mbox format is the classic format for storing mail on Unix systems. All
-messages in an mbox mailbox are stored in a single file with the beginning of
-each message indicated by a line whose first five characters are "From ".
+ The mbox format is the classic format for storing mail on Unix systems. All
+ messages in an mbox mailbox are stored in a single file with the beginning of
+ each message indicated by a line whose first five characters are "From ".
-Several variations of the mbox format exist to address perceived shortcomings in
-the original. In the interest of compatibility, :class:`mbox` implements the
-original format, which is sometimes referred to as :dfn:`mboxo`. This means that
-the :mailheader:`Content-Length` header, if present, is ignored and that any
-occurrences of "From " at the beginning of a line in a message body are
-transformed to ">From " when storing the message, although occurrences of ">From
-" are not transformed to "From " when reading the message.
+ Several variations of the mbox format exist to address perceived shortcomings in
+ the original. In the interest of compatibility, :class:`mbox` implements the
+ original format, which is sometimes referred to as :dfn:`mboxo`. This means that
+ the :mailheader:`Content-Length` header, if present, is ignored and that any
+ occurrences of "From " at the beginning of a line in a message body are
+ transformed to ">From " when storing the message, although occurrences of ">From
+ " are not transformed to "From " when reading the message.
-Some :class:`Mailbox` methods implemented by :class:`mbox` deserve special
-remarks:
+ Some :class:`Mailbox` methods implemented by :class:`mbox` deserve special
+ remarks:
-.. method:: mbox.get_file(key)
+ .. method:: get_file(key)
- Using the file after calling :meth:`flush` or :meth:`close` on the :class:`mbox`
- instance may yield unpredictable results or raise an exception.
+ Using the file after calling :meth:`flush` or :meth:`close` on the
+ :class:`mbox` instance may yield unpredictable results or raise an
+ exception.
-.. method:: mbox.lock()
- mbox.unlock()
+ .. method:: lock()
+ unlock()
- Three locking mechanisms are used---dot locking and, if available, the
- :cfunc:`flock` and :cfunc:`lockf` system calls.
+ Three locking mechanisms are used---dot locking and, if available, the
+ :cfunc:`flock` and :cfunc:`lockf` system calls.
.. seealso::
@@ -482,106 +491,109 @@
representation. If *create* is ``True``, the mailbox is created if it does not
exist.
-MH is a directory-based mailbox format invented for the MH Message Handling
-System, a mail user agent. Each message in an MH mailbox resides in its own
-file. An MH mailbox may contain other MH mailboxes (called :dfn:`folders`) in
-addition to messages. Folders may be nested indefinitely. MH mailboxes also
-support :dfn:`sequences`, which are named lists used to logically group messages
-without moving them to sub-folders. Sequences are defined in a file called
-:file:`.mh_sequences` in each folder.
+ MH is a directory-based mailbox format invented for the MH Message Handling
+ System, a mail user agent. Each message in an MH mailbox resides in its own
+ file. An MH mailbox may contain other MH mailboxes (called :dfn:`folders`) in
+ addition to messages. Folders may be nested indefinitely. MH mailboxes also
+ support :dfn:`sequences`, which are named lists used to logically group
+ messages without moving them to sub-folders. Sequences are defined in a file
+ called :file:`.mh_sequences` in each folder.
-The :class:`MH` class manipulates MH mailboxes, but it does not attempt to
-emulate all of :program:`mh`'s behaviors. In particular, it does not modify and
-is not affected by the :file:`context` or :file:`.mh_profile` files that are
-used by :program:`mh` to store its state and configuration.
+ The :class:`MH` class manipulates MH mailboxes, but it does not attempt to
+ emulate all of :program:`mh`'s behaviors. In particular, it does not modify
+ and is not affected by the :file:`context` or :file:`.mh_profile` files that
+ are used by :program:`mh` to store its state and configuration.
-:class:`MH` instances have all of the methods of :class:`Mailbox` in addition to
-the following:
+ :class:`MH` instances have all of the methods of :class:`Mailbox` in addition
+ to the following:
-.. method:: MH.list_folders()
+ .. method:: list_folders()
- Return a list of the names of all folders.
+ Return a list of the names of all folders.
-.. method:: MH.get_folder(folder)
+ .. method:: get_folder(folder)
- Return an :class:`MH` instance representing the folder whose name is *folder*. A
- :exc:`NoSuchMailboxError` exception is raised if the folder does not exist.
+ Return an :class:`MH` instance representing the folder whose name is
+ *folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder
+ does not exist.
-.. method:: MH.add_folder(folder)
+ .. method:: add_folder(folder)
- Create a folder whose name is *folder* and return an :class:`MH` instance
- representing it.
+ Create a folder whose name is *folder* and return an :class:`MH` instance
+ representing it.
-.. method:: MH.remove_folder(folder)
+ .. method:: remove_folder(folder)
- Delete the folder whose name is *folder*. If the folder contains any messages, a
- :exc:`NotEmptyError` exception will be raised and the folder will not be
- deleted.
+ Delete the folder whose name is *folder*. If the folder contains any
+ messages, a :exc:`NotEmptyError` exception will be raised and the folder
+ will not be deleted.
-.. method:: MH.get_sequences()
+ .. method:: get_sequences()
- Return a dictionary of sequence names mapped to key lists. If there are no
- sequences, the empty dictionary is returned.
+ Return a dictionary of sequence names mapped to key lists. If there are no
+ sequences, the empty dictionary is returned.
-.. method:: MH.set_sequences(sequences)
+ .. method:: set_sequences(sequences)
- Re-define the sequences that exist in the mailbox based upon *sequences*, a
- dictionary of names mapped to key lists, like returned by :meth:`get_sequences`.
+ Re-define the sequences that exist in the mailbox based upon *sequences*,
+ a dictionary of names mapped to key lists, like returned by
+ :meth:`get_sequences`.
-.. method:: MH.pack()
+ .. method:: pack()
- Rename messages in the mailbox as necessary to eliminate gaps in numbering.
- Entries in the sequences list are updated correspondingly.
+ Rename messages in the mailbox as necessary to eliminate gaps in
+ numbering. Entries in the sequences list are updated correspondingly.
- .. note::
+ .. note::
- Already-issued keys are invalidated by this operation and should not be
- subsequently used.
+ Already-issued keys are invalidated by this operation and should not be
+ subsequently used.
-Some :class:`Mailbox` methods implemented by :class:`MH` deserve special
-remarks:
+ Some :class:`Mailbox` methods implemented by :class:`MH` deserve special
+ remarks:
-.. method:: MH.remove(key)
- MH.__delitem__(key)
- MH.discard(key)
+ .. method:: remove(key)
+ __delitem__(key)
+ discard(key)
- These methods immediately delete the message. The MH convention of marking a
- message for deletion by prepending a comma to its name is not used.
+ These methods immediately delete the message. The MH convention of marking
+ a message for deletion by prepending a comma to its name is not used.
-.. method:: MH.lock()
- MH.unlock()
+ .. method:: lock()
+ unlock()
- Three locking mechanisms are used---dot locking and, if available, the
- :cfunc:`flock` and :cfunc:`lockf` system calls. For MH mailboxes, locking the
- mailbox means locking the :file:`.mh_sequences` file and, only for the duration
- of any operations that affect them, locking individual message files.
+ Three locking mechanisms are used---dot locking and, if available, the
+ :cfunc:`flock` and :cfunc:`lockf` system calls. For MH mailboxes, locking
+ the mailbox means locking the :file:`.mh_sequences` file and, only for the
+ duration of any operations that affect them, locking individual message
+ files.
-.. method:: MH.get_file(key)
+ .. method:: get_file(key)
- Depending upon the host platform, it may not be possible to remove the
- underlying message while the returned file remains open.
+ Depending upon the host platform, it may not be possible to remove the
+ underlying message while the returned file remains open.
-.. method:: MH.flush()
+ .. method:: flush()
- All changes to MH mailboxes are immediately applied, so this method does
- nothing.
+ All changes to MH mailboxes are immediately applied, so this method does
+ nothing.
-.. method:: MH.close()
+ .. method:: close()
- :class:`MH` instances do not keep any open files, so this method is equivalent
- to :meth:`unlock`.
+ :class:`MH` instances do not keep any open files, so this method is
+ equivalent to :meth:`unlock`.
.. seealso::
@@ -609,54 +621,56 @@
representation. If *create* is ``True``, the mailbox is created if it does not
exist.
-Babyl is a single-file mailbox format used by the Rmail mail user agent included
-with Emacs. The beginning of a message is indicated by a line containing the two
-characters Control-Underscore (``'\037'``) and Control-L (``'\014'``). The end
-of a message is indicated by the start of the next message or, in the case of
-the last message, a line containing a Control-Underscore (``'\037'``)
-character.
-
-Messages in a Babyl mailbox have two sets of headers, original headers and
-so-called visible headers. Visible headers are typically a subset of the
-original headers that have been reformatted or abridged to be more
-attractive. Each message in a Babyl mailbox also has an accompanying list of
-:dfn:`labels`, or short strings that record extra information about the message,
-and a list of all user-defined labels found in the mailbox is kept in the Babyl
-options section.
+ Babyl is a single-file mailbox format used by the Rmail mail user agent
+ included with Emacs. The beginning of a message is indicated by a line
+ containing the two characters Control-Underscore (``'\037'``) and Control-L
+ (``'\014'``). The end of a message is indicated by the start of the next
+ message or, in the case of the last message, a line containing a
+ Control-Underscore (``'\037'``) character.
-:class:`Babyl` instances have all of the methods of :class:`Mailbox` in addition
-to the following:
+ Messages in a Babyl mailbox have two sets of headers, original headers and
+ so-called visible headers. Visible headers are typically a subset of the
+ original headers that have been reformatted or abridged to be more
+ attractive. Each message in a Babyl mailbox also has an accompanying list of
+ :dfn:`labels`, or short strings that record extra information about the
+ message, and a list of all user-defined labels found in the mailbox is kept
+ in the Babyl options section.
+ :class:`Babyl` instances have all of the methods of :class:`Mailbox` in
+ addition to the following:
-.. method:: Babyl.get_labels()
- Return a list of the names of all user-defined labels used in the mailbox.
+ .. method:: get_labels()
- .. note::
+ Return a list of the names of all user-defined labels used in the mailbox.
+
+ .. note::
- The actual messages are inspected to determine which labels exist in the mailbox
- rather than consulting the list of labels in the Babyl options section, but the
- Babyl section is updated whenever the mailbox is modified.
+ The actual messages are inspected to determine which labels exist in
+ the mailbox rather than consulting the list of labels in the Babyl
+ options section, but the Babyl section is updated whenever the mailbox
+ is modified.
-Some :class:`Mailbox` methods implemented by :class:`Babyl` deserve special
-remarks:
+ Some :class:`Mailbox` methods implemented by :class:`Babyl` deserve special
+ remarks:
-.. method:: Babyl.get_file(key)
+ .. method:: get_file(key)
- In Babyl mailboxes, the headers of a message are not stored contiguously with
- the body of the message. To generate a file-like representation, the headers and
- body are copied together into a :class:`StringIO` instance (from the
- :mod:`StringIO` module), which has an API identical to that of a file. As a
- result, the file-like object is truly independent of the underlying mailbox but
- does not save memory compared to a string representation.
+ In Babyl mailboxes, the headers of a message are not stored contiguously
+ with the body of the message. To generate a file-like representation, the
+ headers and body are copied together into a :class:`StringIO` instance
+ (from the :mod:`StringIO` module), which has an API identical to that of a
+ file. As a result, the file-like object is truly independent of the
+ underlying mailbox but does not save memory compared to a string
+ representation.
-.. method:: Babyl.lock()
- Babyl.unlock()
+ .. method:: lock()
+ unlock()
- Three locking mechanisms are used---dot locking and, if available, the
- :cfunc:`flock` and :cfunc:`lockf` system calls.
+ Three locking mechanisms are used---dot locking and, if available, the
+ :cfunc:`flock` and :cfunc:`lockf` system calls.
.. seealso::
@@ -683,30 +697,31 @@
representation. If *create* is ``True``, the mailbox is created if it does not
exist.
-MMDF is a single-file mailbox format invented for the Multichannel Memorandum
-Distribution Facility, a mail transfer agent. Each message is in the same form
-as an mbox message but is bracketed before and after by lines containing four
-Control-A (``'\001'``) characters. As with the mbox format, the beginning of
-each message is indicated by a line whose first five characters are "From ", but
-additional occurrences of "From " are not transformed to ">From " when storing
-messages because the extra message separator lines prevent mistaking such
-occurrences for the starts of subsequent messages.
+ MMDF is a single-file mailbox format invented for the Multichannel Memorandum
+ Distribution Facility, a mail transfer agent. Each message is in the same
+ form as an mbox message but is bracketed before and after by lines containing
+ four Control-A (``'\001'``) characters. As with the mbox format, the
+ beginning of each message is indicated by a line whose first five characters
+ are "From ", but additional occurrences of "From " are not transformed to
+ ">From " when storing messages because the extra message separator lines
+ prevent mistaking such occurrences for the starts of subsequent messages.
-Some :class:`Mailbox` methods implemented by :class:`MMDF` deserve special
-remarks:
+ Some :class:`Mailbox` methods implemented by :class:`MMDF` deserve special
+ remarks:
-.. method:: MMDF.get_file(key)
+ .. method:: get_file(key)
- Using the file after calling :meth:`flush` or :meth:`close` on the :class:`MMDF`
- instance may yield unpredictable results or raise an exception.
+ Using the file after calling :meth:`flush` or :meth:`close` on the
+ :class:`MMDF` instance may yield unpredictable results or raise an
+ exception.
-.. method:: MMDF.lock()
- MMDF.unlock()
+ .. method:: lock()
+ unlock()
- Three locking mechanisms are used---dot locking and, if available, the
- :cfunc:`flock` and :cfunc:`lockf` system calls.
+ Three locking mechanisms are used---dot locking and, if available, the
+ :cfunc:`flock` and :cfunc:`lockf` system calls.
.. seealso::
@@ -737,21 +752,21 @@
or a file, it should contain an :rfc:`2822`\ -compliant message, which is read
and parsed.
-The format-specific state and behaviors offered by subclasses vary, but in
-general it is only the properties that are not specific to a particular mailbox
-that are supported (although presumably the properties are specific to a
-particular mailbox format). For example, file offsets for single-file mailbox
-formats and file names for directory-based mailbox formats are not retained,
-because they are only applicable to the original mailbox. But state such as
-whether a message has been read by the user or marked as important is retained,
-because it applies to the message itself.
-
-There is no requirement that :class:`Message` instances be used to represent
-messages retrieved using :class:`Mailbox` instances. In some situations, the
-time and memory required to generate :class:`Message` representations might not
-not acceptable. For such situations, :class:`Mailbox` instances also offer
-string and file-like representations, and a custom message factory may be
-specified when a :class:`Mailbox` instance is initialized.
+ The format-specific state and behaviors offered by subclasses vary, but in
+ general it is only the properties that are not specific to a particular
+ mailbox that are supported (although presumably the properties are specific
+ to a particular mailbox format). For example, file offsets for single-file
+ mailbox formats and file names for directory-based mailbox formats are not
+ retained, because they are only applicable to the original mailbox. But state
+ such as whether a message has been read by the user or marked as important is
+ retained, because it applies to the message itself.
+
+ There is no requirement that :class:`Message` instances be used to represent
+ messages retrieved using :class:`Mailbox` instances. In some situations, the
+ time and memory required to generate :class:`Message` representations might
+ not not acceptable. For such situations, :class:`Mailbox` instances also
+ offer string and file-like representations, and a custom message factory may
+ be specified when a :class:`Mailbox` instance is initialized.
.. _mailbox-maildirmessage:
@@ -765,106 +780,109 @@
A message with Maildir-specific behaviors. Parameter *message* has the same
meaning as with the :class:`Message` constructor.
-Typically, a mail user agent application moves all of the messages in the
-:file:`new` subdirectory to the :file:`cur` subdirectory after the first time
-the user opens and closes the mailbox, recording that the messages are old
-whether or not they've actually been read. Each message in :file:`cur` has an
-"info" section added to its file name to store information about its state.
-(Some mail readers may also add an "info" section to messages in :file:`new`.)
-The "info" section may take one of two forms: it may contain "2," followed by a
-list of standardized flags (e.g., "2,FR") or it may contain "1," followed by
-so-called experimental information. Standard flags for Maildir messages are as
-follows:
-
-+------+---------+--------------------------------+
-| Flag | Meaning | Explanation |
-+======+=========+================================+
-| D | Draft | Under composition |
-+------+---------+--------------------------------+
-| F | Flagged | Marked as important |
-+------+---------+--------------------------------+
-| P | Passed | Forwarded, resent, or bounced |
-+------+---------+--------------------------------+
-| R | Replied | Replied to |
-+------+---------+--------------------------------+
-| S | Seen | Read |
-+------+---------+--------------------------------+
-| T | Trashed | Marked for subsequent deletion |
-+------+---------+--------------------------------+
-
-:class:`MaildirMessage` instances offer the following methods:
-
-
-.. method:: MaildirMessage.get_subdir()
-
- Return either "new" (if the message should be stored in the :file:`new`
- subdirectory) or "cur" (if the message should be stored in the :file:`cur`
- subdirectory).
+ Typically, a mail user agent application moves all of the messages in the
+ :file:`new` subdirectory to the :file:`cur` subdirectory after the first time
+ the user opens and closes the mailbox, recording that the messages are old
+ whether or not they've actually been read. Each message in :file:`cur` has an
+ "info" section added to its file name to store information about its state.
+ (Some mail readers may also add an "info" section to messages in
+ :file:`new`.) The "info" section may take one of two forms: it may contain
+ "2," followed by a list of standardized flags (e.g., "2,FR") or it may
+ contain "1," followed by so-called experimental information. Standard flags
+ for Maildir messages are as follows:
- .. note::
+ +------+---------+--------------------------------+
+ | Flag | Meaning | Explanation |
+ +======+=========+================================+
+ | D | Draft | Under composition |
+ +------+---------+--------------------------------+
+ | F | Flagged | Marked as important |
+ +------+---------+--------------------------------+
+ | P | Passed | Forwarded, resent, or bounced |
+ +------+---------+--------------------------------+
+ | R | Replied | Replied to |
+ +------+---------+--------------------------------+
+ | S | Seen | Read |
+ +------+---------+--------------------------------+
+ | T | Trashed | Marked for subsequent deletion |
+ +------+---------+--------------------------------+
+
+ :class:`MaildirMessage` instances offer the following methods:
+
+
+ .. method:: get_subdir()
+
+ Return either "new" (if the message should be stored in the :file:`new`
+ subdirectory) or "cur" (if the message should be stored in the :file:`cur`
+ subdirectory).
+
+ .. note::
- A message is typically moved from :file:`new` to :file:`cur` after its mailbox
- has been accessed, whether or not the message is has been read. A message
- ``msg`` has been read if ``"S" in msg.get_flags()`` is ``True``.
+ A message is typically moved from :file:`new` to :file:`cur` after its
+ mailbox has been accessed, whether or not the message is has been
+ read. A message ``msg`` has been read if ``"S" in msg.get_flags()`` is
+ ``True``.
-.. method:: MaildirMessage.set_subdir(subdir)
+ .. method:: set_subdir(subdir)
- Set the subdirectory the message should be stored in. Parameter *subdir* must be
- either "new" or "cur".
+ Set the subdirectory the message should be stored in. Parameter *subdir*
+ must be either "new" or "cur".
-.. method:: MaildirMessage.get_flags()
+ .. method:: get_flags()
- Return a string specifying the flags that are currently set. If the message
- complies with the standard Maildir format, the result is the concatenation in
- alphabetical order of zero or one occurrence of each of ``'D'``, ``'F'``,
- ``'P'``, ``'R'``, ``'S'``, and ``'T'``. The empty string is returned if no flags
- are set or if "info" contains experimental semantics.
+ Return a string specifying the flags that are currently set. If the
+ message complies with the standard Maildir format, the result is the
+ concatenation in alphabetical order of zero or one occurrence of each of
+ ``'D'``, ``'F'``, ``'P'``, ``'R'``, ``'S'``, and ``'T'``. The empty string
+ is returned if no flags are set or if "info" contains experimental
+ semantics.
-.. method:: MaildirMessage.set_flags(flags)
+ .. method:: set_flags(flags)
- Set the flags specified by *flags* and unset all others.
+ Set the flags specified by *flags* and unset all others.
-.. method:: MaildirMessage.add_flag(flag)
+ .. method:: add_flag(flag)
- Set the flag(s) specified by *flag* without changing other flags. To add more
- than one flag at a time, *flag* may be a string of more than one character. The
- current "info" is overwritten whether or not it contains experimental
- information rather than flags.
+ Set the flag(s) specified by *flag* without changing other flags. To add
+ more than one flag at a time, *flag* may be a string of more than one
+ character. The current "info" is overwritten whether or not it contains
+ experimental information rather than flags.
-.. method:: MaildirMessage.remove_flag(flag)
+ .. method:: remove_flag(flag)
- Unset the flag(s) specified by *flag* without changing other flags. To remove
- more than one flag at a time, *flag* maybe a string of more than one character.
- If "info" contains experimental information rather than flags, the current
- "info" is not modified.
+ Unset the flag(s) specified by *flag* without changing other flags. To
+ remove more than one flag at a time, *flag* maybe a string of more than
+ one character. If "info" contains experimental information rather than
+ flags, the current "info" is not modified.
-.. method:: MaildirMessage.get_date()
+ .. method:: get_date()
- Return the delivery date of the message as a floating-point number representing
- seconds since the epoch.
+ Return the delivery date of the message as a floating-point number
+ representing seconds since the epoch.
-.. method:: MaildirMessage.set_date(date)
+ .. method:: set_date(date)
- Set the delivery date of the message to *date*, a floating-point number
- representing seconds since the epoch.
+ Set the delivery date of the message to *date*, a floating-point number
+ representing seconds since the epoch.
-.. method:: MaildirMessage.get_info()
+ .. method:: get_info()
- Return a string containing the "info" for a message. This is useful for
- accessing and modifying "info" that is experimental (i.e., not a list of flags).
+ Return a string containing the "info" for a message. This is useful for
+ accessing and modifying "info" that is experimental (i.e., not a list of
+ flags).
-.. method:: MaildirMessage.set_info(info)
+ .. method:: set_info(info)
- Set "info" to *info*, which should be a string.
+ Set "info" to *info*, which should be a string.
When a :class:`MaildirMessage` instance is created based upon an
:class:`mboxMessage` or :class:`MMDFMessage` instance, the :mailheader:`Status`
@@ -930,78 +948,81 @@
A message with mbox-specific behaviors. Parameter *message* has the same meaning
as with the :class:`Message` constructor.
-Messages in an mbox mailbox are stored together in a single file. The sender's
-envelope address and the time of delivery are typically stored in a line
-beginning with "From " that is used to indicate the start of a message, though
-there is considerable variation in the exact format of this data among mbox
-implementations. Flags that indicate the state of the message, such as whether
-it has been read or marked as important, are typically stored in
-:mailheader:`Status` and :mailheader:`X-Status` headers.
+ Messages in an mbox mailbox are stored together in a single file. The
+ sender's envelope address and the time of delivery are typically stored in a
+ line beginning with "From " that is used to indicate the start of a message,
+ though there is considerable variation in the exact format of this data among
+ mbox implementations. Flags that indicate the state of the message, such as
+ whether it has been read or marked as important, are typically stored in
+ :mailheader:`Status` and :mailheader:`X-Status` headers.
-Conventional flags for mbox messages are as follows:
+ Conventional flags for mbox messages are as follows:
-+------+----------+--------------------------------+
-| Flag | Meaning | Explanation |
-+======+==========+================================+
-| R | Read | Read |
-+------+----------+--------------------------------+
-| O | Old | Previously detected by MUA |
-+------+----------+--------------------------------+
-| D | Deleted | Marked for subsequent deletion |
-+------+----------+--------------------------------+
-| F | Flagged | Marked as important |
-+------+----------+--------------------------------+
-| A | Answered | Replied to |
-+------+----------+--------------------------------+
+ +------+----------+--------------------------------+
+ | Flag | Meaning | Explanation |
+ +======+==========+================================+
+ | R | Read | Read |
+ +------+----------+--------------------------------+
+ | O | Old | Previously detected by MUA |
+ +------+----------+--------------------------------+
+ | D | Deleted | Marked for subsequent deletion |
+ +------+----------+--------------------------------+
+ | F | Flagged | Marked as important |
+ +------+----------+--------------------------------+
+ | A | Answered | Replied to |
+ +------+----------+--------------------------------+
-The "R" and "O" flags are stored in the :mailheader:`Status` header, and the
-"D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The
-flags and headers typically appear in the order mentioned.
+ The "R" and "O" flags are stored in the :mailheader:`Status` header, and the
+ "D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The
+ flags and headers typically appear in the order mentioned.
-:class:`mboxMessage` instances offer the following methods:
+ :class:`mboxMessage` instances offer the following methods:
-.. method:: mboxMessage.get_from()
+ .. method:: get_from()
- Return a string representing the "From " line that marks the start of the
- message in an mbox mailbox. The leading "From " and the trailing newline are
- excluded.
+ Return a string representing the "From " line that marks the start of the
+ message in an mbox mailbox. The leading "From " and the trailing newline
+ are excluded.
-.. method:: mboxMessage.set_from(from_[, time_=None])
+ .. method:: set_from(from_[, time_=None])
- Set the "From " line to *from_*, which should be specified without a leading
- "From " or trailing newline. For convenience, *time_* may be specified and will
- be formatted appropriately and appended to *from_*. If *time_* is specified, it
- should be a :class:`struct_time` instance, a tuple suitable for passing to
- :meth:`time.strftime`, or ``True`` (to use :meth:`time.gmtime`).
+ Set the "From " line to *from_*, which should be specified without a
+ leading "From " or trailing newline. For convenience, *time_* may be
+ specified and will be formatted appropriately and appended to *from_*. If
+ *time_* is specified, it should be a :class:`struct_time` instance, a
+ tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use
+ :meth:`time.gmtime`).
-.. method:: mboxMessage.get_flags()
+ .. method:: get_flags()
- Return a string specifying the flags that are currently set. If the message
- complies with the conventional format, the result is the concatenation in the
- following order of zero or one occurrence of each of ``'R'``, ``'O'``, ``'D'``,
- ``'F'``, and ``'A'``.
+ Return a string specifying the flags that are currently set. If the
+ message complies with the conventional format, the result is the
+ concatenation in the following order of zero or one occurrence of each of
+ ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
-.. method:: mboxMessage.set_flags(flags)
+ .. method:: set_flags(flags)
- Set the flags specified by *flags* and unset all others. Parameter *flags*
- should be the concatenation in any order of zero or more occurrences of each of
- ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
+ Set the flags specified by *flags* and unset all others. Parameter *flags*
+ should be the concatenation in any order of zero or more occurrences of
+ each of ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
-.. method:: mboxMessage.add_flag(flag)
+ .. method:: add_flag(flag)
- Set the flag(s) specified by *flag* without changing other flags. To add more
- than one flag at a time, *flag* may be a string of more than one character.
+ Set the flag(s) specified by *flag* without changing other flags. To add
+ more than one flag at a time, *flag* may be a string of more than one
+ character.
-.. method:: mboxMessage.remove_flag(flag)
+ .. method:: remove_flag(flag)
- Unset the flag(s) specified by *flag* without changing other flags. To remove
- more than one flag at a time, *flag* maybe a string of more than one character.
+ Unset the flag(s) specified by *flag* without changing other flags. To
+ remove more than one flag at a time, *flag* maybe a string of more than
+ one character.
When an :class:`mboxMessage` instance is created based upon a
:class:`MaildirMessage` instance, a "From " line is generated based upon the
@@ -1081,43 +1102,43 @@
A message with MH-specific behaviors. Parameter *message* has the same meaning
as with the :class:`Message` constructor.
-MH messages do not support marks or flags in the traditional sense, but they do
-support sequences, which are logical groupings of arbitrary messages. Some mail
-reading programs (although not the standard :program:`mh` and :program:`nmh`)
-use sequences in much the same way flags are used with other formats, as
-follows:
+ MH messages do not support marks or flags in the traditional sense, but they
+ do support sequences, which are logical groupings of arbitrary messages. Some
+ mail reading programs (although not the standard :program:`mh` and
+ :program:`nmh`) use sequences in much the same way flags are used with other
+ formats, as follows:
-+----------+------------------------------------------+
-| Sequence | Explanation |
-+==========+==========================================+
-| unseen | Not read, but previously detected by MUA |
-+----------+------------------------------------------+
-| replied | Replied to |
-+----------+------------------------------------------+
-| flagged | Marked as important |
-+----------+------------------------------------------+
+ +----------+------------------------------------------+
+ | Sequence | Explanation |
+ +==========+==========================================+
+ | unseen | Not read, but previously detected by MUA |
+ +----------+------------------------------------------+
+ | replied | Replied to |
+ +----------+------------------------------------------+
+ | flagged | Marked as important |
+ +----------+------------------------------------------+
-:class:`MHMessage` instances offer the following methods:
+ :class:`MHMessage` instances offer the following methods:
-.. method:: MHMessage.get_sequences()
+ .. method:: get_sequences()
- Return a list of the names of sequences that include this message.
+ Return a list of the names of sequences that include this message.
-.. method:: MHMessage.set_sequences(sequences)
+ .. method:: set_sequences(sequences)
- Set the list of sequences that include this message.
+ Set the list of sequences that include this message.
-.. method:: MHMessage.add_sequence(sequence)
+ .. method:: add_sequence(sequence)
- Add *sequence* to the list of sequences that include this message.
+ Add *sequence* to the list of sequences that include this message.
-.. method:: MHMessage.remove_sequence(sequence)
+ .. method:: remove_sequence(sequence)
- Remove *sequence* from the list of sequences that include this message.
+ Remove *sequence* from the list of sequences that include this message.
When an :class:`MHMessage` instance is created based upon a
:class:`MaildirMessage` instance, the following conversions take place:
@@ -1171,79 +1192,79 @@
A message with Babyl-specific behaviors. Parameter *message* has the same
meaning as with the :class:`Message` constructor.
-Certain message labels, called :dfn:`attributes`, are defined by convention to
-have special meanings. The attributes are as follows:
+ Certain message labels, called :dfn:`attributes`, are defined by convention
+ to have special meanings. The attributes are as follows:
-+-----------+------------------------------------------+
-| Label | Explanation |
-+===========+==========================================+
-| unseen | Not read, but previously detected by MUA |
-+-----------+------------------------------------------+
-| deleted | Marked for subsequent deletion |
-+-----------+------------------------------------------+
-| filed | Copied to another file or mailbox |
-+-----------+------------------------------------------+
-| answered | Replied to |
-+-----------+------------------------------------------+
-| forwarded | Forwarded |
-+-----------+------------------------------------------+
-| edited | Modified by the user |
-+-----------+------------------------------------------+
-| resent | Resent |
-+-----------+------------------------------------------+
+ +-----------+------------------------------------------+
+ | Label | Explanation |
+ +===========+==========================================+
+ | unseen | Not read, but previously detected by MUA |
+ +-----------+------------------------------------------+
+ | deleted | Marked for subsequent deletion |
+ +-----------+------------------------------------------+
+ | filed | Copied to another file or mailbox |
+ +-----------+------------------------------------------+
+ | answered | Replied to |
+ +-----------+------------------------------------------+
+ | forwarded | Forwarded |
+ +-----------+------------------------------------------+
+ | edited | Modified by the user |
+ +-----------+------------------------------------------+
+ | resent | Resent |
+ +-----------+------------------------------------------+
-By default, Rmail displays only visible headers. The :class:`BabylMessage`
-class, though, uses the original headers because they are more complete. Visible
-headers may be accessed explicitly if desired.
+ By default, Rmail displays only visible headers. The :class:`BabylMessage`
+ class, though, uses the original headers because they are more
+ complete. Visible headers may be accessed explicitly if desired.
-:class:`BabylMessage` instances offer the following methods:
+ :class:`BabylMessage` instances offer the following methods:
-.. method:: BabylMessage.get_labels()
+ .. method:: get_labels()
- Return a list of labels on the message.
+ Return a list of labels on the message.
-.. method:: BabylMessage.set_labels(labels)
+ .. method:: set_labels(labels)
- Set the list of labels on the message to *labels*.
+ Set the list of labels on the message to *labels*.
-.. method:: BabylMessage.add_label(label)
+ .. method:: add_label(label)
- Add *label* to the list of labels on the message.
+ Add *label* to the list of labels on the message.
-.. method:: BabylMessage.remove_label(label)
+ .. method:: remove_label(label)
- Remove *label* from the list of labels on the message.
+ Remove *label* from the list of labels on the message.
-.. method:: BabylMessage.get_visible()
+ .. method:: get_visible()
- Return an :class:`Message` instance whose headers are the message's visible
- headers and whose body is empty.
+ Return an :class:`Message` instance whose headers are the message's
+ visible headers and whose body is empty.
-.. method:: BabylMessage.set_visible(visible)
+ .. method:: set_visible(visible)
- Set the message's visible headers to be the same as the headers in *message*.
- Parameter *visible* should be a :class:`Message` instance, an
- :class:`email.Message.Message` instance, a string, or a file-like object (which
- should be open in text mode).
+ Set the message's visible headers to be the same as the headers in
+ *message*. Parameter *visible* should be a :class:`Message` instance, an
+ :class:`email.Message.Message` instance, a string, or a file-like object
+ (which should be open in text mode).
-.. method:: BabylMessage.update_visible()
+ .. method:: update_visible()
- When a :class:`BabylMessage` instance's original headers are modified, the
- visible headers are not automatically modified to correspond. This method
- updates the visible headers as follows: each visible header with a corresponding
- original header is set to the value of the original header, each visible header
- without a corresponding original header is removed, and any of
- :mailheader:`Date`, :mailheader:`From`, :mailheader:`Reply-To`,
- :mailheader:`To`, :mailheader:`CC`, and :mailheader:`Subject` that are present
- in the original headers but not the visible headers are added to the visible
- headers.
+ When a :class:`BabylMessage` instance's original headers are modified, the
+ visible headers are not automatically modified to correspond. This method
+ updates the visible headers as follows: each visible header with a
+ corresponding original header is set to the value of the original header,
+ each visible header without a corresponding original header is removed,
+ and any of :mailheader:`Date`, :mailheader:`From`, :mailheader:`Reply-To`,
+ :mailheader:`To`, :mailheader:`CC`, and :mailheader:`Subject` that are
+ present in the original headers but not the visible headers are added to
+ the visible headers.
When a :class:`BabylMessage` instance is created based upon a
:class:`MaildirMessage` instance, the following conversions take place:
@@ -1299,77 +1320,80 @@
A message with MMDF-specific behaviors. Parameter *message* has the same meaning
as with the :class:`Message` constructor.
-As with message in an mbox mailbox, MMDF messages are stored with the sender's
-address and the delivery date in an initial line beginning with "From ".
-Likewise, flags that indicate the state of the message are typically stored in
-:mailheader:`Status` and :mailheader:`X-Status` headers.
+ As with message in an mbox mailbox, MMDF messages are stored with the
+ sender's address and the delivery date in an initial line beginning with
+ "From ". Likewise, flags that indicate the state of the message are
+ typically stored in :mailheader:`Status` and :mailheader:`X-Status` headers.
-Conventional flags for MMDF messages are identical to those of mbox message and
-are as follows:
+ Conventional flags for MMDF messages are identical to those of mbox message
+ and are as follows:
-+------+----------+--------------------------------+
-| Flag | Meaning | Explanation |
-+======+==========+================================+
-| R | Read | Read |
-+------+----------+--------------------------------+
-| O | Old | Previously detected by MUA |
-+------+----------+--------------------------------+
-| D | Deleted | Marked for subsequent deletion |
-+------+----------+--------------------------------+
-| F | Flagged | Marked as important |
-+------+----------+--------------------------------+
-| A | Answered | Replied to |
-+------+----------+--------------------------------+
+ +------+----------+--------------------------------+
+ | Flag | Meaning | Explanation |
+ +======+==========+================================+
+ | R | Read | Read |
+ +------+----------+--------------------------------+
+ | O | Old | Previously detected by MUA |
+ +------+----------+--------------------------------+
+ | D | Deleted | Marked for subsequent deletion |
+ +------+----------+--------------------------------+
+ | F | Flagged | Marked as important |
+ +------+----------+--------------------------------+
+ | A | Answered | Replied to |
+ +------+----------+--------------------------------+
-The "R" and "O" flags are stored in the :mailheader:`Status` header, and the
-"D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The
-flags and headers typically appear in the order mentioned.
+ The "R" and "O" flags are stored in the :mailheader:`Status` header, and the
+ "D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The
+ flags and headers typically appear in the order mentioned.
-:class:`MMDFMessage` instances offer the following methods, which are identical
-to those offered by :class:`mboxMessage`:
+ :class:`MMDFMessage` instances offer the following methods, which are
+ identical to those offered by :class:`mboxMessage`:
-.. method:: MMDFMessage.get_from()
+ .. method:: get_from()
- Return a string representing the "From " line that marks the start of the
- message in an mbox mailbox. The leading "From " and the trailing newline are
- excluded.
+ Return a string representing the "From " line that marks the start of the
+ message in an mbox mailbox. The leading "From " and the trailing newline
+ are excluded.
-.. method:: MMDFMessage.set_from(from_[, time_=None])
+ .. method:: set_from(from_[, time_=None])
- Set the "From " line to *from_*, which should be specified without a leading
- "From " or trailing newline. For convenience, *time_* may be specified and will
- be formatted appropriately and appended to *from_*. If *time_* is specified, it
- should be a :class:`struct_time` instance, a tuple suitable for passing to
- :meth:`time.strftime`, or ``True`` (to use :meth:`time.gmtime`).
+ Set the "From " line to *from_*, which should be specified without a
+ leading "From " or trailing newline. For convenience, *time_* may be
+ specified and will be formatted appropriately and appended to *from_*. If
+ *time_* is specified, it should be a :class:`struct_time` instance, a
+ tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use
+ :meth:`time.gmtime`).
-.. method:: MMDFMessage.get_flags()
+ .. method:: get_flags()
- Return a string specifying the flags that are currently set. If the message
- complies with the conventional format, the result is the concatenation in the
- following order of zero or one occurrence of each of ``'R'``, ``'O'``, ``'D'``,
- ``'F'``, and ``'A'``.
+ Return a string specifying the flags that are currently set. If the
+ message complies with the conventional format, the result is the
+ concatenation in the following order of zero or one occurrence of each of
+ ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
-.. method:: MMDFMessage.set_flags(flags)
+ .. method:: set_flags(flags)
- Set the flags specified by *flags* and unset all others. Parameter *flags*
- should be the concatenation in any order of zero or more occurrences of each of
- ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
+ Set the flags specified by *flags* and unset all others. Parameter *flags*
+ should be the concatenation in any order of zero or more occurrences of
+ each of ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
-.. method:: MMDFMessage.add_flag(flag)
+ .. method:: add_flag(flag)
- Set the flag(s) specified by *flag* without changing other flags. To add more
- than one flag at a time, *flag* may be a string of more than one character.
+ Set the flag(s) specified by *flag* without changing other flags. To add
+ more than one flag at a time, *flag* may be a string of more than one
+ character.
-.. method:: MMDFMessage.remove_flag(flag)
+ .. method:: remove_flag(flag)
- Unset the flag(s) specified by *flag* without changing other flags. To remove
- more than one flag at a time, *flag* maybe a string of more than one character.
+ Unset the flag(s) specified by *flag* without changing other flags. To
+ remove more than one flag at a time, *flag* maybe a string of more than
+ one character.
When an :class:`MMDFMessage` instance is created based upon a
:class:`MaildirMessage` instance, a "From " line is generated based upon the
@@ -1445,25 +1469,25 @@
The following exception classes are defined in the :mod:`mailbox` module:
-.. class:: Error()
+.. exception:: Error()
The based class for all other module-specific exceptions.
-.. class:: NoSuchMailboxError()
+.. exception:: NoSuchMailboxError()
Raised when a mailbox is expected but is not found, such as when instantiating a
:class:`Mailbox` subclass with a path that does not exist (and with the *create*
parameter set to ``False``), or when opening a folder that does not exist.
-.. class:: NotEmptyErrorError()
+.. exception:: NotEmptyErrorError()
Raised when a mailbox is not empty but is expected to be, such as when deleting
a folder that contains messages.
-.. class:: ExternalClashError()
+.. exception:: ExternalClashError()
Raised when some mailbox-related condition beyond the control of the program
causes it to be unable to proceed, such as when failing to acquire a lock that
@@ -1471,7 +1495,7 @@
already exists.
-.. class:: FormatError()
+.. exception:: FormatError()
Raised when the data in a file cannot be parsed, such as when an :class:`MH`
instance attempts to read a corrupted :file:`.mh_sequences` file.
Modified: python/branches/py3k/Doc/library/mmap.rst
==============================================================================
--- python/branches/py3k/Doc/library/mmap.rst (original)
+++ python/branches/py3k/Doc/library/mmap.rst Fri Apr 25 03:59:09 2008
@@ -131,111 +131,111 @@
map.close()
-Memory-mapped file objects support the following methods:
+ Memory-mapped file objects support the following methods:
-.. method:: mmap.close()
+ .. method:: close()
- Close the file. Subsequent calls to other methods of the object will
- result in an exception being raised.
+ Close the file. Subsequent calls to other methods of the object will
+ result in an exception being raised.
-.. method:: mmap.find(string[, start[, end]])
+ .. method:: find(string[, start[, end]])
- Returns the lowest index in the object where the substring *string* is
- found, such that *string* is contained in the range [*start*, *end*].
- Optional arguments *start* and *end* are interpreted as in slice notation.
- Returns ``-1`` on failure.
+ Returns the lowest index in the object where the substring *string* is
+ found, such that *string* is contained in the range [*start*, *end*].
+ Optional arguments *start* and *end* are interpreted as in slice notation.
+ Returns ``-1`` on failure.
-.. method:: mmap.flush([offset, size])
+ .. method:: flush([offset, size])
- Flushes changes made to the in-memory copy of a file back to disk. Without
- use of this call there is no guarantee that changes are written back before
- the object is destroyed. If *offset* and *size* are specified, only
- changes to the given range of bytes will be flushed to disk; otherwise, the
- whole extent of the mapping is flushed.
+ Flushes changes made to the in-memory copy of a file back to disk. Without
+ use of this call there is no guarantee that changes are written back before
+ the object is destroyed. If *offset* and *size* are specified, only
+ changes to the given range of bytes will be flushed to disk; otherwise, the
+ whole extent of the mapping is flushed.
- **(Windows version)** A nonzero value returned indicates success; zero
- indicates failure.
+ **(Windows version)** A nonzero value returned indicates success; zero
+ indicates failure.
- **(Unix version)** A zero value is returned to indicate success. An
- exception is raised when the call failed.
+ **(Unix version)** A zero value is returned to indicate success. An
+ exception is raised when the call failed.
-.. method:: mmap.move(dest, src, count)
+ .. method:: move(dest, src, count)
- Copy the *count* bytes starting at offset *src* to the destination index
- *dest*. If the mmap was created with :const:`ACCESS_READ`, then calls to
- move will throw a :exc:`TypeError` exception.
+ Copy the *count* bytes starting at offset *src* to the destination index
+ *dest*. If the mmap was created with :const:`ACCESS_READ`, then calls to
+ move will throw a :exc:`TypeError` exception.
-.. method:: mmap.read(num)
+ .. method:: read(num)
- Return a string containing up to *num* bytes starting from the current file
- position; the file position is updated to point after the bytes that were
- returned.
+ Return a string containing up to *num* bytes starting from the current
+ file position; the file position is updated to point after the bytes that
+ were returned.
-.. method:: mmap.read_byte()
+ .. method:: read_byte()
- Returns a string of length 1 containing the character at the current file
- position, and advances the file position by 1.
+ Returns a string of length 1 containing the character at the current file
+ position, and advances the file position by 1.
-.. method:: mmap.readline()
+ .. method:: readline()
- Returns a single line, starting at the current file position and up to the
- next newline.
+ Returns a single line, starting at the current file position and up to the
+ next newline.
-.. method:: mmap.resize(newsize)
+ .. method:: resize(newsize)
- Resizes the map and the underlying file, if any. If the mmap was created
- with :const:`ACCESS_READ` or :const:`ACCESS_COPY`, resizing the map will
- throw a :exc:`TypeError` exception.
+ Resizes the map and the underlying file, if any. If the mmap was created
+ with :const:`ACCESS_READ` or :const:`ACCESS_COPY`, resizing the map will
+ throw a :exc:`TypeError` exception.
-.. method:: mmap.rfind(string[, start[, end]])
+ .. method:: rfind(string[, start[, end]])
- Returns the highest index in the object where the substring *string* is
- found, such that *string* is contained in the range [*start*, *end*].
- Optional arguments *start* and *end* are interpreted as in slice notation.
- Returns ``-1`` on failure.
+ Returns the highest index in the object where the substring *string* is
+ found, such that *string* is contained in the range [*start*, *end*].
+ Optional arguments *start* and *end* are interpreted as in slice notation.
+ Returns ``-1`` on failure.
-.. method:: mmap.seek(pos[, whence])
+ .. method:: seek(pos[, whence])
- Set the file's current position. *whence* argument is optional and
- defaults to ``os.SEEK_SET`` or ``0`` (absolute file positioning); other
- values are ``os.SEEK_CUR`` or ``1`` (seek relative to the current position)
- and ``os.SEEK_END`` or ``2`` (seek relative to the file's end).
+ Set the file's current position. *whence* argument is optional and
+ defaults to ``os.SEEK_SET`` or ``0`` (absolute file positioning); other
+ values are ``os.SEEK_CUR`` or ``1`` (seek relative to the current
+ position) and ``os.SEEK_END`` or ``2`` (seek relative to the file's end).
-.. method:: mmap.size()
+ .. method:: size()
- Return the length of the file, which can be larger than the size of the
- memory-mapped area.
+ Return the length of the file, which can be larger than the size of the
+ memory-mapped area.
-.. method:: mmap.tell()
+ .. method:: tell()
- Returns the current position of the file pointer.
+ Returns the current position of the file pointer.
-.. method:: mmap.write(string)
+ .. method:: write(string)
- Write the bytes in *string* into memory at the current position of the file
- pointer; the file position is updated to point after the bytes that were
- written. If the mmap was created with :const:`ACCESS_READ`, then writing to
- it will throw a :exc:`TypeError` exception.
+ Write the bytes in *string* into memory at the current position of the
+ file pointer; the file position is updated to point after the bytes that
+ were written. If the mmap was created with :const:`ACCESS_READ`, then
+ writing to it will throw a :exc:`TypeError` exception.
-.. method:: mmap.write_byte(byte)
+ .. method:: write_byte(byte)
- Write the single-character string *byte* into memory at the current
- position of the file pointer; the file position is advanced by ``1``. If
- the mmap was created with :const:`ACCESS_READ`, then writing to it will
- throw a :exc:`TypeError` exception.
+ Write the single-character string *byte* into memory at the current
+ position of the file pointer; the file position is advanced by ``1``. If
+ the mmap was created with :const:`ACCESS_READ`, then writing to it will
+ throw a :exc:`TypeError` exception.
Modified: python/branches/py3k/Doc/library/modulefinder.rst
==============================================================================
--- python/branches/py3k/Doc/library/modulefinder.rst (original)
+++ python/branches/py3k/Doc/library/modulefinder.rst Fri Apr 25 03:59:09 2008
@@ -38,19 +38,21 @@
be replaced in module paths.
-.. method:: ModuleFinder.report()
+ .. method:: report()
- Print a report to standard output that lists the modules imported by the script
- and their paths, as well as modules that are missing or seem to be missing.
+ Print a report to standard output that lists the modules imported by the
+ script and their paths, as well as modules that are missing or seem to be
+ missing.
+ .. method:: run_script(pathname)
-.. method:: ModuleFinder.run_script(pathname)
+ Analyze the contents of the *pathname* file, which must contain Python
+ code.
- Analyze the contents of the *pathname* file, which must contain Python code.
+ .. attribute:: modules
-.. attribute:: ModuleFinder.modules
-
- A dictionary mapping module names to modules. See :ref:`modulefinder-example`
+ A dictionary mapping module names to modules. See
+ :ref:`modulefinder-example`
.. _modulefinder-example:
Modified: python/branches/py3k/Doc/library/msilib.rst
==============================================================================
--- python/branches/py3k/Doc/library/msilib.rst (original)
+++ python/branches/py3k/Doc/library/msilib.rst Fri Apr 25 03:59:09 2008
@@ -318,19 +318,20 @@
*name* is the name of the CAB file in the MSI file.
-.. method:: CAB.append(full, file, logical)
+ .. method:: append(full, file, logical)
- Add the file with the pathname *full* to the CAB file, under the name *logical*.
- If there is already a file named *logical*, a new file name is created.
+ Add the file with the pathname *full* to the CAB file, under the name
+ *logical*. If there is already a file named *logical*, a new file name is
+ created.
- Return the index of the file in the CAB file, and the new name of the file
- inside the CAB file.
+ Return the index of the file in the CAB file, and the new name of the file
+ inside the CAB file.
-.. method:: CAB.commit(database)
+ .. method:: commit(database)
- Generate a CAB file, add it as a stream to the MSI file, put it into the
- ``Media`` table, and remove the generated file from the disk.
+ Generate a CAB file, add it as a stream to the MSI file, put it into the
+ ``Media`` table, and remove the generated file from the disk.
.. _msi-directory:
@@ -351,33 +352,33 @@
the default flags that new components get.
-.. method:: Directory.start_component([component[, feature[, flags[, keyfile[, uuid]]]]])
+ .. method:: start_component([component[, feature[, flags[, keyfile[, uuid]]]]])
- Add an entry to the Component table, and make this component the current
- component for this directory. If no component name is given, the directory name
- is used. If no *feature* is given, the current feature is used. If no *flags*
- are given, the directory's default flags are used. If no *keyfile* is given, the
- KeyPath is left null in the Component table.
+ Add an entry to the Component table, and make this component the current
+ component for this directory. If no component name is given, the directory
+ name is used. If no *feature* is given, the current feature is used. If no
+ *flags* are given, the directory's default flags are used. If no *keyfile*
+ is given, the KeyPath is left null in the Component table.
-.. method:: Directory.add_file(file[, src[, version[, language]]])
+ .. method:: add_file(file[, src[, version[, language]]])
- Add a file to the current component of the directory, starting a new one if
- there is no current component. By default, the file name in the source and the
- file table will be identical. If the *src* file is specified, it is interpreted
- relative to the current directory. Optionally, a *version* and a *language* can
- be specified for the entry in the File table.
+ Add a file to the current component of the directory, starting a new one
+ if there is no current component. By default, the file name in the source
+ and the file table will be identical. If the *src* file is specified, it
+ is interpreted relative to the current directory. Optionally, a *version*
+ and a *language* can be specified for the entry in the File table.
-.. method:: Directory.glob(pattern[, exclude])
+ .. method:: glob(pattern[, exclude])
- Add a list of files to the current component as specified in the glob pattern.
- Individual files can be excluded in the *exclude* list.
+ Add a list of files to the current component as specified in the glob
+ pattern. Individual files can be excluded in the *exclude* list.
-.. method:: Directory.remove_pyc()
+ .. method:: remove_pyc()
- Remove ``.pyc``/``.pyo`` files on uninstall.
+ Remove ``.pyc``/``.pyo`` files on uninstall.
.. seealso::
@@ -401,11 +402,11 @@
:class:`Directory`.
-.. method:: Feature.set_current()
+ .. method:: set_current()
- Make this feature the current feature of :mod:`msilib`. New components are
- automatically added to the default feature, unless a feature is explicitly
- specified.
+ Make this feature the current feature of :mod:`msilib`. New components are
+ automatically added to the default feature, unless a feature is explicitly
+ specified.
.. seealso::
@@ -428,19 +429,19 @@
belongs to, and *name* is the control's name.
-.. method:: Control.event(event, argument[, condition=1[, ordering]])
+ .. method:: event(event, argument[, condition=1[, ordering]])
- Make an entry into the ``ControlEvent`` table for this control.
+ Make an entry into the ``ControlEvent`` table for this control.
-.. method:: Control.mapping(event, attribute)
+ .. method:: mapping(event, attribute)
- Make an entry into the ``EventMapping`` table for this control.
+ Make an entry into the ``EventMapping`` table for this control.
-.. method:: Control.condition(action, condition)
+ .. method:: condition(action, condition)
- Make an entry into the ``ControlCondition`` table for this control.
+ Make an entry into the ``ControlCondition`` table for this control.
.. class:: RadioButtonGroup(dlg, name, property)
@@ -449,11 +450,11 @@
that gets set when a radio button is selected.
-.. method:: RadioButtonGroup.add(name, x, y, width, height, text [, value])
+ .. method:: add(name, x, y, width, height, text [, value])
- Add a radio button named *name* to the group, at the coordinates *x*, *y*,
- *width*, *height*, and with the label *text*. If *value* is omitted, it defaults
- to *name*.
+ Add a radio button named *name* to the group, at the coordinates *x*, *y*,
+ *width*, *height*, and with the label *text*. If *value* is omitted, it
+ defaults to *name*.
.. class:: Dialog(db, name, x, y, w, h, attr, title, first, default, cancel)
@@ -463,42 +464,43 @@
default, and cancel controls.
-.. method:: Dialog.control(name, type, x, y, width, height, attributes, property, text, control_next, help)
+ .. method:: control(name, type, x, y, width, height, attributes, property, text, control_next, help)
- Return a new :class:`Control` object. An entry in the ``Control`` table is made
- with the specified parameters.
+ Return a new :class:`Control` object. An entry in the ``Control`` table is
+ made with the specified parameters.
- This is a generic method; for specific types, specialized methods are provided.
+ This is a generic method; for specific types, specialized methods are
+ provided.
-.. method:: Dialog.text(name, x, y, width, height, attributes, text)
+ .. method:: text(name, x, y, width, height, attributes, text)
- Add and return a ``Text`` control.
+ Add and return a ``Text`` control.
-.. method:: Dialog.bitmap(name, x, y, width, height, text)
+ .. method:: bitmap(name, x, y, width, height, text)
- Add and return a ``Bitmap`` control.
+ Add and return a ``Bitmap`` control.
-.. method:: Dialog.line(name, x, y, width, height)
+ .. method:: line(name, x, y, width, height)
- Add and return a ``Line`` control.
+ Add and return a ``Line`` control.
-.. method:: Dialog.pushbutton(name, x, y, width, height, attributes, text, next_control)
+ .. method:: pushbutton(name, x, y, width, height, attributes, text, next_control)
- Add and return a ``PushButton`` control.
+ Add and return a ``PushButton`` control.
-.. method:: Dialog.radiogroup(name, x, y, width, height, attributes, property, text, next_control)
+ .. method:: radiogroup(name, x, y, width, height, attributes, property, text, next_control)
- Add and return a ``RadioButtonGroup`` control.
+ Add and return a ``RadioButtonGroup`` control.
-.. method:: Dialog.checkbox(name, x, y, width, height, attributes, property, text, next_control)
+ .. method:: checkbox(name, x, y, width, height, attributes, property, text, next_control)
- Add and return a ``CheckBox`` control.
+ Add and return a ``CheckBox`` control.
.. seealso::
Modified: python/branches/py3k/Doc/library/numbers.rst
==============================================================================
--- python/branches/py3k/Doc/library/numbers.rst (original)
+++ python/branches/py3k/Doc/library/numbers.rst Fri Apr 25 03:59:09 2008
@@ -27,18 +27,18 @@
``-``, ``*``, ``/``, :func:`abs`, :meth:`conjugate`, ``==``, and ``!=``. All
except ``-`` and ``!=`` are abstract.
-.. attribute:: Complex.real
+ .. attribute:: real
- Abstract. Retrieves the :class:`Real` component of this number.
+ Abstract. Retrieves the :class:`Real` component of this number.
-.. attribute:: Complex.imag
+ .. attribute:: imag
- Abstract. Retrieves the :class:`Real` component of this number.
+ Abstract. Retrieves the :class:`Real` component of this number.
-.. method:: Complex.conjugate()
+ .. method:: conjugate()
- Abstract. Returns the complex conjugate. For example, ``(1+3j).conjugate() ==
- (1-3j)``.
+ Abstract. Returns the complex conjugate. For example, ``(1+3j).conjugate()
+ == (1-3j)``.
.. class:: Real
@@ -60,13 +60,13 @@
should be in lowest terms. With these, it provides a default for
:func:`float`.
-.. attribute:: Rational.numerator
+ .. attribute:: numerator
- Abstract.
+ Abstract.
-.. attribute:: Rational.denominator
+ .. attribute:: denominator
- Abstract.
+ Abstract.
.. class:: Integral
Modified: python/branches/py3k/Doc/library/pickle.rst
==============================================================================
--- python/branches/py3k/Doc/library/pickle.rst (original)
+++ python/branches/py3k/Doc/library/pickle.rst Fri Apr 25 03:59:09 2008
@@ -245,34 +245,34 @@
It can thus be an open file object, a :mod:`StringIO` object, or any other
custom object that meets this interface.
-:class:`Pickler` objects define one (or two) public methods:
+ :class:`Pickler` objects define one (or two) public methods:
-.. method:: Pickler.dump(obj)
+ .. method:: dump(obj)
- Write a pickled representation of *obj* to the open file object given in the
- constructor. Either the binary or ASCII format will be used, depending on the
- value of the *protocol* argument passed to the constructor.
+ Write a pickled representation of *obj* to the open file object given in the
+ constructor. Either the binary or ASCII format will be used, depending on the
+ value of the *protocol* argument passed to the constructor.
-.. method:: Pickler.clear_memo()
+ .. method:: clear_memo()
- Clears the pickler's "memo". The memo is the data structure that remembers
- which objects the pickler has already seen, so that shared or recursive objects
- pickled by reference and not by value. This method is useful when re-using
- picklers.
+ Clears the pickler's "memo". The memo is the data structure that remembers
+ which objects the pickler has already seen, so that shared or recursive objects
+ pickled by reference and not by value. This method is useful when re-using
+ picklers.
- .. note::
+ .. note::
- Prior to Python 2.3, :meth:`clear_memo` was only available on the picklers
- created by :mod:`cPickle`. In the :mod:`pickle` module, picklers have an
- instance variable called :attr:`memo` which is a Python dictionary. So to clear
- the memo for a :mod:`pickle` module pickler, you could do the following::
+ Prior to Python 2.3, :meth:`clear_memo` was only available on the picklers
+ created by :mod:`cPickle`. In the :mod:`pickle` module, picklers have an
+ instance variable called :attr:`memo` which is a Python dictionary. So to clear
+ the memo for a :mod:`pickle` module pickler, you could do the following::
- mypickler.memo.clear()
+ mypickler.memo.clear()
- Code that does not need to support older versions of Python should simply use
- :meth:`clear_memo`.
+ Code that does not need to support older versions of Python should simply use
+ :meth:`clear_memo`.
It is possible to make multiple calls to the :meth:`dump` method of the same
:class:`Pickler` instance. These must then be matched to the same number of
@@ -296,29 +296,30 @@
reading, a :mod:`StringIO` object, or any other custom object that meets this
interface.
-:class:`Unpickler` objects have one (or two) public methods:
+ :class:`Unpickler` objects have one (or two) public methods:
-.. method:: Unpickler.load()
+ .. method:: load()
- Read a pickled object representation from the open file object given in the
- constructor, and return the reconstituted object hierarchy specified therein.
+ Read a pickled object representation from the open file object given in
+ the constructor, and return the reconstituted object hierarchy specified
+ therein.
- This method automatically determines whether the data stream was written in
- binary mode or not.
+ This method automatically determines whether the data stream was written
+ in binary mode or not.
-.. method:: Unpickler.noload()
+ .. method:: noload()
- This is just like :meth:`load` except that it doesn't actually create any
- objects. This is useful primarily for finding what's called "persistent ids"
- that may be referenced in a pickle data stream. See section
- :ref:`pickle-protocol` below for more details.
+ This is just like :meth:`load` except that it doesn't actually create any
+ objects. This is useful primarily for finding what's called "persistent
+ ids" that may be referenced in a pickle data stream. See section
+ :ref:`pickle-protocol` below for more details.
- **Note:** the :meth:`noload` method is currently only available on
- :class:`Unpickler` objects created with the :mod:`cPickle` module.
- :mod:`pickle` module :class:`Unpickler`\ s do not have the :meth:`noload`
- method.
+ **Note:** the :meth:`noload` method is currently only available on
+ :class:`Unpickler` objects created with the :mod:`cPickle` module.
+ :mod:`pickle` module :class:`Unpickler`\ s do not have the :meth:`noload`
+ method.
What can be pickled and unpickled?
Modified: python/branches/py3k/Doc/library/robotparser.rst
==============================================================================
--- python/branches/py3k/Doc/library/robotparser.rst (original)
+++ python/branches/py3k/Doc/library/robotparser.rst Fri Apr 25 03:59:09 2008
@@ -25,35 +25,35 @@
single :file:`robots.txt` file.
- .. method:: RobotFileParser.set_url(url)
+ .. method:: set_url(url)
Sets the URL referring to a :file:`robots.txt` file.
- .. method:: RobotFileParser.read()
+ .. method:: read()
Reads the :file:`robots.txt` URL and feeds it to the parser.
- .. method:: RobotFileParser.parse(lines)
+ .. method:: parse(lines)
Parses the lines argument.
- .. method:: RobotFileParser.can_fetch(useragent, url)
+ .. method:: can_fetch(useragent, url)
Returns ``True`` if the *useragent* is allowed to fetch the *url* according to
the rules contained in the parsed :file:`robots.txt` file.
- .. method:: RobotFileParser.mtime()
+ .. method:: mtime()
Returns the time the ``robots.txt`` file was last fetched. This is useful for
long-running web spiders that need to check for new ``robots.txt`` files
periodically.
- .. method:: RobotFileParser.modified()
+ .. method:: modified()
Sets the time the ``robots.txt`` file was last fetched to the current time.
Modified: python/branches/py3k/Doc/library/simplehttpserver.rst
==============================================================================
--- python/branches/py3k/Doc/library/simplehttpserver.rst (original)
+++ python/branches/py3k/Doc/library/simplehttpserver.rst Fri Apr 25 03:59:09 2008
@@ -23,57 +23,59 @@
:class:`BaseHTTPServer.BaseHTTPRequestHandler`. This class implements the
:func:`do_GET` and :func:`do_HEAD` functions.
-The :class:`SimpleHTTPRequestHandler` defines the following member variables:
+ The :class:`SimpleHTTPRequestHandler` defines the following member variables:
-.. attribute:: SimpleHTTPRequestHandler.server_version
+ .. attribute:: server_version
- This will be ``"SimpleHTTP/" + __version__``, where ``__version__`` is defined
- in the module.
+ This will be ``"SimpleHTTP/" + __version__``, where ``__version__`` is
+ defined in the module.
-.. attribute:: SimpleHTTPRequestHandler.extensions_map
+ .. attribute:: extensions_map
- A dictionary mapping suffixes into MIME types. The default is signified by an
- empty string, and is considered to be ``application/octet-stream``. The mapping
- is used case-insensitively, and so should contain only lower-cased keys.
+ A dictionary mapping suffixes into MIME types. The default is signified by
+ an empty string, and is considered to be ``application/octet-stream``. The
+ mapping is used case-insensitively, and so should contain only lower-cased
+ keys.
-The :class:`SimpleHTTPRequestHandler` defines the following methods:
+ The :class:`SimpleHTTPRequestHandler` defines the following methods:
-.. method:: SimpleHTTPRequestHandler.do_HEAD()
+ .. method:: do_HEAD()
- This method serves the ``'HEAD'`` request type: it sends the headers it would
- send for the equivalent ``GET`` request. See the :meth:`do_GET` method for a
- more complete explanation of the possible headers.
+ This method serves the ``'HEAD'`` request type: it sends the headers it
+ would send for the equivalent ``GET`` request. See the :meth:`do_GET`
+ method for a more complete explanation of the possible headers.
-.. method:: SimpleHTTPRequestHandler.do_GET()
+ .. method:: do_GET()
- The request is mapped to a local file by interpreting the request as a path
- relative to the current working directory.
+ The request is mapped to a local file by interpreting the request as a
+ path relative to the current working directory.
- If the request was mapped to a directory, the directory is checked for a file
- named ``index.html`` or ``index.htm`` (in that order). If found, the file's
- contents are returned; otherwise a directory listing is generated by calling the
- :meth:`list_directory` method. This method uses :func:`os.listdir` to scan the
- directory, and returns a ``404`` error response if the :func:`listdir` fails.
+ If the request was mapped to a directory, the directory is checked for a
+ file named ``index.html`` or ``index.htm`` (in that order). If found, the
+ file's contents are returned; otherwise a directory listing is generated
+ by calling the :meth:`list_directory` method. This method uses
+ :func:`os.listdir` to scan the directory, and returns a ``404`` error
+ response if the :func:`listdir` fails.
- If the request was mapped to a file, it is opened and the contents are returned.
- Any :exc:`IOError` exception in opening the requested file is mapped to a
- ``404``, ``'File not found'`` error. Otherwise, the content type is guessed by
- calling the :meth:`guess_type` method, which in turn uses the *extensions_map*
- variable.
+ If the request was mapped to a file, it is opened and the contents are
+ returned. Any :exc:`IOError` exception in opening the requested file is
+ mapped to a ``404``, ``'File not found'`` error. Otherwise, the content
+ type is guessed by calling the :meth:`guess_type` method, which in turn
+ uses the *extensions_map* variable.
- A ``'Content-type:'`` header with the guessed content type is output, followed
- by a ``'Content-Length:'`` header with the file's size and a
- ``'Last-Modified:'`` header with the file's modification time.
+ A ``'Content-type:'`` header with the guessed content type is output,
+ followed by a ``'Content-Length:'`` header with the file's size and a
+ ``'Last-Modified:'`` header with the file's modification time.
- Then follows a blank line signifying the end of the headers, and then the
- contents of the file are output. If the file's MIME type starts with ``text/``
- the file is opened in text mode; otherwise binary mode is used.
+ Then follows a blank line signifying the end of the headers, and then the
+ contents of the file are output. If the file's MIME type starts with
+ ``text/`` the file is opened in text mode; otherwise binary mode is used.
- For example usage, see the implementation of the :func:`test` function.
+ For example usage, see the implementation of the :func:`test` function.
.. seealso::
Modified: python/branches/py3k/Doc/library/smtpd.rst
==============================================================================
--- python/branches/py3k/Doc/library/smtpd.rst (original)
+++ python/branches/py3k/Doc/library/smtpd.rst Fri Apr 25 03:59:09 2008
@@ -27,14 +27,15 @@
:mod:`asyncore`'s event loop on instantiation.
-.. method:: SMTPServer.process_message(peer, mailfrom, rcpttos, data)
+ .. method:: process_message(peer, mailfrom, rcpttos, data)
- Raise :exc:`NotImplementedError` exception. Override this in subclasses to do
- something useful with this message. Whatever was passed in the constructor as
- *remoteaddr* will be available as the :attr:`_remoteaddr` attribute. *peer* is
- the remote host's address, *mailfrom* is the envelope originator, *rcpttos* are
- the envelope recipients and *data* is a string containing the contents of the
- e-mail (which should be in :rfc:`2822` format).
+ Raise :exc:`NotImplementedError` exception. Override this in subclasses to
+ do something useful with this message. Whatever was passed in the
+ constructor as *remoteaddr* will be available as the :attr:`_remoteaddr`
+ attribute. *peer* is the remote host's address, *mailfrom* is the envelope
+ originator, *rcpttos* are the envelope recipients and *data* is a string
+ containing the contents of the e-mail (which should be in :rfc:`2822`
+ format).
DebuggingServer Objects
Modified: python/branches/py3k/Doc/library/string.rst
==============================================================================
--- python/branches/py3k/Doc/library/string.rst (original)
+++ python/branches/py3k/Doc/library/string.rst Fri Apr 25 03:59:09 2008
@@ -452,29 +452,29 @@
The constructor takes a single argument which is the template string.
-.. method:: Template.substitute(mapping[, **kws])
+ .. method:: substitute(mapping[, **kws])
- Performs the template substitution, returning a new string. *mapping* is any
- dictionary-like object with keys that match the placeholders in the template.
- Alternatively, you can provide keyword arguments, where the keywords are the
- placeholders. When both *mapping* and *kws* are given and there are duplicates,
- the placeholders from *kws* take precedence.
-
-
-.. method:: Template.safe_substitute(mapping[, **kws])
-
- Like :meth:`substitute`, except that if placeholders are missing from *mapping*
- and *kws*, instead of raising a :exc:`KeyError` exception, the original
- placeholder will appear in the resulting string intact. Also, unlike with
- :meth:`substitute`, any other appearances of the ``$`` will simply return ``$``
- instead of raising :exc:`ValueError`.
-
- While other exceptions may still occur, this method is called "safe" because
- substitutions always tries to return a usable string instead of raising an
- exception. In another sense, :meth:`safe_substitute` may be anything other than
- safe, since it will silently ignore malformed templates containing dangling
- delimiters, unmatched braces, or placeholders that are not valid Python
- identifiers.
+ Performs the template substitution, returning a new string. *mapping* is
+ any dictionary-like object with keys that match the placeholders in the
+ template. Alternatively, you can provide keyword arguments, where the
+ keywords are the placeholders. When both *mapping* and *kws* are given
+ and there are duplicates, the placeholders from *kws* take precedence.
+
+
+ .. method:: safe_substitute(mapping[, **kws])
+
+ Like :meth:`substitute`, except that if placeholders are missing from
+ *mapping* and *kws*, instead of raising a :exc:`KeyError` exception, the
+ original placeholder will appear in the resulting string intact. Also,
+ unlike with :meth:`substitute`, any other appearances of the ``$`` will
+ simply return ``$`` instead of raising :exc:`ValueError`.
+
+ While other exceptions may still occur, this method is called "safe"
+ because substitutions always tries to return a usable string instead of
+ raising an exception. In another sense, :meth:`safe_substitute` may be
+ anything other than safe, since it will silently ignore malformed
+ templates containing dangling delimiters, unmatched braces, or
+ placeholders that are not valid Python identifiers.
:class:`Template` instances also provide one public data attribute:
Modified: python/branches/py3k/Doc/library/struct.rst
==============================================================================
--- python/branches/py3k/Doc/library/struct.rst (original)
+++ python/branches/py3k/Doc/library/struct.rst Fri Apr 25 03:59:09 2008
@@ -242,37 +242,37 @@
since the format string only needs to be compiled once.
-Compiled Struct objects support the following methods and attributes:
+ Compiled Struct objects support the following methods and attributes:
-.. method:: Struct.pack(v1, v2, ...)
+ .. method:: pack(v1, v2, ...)
- Identical to the :func:`pack` function, using the compiled format.
- (``len(result)`` will equal :attr:`self.size`.)
+ Identical to the :func:`pack` function, using the compiled format.
+ (``len(result)`` will equal :attr:`self.size`.)
-.. method:: Struct.pack_into(buffer, offset, v1, v2, ...)
+ .. method:: pack_into(buffer, offset, v1, v2, ...)
- Identical to the :func:`pack_into` function, using the compiled format.
+ Identical to the :func:`pack_into` function, using the compiled format.
-.. method:: Struct.unpack(string)
+ .. method:: unpack(string)
- Identical to the :func:`unpack` function, using the compiled format.
- (``len(string)`` must equal :attr:`self.size`).
+ Identical to the :func:`unpack` function, using the compiled format.
+ (``len(string)`` must equal :attr:`self.size`).
-.. method:: Struct.unpack_from(buffer[, offset=0])
+ .. method:: unpack_from(buffer[, offset=0])
- Identical to the :func:`unpack_from` function, using the compiled format.
- (``len(buffer[offset:])`` must be at least :attr:`self.size`).
+ Identical to the :func:`unpack_from` function, using the compiled format.
+ (``len(buffer[offset:])`` must be at least :attr:`self.size`).
-.. attribute:: Struct.format
+ .. attribute:: format
- The format string used to construct this Struct object.
+ The format string used to construct this Struct object.
-.. attribute:: Struct.size
+ .. attribute:: size
- The calculated size of the struct (and hence of the string) corresponding
- to :attr:`format`.
+ The calculated size of the struct (and hence of the string) corresponding
+ to :attr:`format`.
Modified: python/branches/py3k/Doc/library/textwrap.rst
==============================================================================
--- python/branches/py3k/Doc/library/textwrap.rst (original)
+++ python/branches/py3k/Doc/library/textwrap.rst Fri Apr 25 03:59:09 2008
@@ -85,103 +85,104 @@
change any of its options through direct assignment to instance attributes
between uses.
-The :class:`TextWrapper` instance attributes (and keyword arguments to the
-constructor) are as follows:
+ The :class:`TextWrapper` instance attributes (and keyword arguments to the
+ constructor) are as follows:
-.. attribute:: TextWrapper.width
+ .. attribute:: width
- (default: ``70``) The maximum length of wrapped lines. As long as there are no
- individual words in the input text longer than :attr:`width`,
- :class:`TextWrapper` guarantees that no output line will be longer than
- :attr:`width` characters.
+ (default: ``70``) The maximum length of wrapped lines. As long as there
+ are no individual words in the input text longer than :attr:`width`,
+ :class:`TextWrapper` guarantees that no output line will be longer than
+ :attr:`width` characters.
-.. attribute:: TextWrapper.expand_tabs
+ .. attribute:: expand_tabs
- (default: ``True``) If true, then all tab characters in *text* will be expanded
- to spaces using the :meth:`expandtabs` method of *text*.
+ (default: ``True``) If true, then all tab characters in *text* will be
+ expanded to spaces using the :meth:`expandtabs` method of *text*.
-.. attribute:: TextWrapper.replace_whitespace
+ .. attribute:: replace_whitespace
- (default: ``True``) If true, each whitespace character (as defined by
- ``string.whitespace``) remaining after tab expansion will be replaced by a
- single space.
+ (default: ``True``) If true, each whitespace character (as defined by
+ ``string.whitespace``) remaining after tab expansion will be replaced by a
+ single space.
- .. note::
+ .. note::
- If :attr:`expand_tabs` is false and :attr:`replace_whitespace` is true, each tab
- character will be replaced by a single space, which is *not* the same as tab
- expansion.
+ If :attr:`expand_tabs` is false and :attr:`replace_whitespace` is true,
+ each tab character will be replaced by a single space, which is *not*
+ the same as tab expansion.
-.. attribute:: TextWrapper.drop_whitespace
+ .. attribute:: drop_whitespace
- (default: ``True``) If true, whitespace that, after wrapping, happens to end up
- at the beginning or end of a line is dropped (leading whitespace in the first
- line is always preserved, though).
+ (default: ``True``) If true, whitespace that, after wrapping, happens to
+ end up at the beginning or end of a line is dropped (leading whitespace in
+ the first line is always preserved, though).
-.. attribute:: TextWrapper.initial_indent
+ .. attribute:: initial_indent
- (default: ``''``) String that will be prepended to the first line of wrapped
- output. Counts towards the length of the first line.
+ (default: ``''``) String that will be prepended to the first line of
+ wrapped output. Counts towards the length of the first line.
-.. attribute:: TextWrapper.subsequent_indent
+ .. attribute:: subsequent_indent
- (default: ``''``) String that will be prepended to all lines of wrapped output
- except the first. Counts towards the length of each line except the first.
+ (default: ``''``) String that will be prepended to all lines of wrapped
+ output except the first. Counts towards the length of each line except
+ the first.
-.. attribute:: TextWrapper.fix_sentence_endings
+ .. attribute:: fix_sentence_endings
- (default: ``False``) If true, :class:`TextWrapper` attempts to detect sentence
- endings and ensure that sentences are always separated by exactly two spaces.
- This is generally desired for text in a monospaced font. However, the sentence
- detection algorithm is imperfect: it assumes that a sentence ending consists of
- a lowercase letter followed by one of ``'.'``, ``'!'``, or ``'?'``, possibly
- followed by one of ``'"'`` or ``"'"``, followed by a space. One problem with
- this is algorithm is that it is unable to detect the difference between "Dr." in
- ::
+ (default: ``False``) If true, :class:`TextWrapper` attempts to detect
+ sentence endings and ensure that sentences are always separated by exactly
+ two spaces. This is generally desired for text in a monospaced font.
+ However, the sentence detection algorithm is imperfect: it assumes that a
+ sentence ending consists of a lowercase letter followed by one of ``'.'``,
+ ``'!'``, or ``'?'``, possibly followed by one of ``'"'`` or ``"'"``,
+ followed by a space. One problem with this is algorithm is that it is
+ unable to detect the difference between "Dr." in ::
- [...] Dr. Frankenstein's monster [...]
+ [...] Dr. Frankenstein's monster [...]
- and "Spot." in ::
+ and "Spot." in ::
- [...] See Spot. See Spot run [...]
+ [...] See Spot. See Spot run [...]
- :attr:`fix_sentence_endings` is false by default.
+ :attr:`fix_sentence_endings` is false by default.
- Since the sentence detection algorithm relies on ``string.lowercase`` for the
- definition of "lowercase letter," and a convention of using two spaces after
- a period to separate sentences on the same line, it is specific to
- English-language texts.
+ Since the sentence detection algorithm relies on ``string.lowercase`` for
+ the definition of "lowercase letter," and a convention of using two spaces
+ after a period to separate sentences on the same line, it is specific to
+ English-language texts.
-.. attribute:: TextWrapper.break_long_words
+ .. attribute:: break_long_words
- (default: ``True``) If true, then words longer than :attr:`width` will be broken
- in order to ensure that no lines are longer than :attr:`width`. If it is false,
- long words will not be broken, and some lines may be longer than :attr:`width`.
- (Long words will be put on a line by themselves, in order to minimize the amount
- by which :attr:`width` is exceeded.)
+ (default: ``True``) If true, then words longer than :attr:`width` will be
+ broken in order to ensure that no lines are longer than :attr:`width`. If
+ it is false, long words will not be broken, and some lines may be longer
+ than :attr:`width`. (Long words will be put on a line by themselves, in
+ order to minimize the amount by which :attr:`width` is exceeded.)
-:class:`TextWrapper` also provides two public methods, analogous to the
-module-level convenience functions:
+ :class:`TextWrapper` also provides two public methods, analogous to the
+ module-level convenience functions:
-.. method:: TextWrapper.wrap(text)
+ .. method:: wrap(text)
- Wraps the single paragraph in *text* (a string) so every line is at most
- :attr:`width` characters long. All wrapping options are taken from instance
- attributes of the :class:`TextWrapper` instance. Returns a list of output lines,
- without final newlines.
+ Wraps the single paragraph in *text* (a string) so every line is at most
+ :attr:`width` characters long. All wrapping options are taken from
+ instance attributes of the :class:`TextWrapper` instance. Returns a list
+ of output lines, without final newlines.
-.. method:: TextWrapper.fill(text)
+ .. method:: fill(text)
- Wraps the single paragraph in *text*, and returns a single string containing the
- wrapped paragraph.
+ Wraps the single paragraph in *text*, and returns a single string
+ containing the wrapped paragraph.
Modified: python/branches/py3k/Doc/library/xml.etree.elementtree.rst
==============================================================================
--- python/branches/py3k/Doc/library/xml.etree.elementtree.rst (original)
+++ python/branches/py3k/Doc/library/xml.etree.elementtree.rst Fri Apr 25 03:59:09 2008
@@ -304,61 +304,63 @@
XML *file* if given.
-.. method:: ElementTree._setroot(element)
+ .. method:: _setroot(element)
- Replaces the root element for this tree. This discards the current contents of
- the tree, and replaces it with the given element. Use with care. *element* is
- an element instance.
+ Replaces the root element for this tree. This discards the current
+ contents of the tree, and replaces it with the given element. Use with
+ care. *element* is an element instance.
-.. method:: ElementTree.find(path)
+ .. method:: find(path)
- Finds the first toplevel element with given tag. Same as getroot().find(path).
- *path* is the element to look for. Returns the first matching element, or
- ``None`` if no element was found.
+ Finds the first toplevel element with given tag. Same as
+ getroot().find(path). *path* is the element to look for. Returns the
+ first matching element, or ``None`` if no element was found.
-.. method:: ElementTree.findall(path)
+ .. method:: findall(path)
- Finds all toplevel elements with the given tag. Same as getroot().findall(path).
- *path* is the element to look for. Returns a list or :term:`iterator` containing all
- matching elements, in document order.
+ Finds all toplevel elements with the given tag. Same as
+ getroot().findall(path). *path* is the element to look for. Returns a
+ list or :term:`iterator` containing all matching elements, in document
+ order.
-.. method:: ElementTree.findtext(path[, default])
+ .. method:: findtext(path[, default])
- Finds the element text for the first toplevel element with given tag. Same as
- getroot().findtext(path). *path* is the toplevel element to look for. *default*
- is the value to return if the element was not found. Returns the text content of
- the first matching element, or the default value no element was found. Note
- that if the element has is found, but has no text content, this method returns
- an empty string.
+ Finds the element text for the first toplevel element with given tag.
+ Same as getroot().findtext(path). *path* is the toplevel element to look
+ for. *default* is the value to return if the element was not
+ found. Returns the text content of the first matching element, or the
+ default value no element was found. Note that if the element has is
+ found, but has no text content, this method returns an empty string.
-.. method:: ElementTree.getiterator([tag])
+ .. method:: getiterator([tag])
- Creates and returns a tree iterator for the root element. The iterator loops
- over all elements in this tree, in section order. *tag* is the tag to look for
- (default is to return all elements)
+ Creates and returns a tree iterator for the root element. The iterator
+ loops over all elements in this tree, in section order. *tag* is the tag
+ to look for (default is to return all elements)
-.. method:: ElementTree.getroot()
+ .. method:: getroot()
- Returns the root element for this tree.
+ Returns the root element for this tree.
-.. method:: ElementTree.parse(source[, parser])
+ .. method:: parse(source[, parser])
- Loads an external XML section into this element tree. *source* is a file name or
- file object. *parser* is an optional parser instance. If not given, the
- standard XMLTreeBuilder parser is used. Returns the section root element.
+ Loads an external XML section into this element tree. *source* is a file
+ name or file object. *parser* is an optional parser instance. If not
+ given, the standard XMLTreeBuilder parser is used. Returns the section
+ root element.
-.. method:: ElementTree.write(file[, encoding])
+ .. method:: write(file[, encoding])
- Writes the element tree to a file, as XML. *file* is a file name, or a file
- object opened for writing. *encoding* [1]_ is the output encoding (default is
- US-ASCII).
+ Writes the element tree to a file, as XML. *file* is a file name, or a
+ file object opened for writing. *encoding* [1]_ is the output encoding
+ (default is US-ASCII).
This is the XML file that is going to be manipulated::
@@ -419,28 +421,28 @@
Element instances when given.
-.. method:: TreeBuilder.close()
+ .. method:: close()
- Flushes the parser buffers, and returns the toplevel document element. Returns an
- Element instance.
+ Flushes the parser buffers, and returns the toplevel document
+ element. Returns an Element instance.
-.. method:: TreeBuilder.data(data)
+ .. method:: data(data)
- Adds text to the current element. *data* is a string. This should be either an
- ASCII-only :class:`bytes` object or a :class:`str` object.
+ Adds text to the current element. *data* is a string. This should be
+ either an ASCII-only :class:`bytes` object or a :class:`str` object.
-.. method:: TreeBuilder.end(tag)
+ .. method:: end(tag)
- Closes the current element. *tag* is the element name. Returns the closed
- element.
+ Closes the current element. *tag* is the element name. Returns the closed
+ element.
-.. method:: TreeBuilder.start(tag, attrs)
+ .. method:: start(tag, attrs)
- Opens a new element. *tag* is the element name. *attrs* is a dictionary
- containing element attributes. Returns the opened element.
+ Opens a new element. *tag* is the element name. *attrs* is a dictionary
+ containing element attributes. Returns the opened element.
.. _elementtree-xmltreebuilder-objects:
@@ -457,20 +459,20 @@
instance of the standard TreeBuilder class.
-.. method:: XMLTreeBuilder.close()
+ .. method:: close()
- Finishes feeding data to the parser. Returns an element structure.
+ Finishes feeding data to the parser. Returns an element structure.
-.. method:: XMLTreeBuilder.doctype(name, pubid, system)
+ .. method:: doctype(name, pubid, system)
- Handles a doctype declaration. *name* is the doctype name. *pubid* is the public
- identifier. *system* is the system identifier.
+ Handles a doctype declaration. *name* is the doctype name. *pubid* is the
+ public identifier. *system* is the system identifier.
-.. method:: XMLTreeBuilder.feed(data)
+ .. method:: feed(data)
- Feeds data to the parser. *data* is encoded data.
+ Feeds data to the parser. *data* is encoded data.
:meth:`XMLTreeBuilder.feed` calls *target*\'s :meth:`start` method
for each opening tag, its :meth:`end` method for each closing tag,
Modified: python/branches/py3k/Doc/library/zipimport.rst
==============================================================================
--- python/branches/py3k/Doc/library/zipimport.rst (original)
+++ python/branches/py3k/Doc/library/zipimport.rst Fri Apr 25 03:59:09 2008
@@ -70,55 +70,57 @@
(provided that it exists).
-.. method:: zipimporter.find_module(fullname[, path])
+ .. method:: find_module(fullname[, path])
- Search for a module specified by *fullname*. *fullname* must be the fully
- qualified (dotted) module name. It returns the zipimporter instance itself if
- the module was found, or :const:`None` if it wasn't. The optional *path*
- argument is ignored---it's there for compatibility with the importer protocol.
+ Search for a module specified by *fullname*. *fullname* must be the fully
+ qualified (dotted) module name. It returns the zipimporter instance itself
+ if the module was found, or :const:`None` if it wasn't. The optional
+ *path* argument is ignored---it's there for compatibility with the
+ importer protocol.
-.. method:: zipimporter.get_code(fullname)
+ .. method:: get_code(fullname)
- Return the code object for the specified module. Raise :exc:`ZipImportError` if
- the module couldn't be found.
+ Return the code object for the specified module. Raise
+ :exc:`ZipImportError` if the module couldn't be found.
-.. method:: zipimporter.get_data(pathname)
+ .. method:: get_data(pathname)
- Return the data associated with *pathname*. Raise :exc:`IOError` if the file
- wasn't found.
+ Return the data associated with *pathname*. Raise :exc:`IOError` if the
+ file wasn't found.
-.. method:: zipimporter.get_source(fullname)
+ .. method:: get_source(fullname)
- Return the source code for the specified module. Raise :exc:`ZipImportError` if
- the module couldn't be found, return :const:`None` if the archive does contain
- the module, but has no source for it.
+ Return the source code for the specified module. Raise
+ :exc:`ZipImportError` if the module couldn't be found, return
+ :const:`None` if the archive does contain the module, but has no source
+ for it.
-.. method:: zipimporter.is_package(fullname)
+ .. method:: is_package(fullname)
- Return True if the module specified by *fullname* is a package. Raise
- :exc:`ZipImportError` if the module couldn't be found.
+ Return True if the module specified by *fullname* is a package. Raise
+ :exc:`ZipImportError` if the module couldn't be found.
-.. method:: zipimporter.load_module(fullname)
+ .. method:: load_module(fullname)
- Load the module specified by *fullname*. *fullname* must be the fully qualified
- (dotted) module name. It returns the imported module, or raises
- :exc:`ZipImportError` if it wasn't found.
+ Load the module specified by *fullname*. *fullname* must be the fully
+ qualified (dotted) module name. It returns the imported module, or raises
+ :exc:`ZipImportError` if it wasn't found.
-.. attribute:: zipimporter.archive
+ .. attribute:: archive
- The file name of the importer's associated ZIP file.
+ The file name of the importer's associated ZIP file.
-.. attribute:: zipimporter.prefix
+ .. attribute:: prefix
- The path within the ZIP file where modules are searched; see
- :class:`zipimporter` for details.
+ The path within the ZIP file where modules are searched; see
+ :class:`zipimporter` for details.
.. _zipimport-examples:
More information about the Python-3000-checkins
mailing list