summaryrefslogtreecommitdiffstats
path: root/Source/cmExternalMakefileProjectGenerator.cxx
blob: 5895d666e90ca9d480904b543cd919bc6b7e1875 (plain) 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

/* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
   file Copyright.txt or https://cmake.org/licensing for details.  */
#include "cmExternalMakefileProjectGenerator.h"

#include <utility>

#include "cmStringAlgorithms.h"

class cmMakefile;

void cmExternalMakefileProjectGenerator::EnableLanguage(
  std::vector<std::string> const& /*unused*/, cmMakefile* /*unused*/,
  bool /*unused*/)
{
}

std::string cmExternalMakefileProjectGenerator::CreateFullGeneratorName(
  const std::string& globalGenerator, const std::string& extraGenerator)
{
  std::string fullName;
  if (!globalGenerator.empty()) {
    if (!extraGenerator.empty()) {
      fullName = cmStrCat(extraGenerator, " - ");
    }
    fullName += globalGenerator;
  }
  return fullName;
}

bool cmExternalMakefileProjectGenerator::Open(
  const std::string& /*bindir*/, const std::string& /*projectName*/,
  bool /*dryRun*/)
{
  return false;
}

cmExternalMakefileProjectGeneratorFactory::
  cmExternalMakefileProjectGeneratorFactory(std::string n, std::string doc)
  : Name(std::move(n))
  , Documentation(std::move(doc))
{
}

cmExternalMakefileProjectGeneratorFactory::
  ~cmExternalMakefileProjectGeneratorFactory() = default;

std::string cmExternalMakefileProjectGeneratorFactory::GetName() const
{
  return this->Name;
}

std::string cmExternalMakefileProjectGeneratorFactory::GetDocumentation() const
{
  return this->Documentation;
}

std::vector<std::string>
cmExternalMakefileProjectGeneratorFactory::GetSupportedGlobalGenerators() const
{
  return this->SupportedGlobalGenerators;
}

void cmExternalMakefileProjectGeneratorFactory::AddSupportedGlobalGenerator(
  const std::string& base)
{
  this->SupportedGlobalGenerators.push_back(base);
}
generated by cgit v0.12 at 2026-02-13 17:51:26 (GMT)
d>
-rw-r--r--Doc/library/decimal.rst772
-rw-r--r--Doc/library/difflib.rst235
-rw-r--r--Doc/library/doctest.rst312
-rw-r--r--Doc/library/email.charset.rst188
-rw-r--r--Doc/library/email.generator.rst39
-rw-r--r--Doc/library/email.header.rst75
-rw-r--r--Doc/library/email.message.rst635
-rw-r--r--Doc/library/email.parser.rst59
-rw-r--r--Doc/library/filecmp.rst77
-rw-r--r--Doc/library/fractions.rst68
-rw-r--r--Doc/library/ftplib.rst29
-rw-r--r--Doc/library/gettext.rst128
-rw-r--r--Doc/library/logging.rst316
-rw-r--r--Doc/library/mailbox.rst1262
-rw-r--r--Doc/library/mmap.rst124
-rw-r--r--Doc/library/modulefinder.rst18
-rw-r--r--Doc/library/msilib.rst112
-rw-r--r--Doc/library/numbers.rst22
-rw-r--r--Doc/library/pickle.rst67
-rw-r--r--Doc/library/robotparser.rst12
-rw-r--r--Doc/library/simplehttpserver.rst68
-rw-r--r--Doc/library/smtpd.rst17
-rw-r--r--Doc/library/string.rst36
-rw-r--r--Doc/library/struct.rst34
-rw-r--r--Doc/library/textwrap.rst123
-rw-r--r--Doc/library/xml.etree.elementtree.rst106
-rw-r--r--Doc/library/zipimport.rst56
40 files changed, 3443 insertions, 3380 deletions
diff --git a/Doc/library/asynchat.rst b/Doc/library/asynchat.rst
index 8e9437d..6f15441 100644
--- a/Doc/library/asynchat.rst
+++ b/Doc/library/asynchat.rst
@@ -197,10 +197,10 @@ asynchat - Auxiliary Classes and Functions
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 @@ asynchat - Auxiliary Classes and Functions
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.
diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst
index 6830bae..7242e73 100644
--- a/Doc/library/asyncore.rst
+++ b/Doc/library/asyncore.rst
@@ -95,132 +95,132 @@ any that have been added to the map during asynchronous service) is closed.
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:
diff --git a/Doc/library/basehttpserver.rst b/Doc/library/basehttpserver.rst
index b527163..14f32e7 100644
--- a/Doc/library/basehttpserver.rst
+++ b/Doc/library/basehttpserver.rst
@@ -34,216 +34,224 @@ to a handler. Code to create and run the server looks like this::
.. 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::
diff --git a/Doc/library/bdb.rst b/Doc/library/bdb.rst
index 84ea0ae..f04b671 100644
--- a/Doc/library/bdb.rst
+++ b/Doc/library/bdb.rst
@@ -31,32 +31,35 @@ The :mod:`bdb` module also defines two classes:
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 @@ The :mod:`bdb` module also defines two classes:
(: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:
diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index ac1695b..cde5749 100644
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -44,75 +44,77 @@ Handling of compressed files is offered by the :class:`BZ2File` class.
.. 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 @@ Sequential compression and decompression is done using the classes
.. 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 @@ Sequential compression and decompression is done using the classes
: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 @@ and :func:`decompress` functions.
.. 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.
diff --git a/Doc/library/calendar.rst b/Doc/library/calendar.rst
index 33b2ad7..112a672 100644
--- a/Doc/library/calendar.rst
+++ b/Doc/library/calendar.rst
@@ -33,74 +33,75 @@ it's the base calendar for all computations.
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 @@ it's the base calendar for all computations.
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 @@ it's the base calendar for all computations.
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.
diff --git a/Doc/library/cgihttpserver.rst b/Doc/library/cgihttpserver.rst
index 4f27627..6275c1a 100644
--- a/Doc/library/cgihttpserver.rst
+++ b/Doc/library/cgihttpserver.rst
@@ -43,22 +43,22 @@ The :mod:`CGIHTTPServer` module defines the following class:
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.
diff --git a/Doc/library/chunk.rst b/Doc/library/chunk.rst
index 2e1798d..64ce4e2 100644
--- a/Doc/library/chunk.rst
+++ b/Doc/library/chunk.rst
@@ -66,62 +66,64 @@ instance will fail with a :exc:`EOFError` exception.
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
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index f00c873..2acf76b 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -425,16 +425,16 @@ define in order to be compatible with the Python codec registry.
: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 @@ define in order to be compatible with the Python codec registry.
: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 @@ compatible with the Python codec registry.
: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 @@ compatible with the Python codec registry.
: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 @@ The design is such that one can use the factory functions returned by the
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.
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index 7827700..cff07b9 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -166,59 +166,60 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
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 @@ in Unix::
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:
diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index ffdb3cb..6beadc5 100644
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -209,19 +209,20 @@ The :mod:`csv` module defines the following classes:
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::
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 7b95ba1..8d38050 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -1441,10 +1441,10 @@ loader instance.
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 @@ They are instances of a private class:
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 @@ foreign function object.
``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 @@ Data types
: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 @@ Fundamental data types
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 @@ other data types containing pointer type fields.
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_`
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
index 4135182..21c3176 100644
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -1567,92 +1567,94 @@ You can instantiate a :class:`Textbox` object as follows:
containing window, with coordinates ``(0, 0)``. The instance's
:attr:`stripspaces` flag is initially on.
-:class:`Textbox` objects have the following methods:
-
-
-.. method:: Textbox.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.
+ :class:`Textbox` objects have the following methods:
+
+
+ .. 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:: 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
diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst