wrap lines to <80 characters before fixing errors
diff --git a/Doc/library/asynchat.rst b/Doc/library/asynchat.rst
index b651c40..f870e12 100644
--- a/Doc/library/asynchat.rst
+++ b/Doc/library/asynchat.rst
@@ -9,72 +9,77 @@
This module builds on the :mod:`asyncore` infrastructure, simplifying
-asynchronous clients and servers and making it easier to handle protocols whose
-elements are terminated by arbitrary strings, or are of variable length.
+asynchronous clients and servers and making it easier to handle protocols
+whose elements are terminated by arbitrary strings, or are of variable length.
:mod:`asynchat` defines the abstract class :class:`async_chat` that you
subclass, providing implementations of the :meth:`collect_incoming_data` and
:meth:`found_terminator` methods. It uses the same asynchronous loop as
-:mod:`asyncore`, and the two types of channel, :class:`asyncore.dispatcher` and
-:class:`asynchat.async_chat`, can freely be mixed in the channel map. Typically
-an :class:`asyncore.dispatcher` server channel generates new
-:class:`asynchat.async_chat` channel objects as it receives incoming connection
-requests.
+:mod:`asyncore`, and the two types of channel, :class:`asyncore.dispatcher`
+and :class:`asynchat.async_chat`, can freely be mixed in the channel map.
+Typically an :class:`asyncore.dispatcher` server channel generates new
+:class:`asynchat.async_chat` channel objects as it receives incoming
+connection requests.
.. class:: async_chat()
This class is an abstract subclass of :class:`asyncore.dispatcher`. To make
practical use of the code you must subclass :class:`async_chat`, providing
- meaningful :meth:`collect_incoming_data` and :meth:`found_terminator` methods.
+ meaningful :meth:`collect_incoming_data` and :meth:`found_terminator`
+ methods.
The :class:`asyncore.dispatcher` methods can be used, although not all make
sense in a message/response context.
- Like :class:`asyncore.dispatcher`, :class:`async_chat` defines a set of events
- that are generated by an analysis of socket conditions after a :cfunc:`select`
- call. Once the polling loop has been started the :class:`async_chat` object's
- methods are called by the event-processing framework with no action on the part
- of the programmer.
+ Like :class:`asyncore.dispatcher`, :class:`async_chat` defines a set of
+ events that are generated by an analysis of socket conditions after a
+ :cfunc:`select` call. Once the polling loop has been started the
+ :class:`async_chat` object's methods are called by the event-processing
+ framework with no action on the part of the programmer.
- Unlike :class:`asyncore.dispatcher`, :class:`async_chat` allows you to define a
- first-in-first-out queue (fifo) of *producers*. A producer need have only one
- method, :meth:`more`, which should return data to be transmitted on the channel.
+ Unlike :class:`asyncore.dispatcher`, :class:`async_chat` allows you to
+ define a first-in-first-out queue (fifo) of *producers*. A producer need
+ have only one method, :meth:`more`, which should return data to be
+ transmitted on the channel.
The producer indicates exhaustion (*i.e.* that it contains no more data) by
having its :meth:`more` method return the empty string. At this point the
- :class:`async_chat` object removes the producer from the fifo and starts using
- the next producer, if any. When the producer fifo is empty the
+ :class:`async_chat` object removes the producer from the fifo and starts
+ using the next producer, if any. When the producer fifo is empty the
:meth:`handle_write` method does nothing. You use the channel object's
- :meth:`set_terminator` method to describe how to recognize the end of, or an
- important breakpoint in, an incoming transmission from the remote endpoint.
+ :meth:`set_terminator` method to describe how to recognize the end of, or
+ an important breakpoint in, an incoming transmission from the remote
+ endpoint.
To build a functioning :class:`async_chat` subclass your input methods
- :meth:`collect_incoming_data` and :meth:`found_terminator` must handle the data
- that the channel receives asynchronously. The methods are described below.
+ :meth:`collect_incoming_data` and :meth:`found_terminator` must handle the
+ data that the channel receives asynchronously. The methods are described
+ below.
.. method:: async_chat.close_when_done()
- Pushes a ``None`` on to the producer fifo. When this producer is popped off the
- fifo it causes the channel to be closed.
+ Pushes a ``None`` on to the producer fifo. When this producer is popped off
+ the fifo it causes the channel to be closed.
.. method:: async_chat.collect_incoming_data(data)
- Called with *data* holding an arbitrary amount of received data. The default
- method, which must be overridden, raises a :exc:`NotImplementedError` exception.
+ Called with *data* holding an arbitrary amount of received data. The
+ default method, which must be overridden, raises a
+ :exc:`NotImplementedError` exception.
.. method:: async_chat.discard_buffers()
- In emergencies this method will discard any data held in the input and/or output
- buffers and the producer fifo.
+ In emergencies this method will discard any data held in the input and/or
+ output buffers and the producer fifo.
.. method:: async_chat.found_terminator()
- Called when the incoming data stream matches the termination condition set by
- :meth:`set_terminator`. The default method, which must be overridden, raises a
- :exc:`NotImplementedError` exception. The buffered input data should be
- available via an instance attribute.
+ Called when the incoming data stream matches the termination condition set
+ by :meth:`set_terminator`. The default method, which must be overridden,
+ raises a :exc:`NotImplementedError` exception. The buffered input data
+ should be available via an instance attribute.
.. method:: async_chat.get_terminator()
@@ -90,59 +95,59 @@
.. method:: async_chat.handle_read()
- Called when a read event fires on the channel's socket in the asynchronous loop.
- The default method checks for the termination condition established by
- :meth:`set_terminator`, which can be either the appearance of a particular
- string in the input stream or the receipt of a particular number of characters.
- When the terminator is found, :meth:`handle_read` calls the
- :meth:`found_terminator` method after calling :meth:`collect_incoming_data` with
- any data preceding the terminating condition.
+ Called when a read event fires on the channel's socket in the asynchronous
+ loop. The default method checks for the termination condition established
+ by :meth:`set_terminator`, which can be either the appearance of a
+ particular string in the input stream or the receipt of a particular number
+ of characters. When the terminator is found, :meth:`handle_read` calls the
+ :meth:`found_terminator` method after calling :meth:`collect_incoming_data`
+ with any data preceding the terminating condition.
.. method:: async_chat.handle_write()
- Called when the application may write data to the channel. The default method
- calls the :meth:`initiate_send` method, which in turn will call
- :meth:`refill_buffer` to collect data from the producer fifo associated with the
- channel.
+ Called when the application may write data to the channel. The default
+ method calls the :meth:`initiate_send` method, which in turn will call
+ :meth:`refill_buffer` to collect data from the producer fifo associated
+ with the channel.
.. method:: async_chat.push(data)
- Creates a :class:`simple_producer` object (*see below*) containing the data and
- pushes it on to the channel's ``producer_fifo`` to ensure its transmission. This
- is all you need to do to have the channel write the data out to the network,
- although it is possible to use your own producers in more complex schemes to
- implement encryption and chunking, for example.
+ Creates a :class:`simple_producer` object (*see below*) containing the data
+ and pushes it on to the channel's ``producer_fifo`` to ensure its
+ transmission. This is all you need to do to have the channel write the
+ data out to the network, although it is possible to use your own producers
+ in more complex schemes to implement encryption and chunking, for example.
.. method:: async_chat.push_with_producer(producer)
- Takes a producer object and adds it to the producer fifo associated with the
- channel. When all currently-pushed producers have been exhausted the channel
- will consume this producer's data by calling its :meth:`more` method and send
- the data to the remote endpoint.
+ Takes a producer object and adds it to the producer fifo associated with
+ the channel. When all currently-pushed producers have been exhausted the
+ channel will consume this producer's data by calling its :meth:`more`
+ method and send the data to the remote endpoint.
.. method:: async_chat.readable()
- Should return ``True`` for the channel to be included in the set of channels
- tested by the :cfunc:`select` loop for readability.
+ Should return ``True`` for the channel to be included in the set of
+ channels tested by the :cfunc:`select` loop for readability.
.. method:: async_chat.refill_buffer()
- Refills the output buffer by calling the :meth:`more` method of the producer at
- the head of the fifo. If it is exhausted then the producer is popped off the
- fifo and the next producer is activated. If the current producer is, or becomes,
- ``None`` then the channel is closed.
+ Refills the output buffer by calling the :meth:`more` method of the
+ producer at the head of the fifo. If it is exhausted then the producer is
+ popped off the fifo and the next producer is activated. If the current
+ producer is, or becomes, ``None`` then the channel is closed.
.. method:: async_chat.set_terminator(term)
- Sets the terminating condition to be recognised on the channel. ``term`` may be
- any of three types of value, corresponding to three different ways to handle
- incoming protocol data.
+ Sets the terminating condition to be recognized on the channel. ``term``
+ may be any of three types of value, corresponding to three different ways
+ to handle incoming protocol data.
+-----------+---------------------------------------------+
| term | Description |
@@ -158,8 +163,8 @@
| | forever |
+-----------+---------------------------------------------+
- Note that any data following the terminator will be available for reading by the
- channel after :meth:`found_terminator` is called.
+ Note that any data following the terminator will be available for reading
+ by the channel after :meth:`found_terminator` is called.
.. method:: async_chat.writable()
@@ -174,29 +179,29 @@
.. class:: simple_producer(data[, buffer_size=512])
- A :class:`simple_producer` takes a chunk of data and an optional buffer size.
- Repeated calls to its :meth:`more` method yield successive chunks of the data no
- larger than *buffer_size*.
+ A :class:`simple_producer` takes a chunk of data and an optional buffer
+ size. Repeated calls to its :meth:`more` method yield successive chunks of
+ the data no larger than *buffer_size*.
.. method:: simple_producer.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])
- Each channel maintains a :class:`fifo` holding data which has been pushed by the
- application but not yet popped for writing to the channel. A :class:`fifo` is a
- list used to hold data and/or producers until they are required. If the *list*
- argument is provided then it should contain producers or data items to be
- written to the channel.
+ Each channel maintains a :class:`fifo` holding data which has been pushed
+ by the application but not yet popped for writing to the channel. A
+ :class:`fifo` is a list used to hold data and/or producers until they are
+ required. If the *list* argument is provided then it should contain
+ producers or data items to be written to the channel.
.. method:: fifo.is_empty()
- Returns ``True`` iff the fifo is empty.
+ Returns ``True`` if and only if the fifo is empty.
.. method:: fifo.first()
@@ -206,14 +211,14 @@
.. method:: fifo.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()
- 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.
@@ -221,8 +226,8 @@
.. function:: find_prefix_at_end(haystack, needle)
- Returns ``True`` if string *haystack* ends with any non-empty prefix of string
- *needle*.
+ Returns ``True`` if string *haystack* ends with any non-empty prefix of
+ string *needle*.
.. _asynchat-example:
@@ -231,19 +236,20 @@
----------------
The following partial example shows how HTTP requests can be read with
-:class:`async_chat`. A web server might create an :class:`http_request_handler`
-object for each incoming client connection. Notice that initially the channel
-terminator is set to match the blank line at the end of the HTTP headers, and a
-flag indicates that the headers are being read.
+:class:`async_chat`. A web server might create an
+:class:`http_request_handler` object for each incoming client connection.
+Notice that initially the channel terminator is set to match the blank line at
+the end of the HTTP headers, and a flag indicates that the headers are being
+read.
-Once the headers have been read, if the request is of type POST (indicating that
-further data are present in the input stream) then the ``Content-Length:``
-header is used to set a numeric terminator to read the right amount of data from
-the channel.
+Once the headers have been read, if the request is of type POST (indicating
+that further data are present in the input stream) then the
+``Content-Length:`` header is used to set a numeric terminator to read the
+right amount of data from the channel.
The :meth:`handle_request` method is called once all relevant input has been
-marshalled, after setting the channel terminator to ``None`` to ensure that any
-extraneous data sent by the web client are ignored. ::
+marshalled, after setting the channel terminator to ``None`` to ensure that
+any extraneous data sent by the web client are ignored. ::
class http_request_handler(asynchat.async_chat):
@@ -281,4 +287,3 @@
self.handling = True
self.ibuffer = []
self.handle_request()
-