Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r70712 | benjamin.peterson | 2009-03-30 10:15:38 -0500 (Mon, 30 Mar 2009) | 1 line

  don't rely on the order dict repr #5605
........
  r70714 | brett.cannon | 2009-03-30 10:20:53 -0500 (Mon, 30 Mar 2009) | 1 line

  Add an entry to developers.txt.
........
  r70764 | martin.v.loewis | 2009-03-30 17:06:33 -0500 (Mon, 30 Mar 2009) | 2 lines

  Add several VM developers.
........
  r70765 | georg.brandl | 2009-03-30 17:09:34 -0500 (Mon, 30 Mar 2009) | 1 line

  #5199: make warning about vars() assignment more visible.
........
  r70769 | andrew.kuchling | 2009-03-30 17:29:53 -0500 (Mon, 30 Mar 2009) | 1 line

  Remove comment
........
  r70770 | andrew.kuchling | 2009-03-30 17:30:20 -0500 (Mon, 30 Mar 2009) | 1 line

  Add several items and placeholders
........
  r70771 | andrew.kuchling | 2009-03-30 17:31:11 -0500 (Mon, 30 Mar 2009) | 1 line

  Many edits
........
  r70773 | georg.brandl | 2009-03-30 17:43:00 -0500 (Mon, 30 Mar 2009) | 1 line

  #5039: make it clear that the impl. note refers to CPython.
........
  r70776 | andrew.kuchling | 2009-03-30 18:08:24 -0500 (Mon, 30 Mar 2009) | 1 line

  typo fix
........
  r70777 | andrew.kuchling | 2009-03-30 18:09:46 -0500 (Mon, 30 Mar 2009) | 1 line

  Add more items
........
  r70788 | andrew.kuchling | 2009-03-30 20:21:01 -0500 (Mon, 30 Mar 2009) | 1 line

  Add various items
........
  r70789 | georg.brandl | 2009-03-30 20:25:15 -0500 (Mon, 30 Mar 2009) | 1 line

  Fix a wrong struct field assignment (docstring as closure).
........
  r70824 | georg.brandl | 2009-03-31 10:43:20 -0500 (Tue, 31 Mar 2009) | 1 line

  #5519: remove reference to Kodos, which seems dead.
........
  r70828 | georg.brandl | 2009-03-31 10:50:16 -0500 (Tue, 31 Mar 2009) | 1 line

  #5581: fget argument of abstractproperty is optional as well.
........
  r70832 | georg.brandl | 2009-03-31 11:31:11 -0500 (Tue, 31 Mar 2009) | 1 line

  #1386675: specify WindowsError as the exception, because it has a winerror attribute that EnvironmentError doesnt have.
........
  r70836 | georg.brandl | 2009-03-31 11:50:25 -0500 (Tue, 31 Mar 2009) | 1 line

  #5417: replace references to undocumented functions by ones to documented functions.
........
  r70842 | georg.brandl | 2009-03-31 12:13:06 -0500 (Tue, 31 Mar 2009) | 1 line

  #970783: document PyObject_Generic[GS]etAttr.
........
  r70851 | georg.brandl | 2009-03-31 13:26:55 -0500 (Tue, 31 Mar 2009) | 1 line

  #837577: note cryptic return value of spawn*e on invalid env dicts.
........
  r70855 | georg.brandl | 2009-03-31 13:30:37 -0500 (Tue, 31 Mar 2009) | 1 line

  #5245: note that PyRun_SimpleString doesnt return on SystemExit.
........
  r70857 | georg.brandl | 2009-03-31 13:33:10 -0500 (Tue, 31 Mar 2009) | 1 line

  #5227: note that Py_Main doesnt return on SystemExit.
........
  r70866 | georg.brandl | 2009-03-31 14:06:57 -0500 (Tue, 31 Mar 2009) | 1 line

  #4882: document named group behavior a bit better.
........
  r70867 | georg.brandl | 2009-03-31 14:10:35 -0500 (Tue, 31 Mar 2009) | 1 line

  #1096310: document usage of sys.__std*__ a bit better.
........
  r70868 | georg.brandl | 2009-03-31 14:12:17 -0500 (Tue, 31 Mar 2009) | 1 line

  #5190: export make_option in __all__.
........
  r70869 | georg.brandl | 2009-03-31 14:14:42 -0500 (Tue, 31 Mar 2009) | 1 line

  Fix-up unwanted change.
........
  r70870 | georg.brandl | 2009-03-31 14:26:24 -0500 (Tue, 31 Mar 2009) | 1 line

  #4411: document mro() and __mro__. (I hope I got it right.)
........
  r70871 | georg.brandl | 2009-03-31 14:30:56 -0500 (Tue, 31 Mar 2009) | 1 line

  #5618: fix typo.
........
  r70872 | r.david.murray | 2009-03-31 14:31:17 -0500 (Tue, 31 Mar 2009) | 3 lines

  Delete out-of-date and little-known README from the test
  directory by consensus of devs at pycon sprint.
........
  r70883 | georg.brandl | 2009-03-31 15:41:08 -0500 (Tue, 31 Mar 2009) | 1 line

  #1674032: return value of flag from Event.wait(). OKed by Guido.
........
  r70885 | tarek.ziade | 2009-03-31 15:48:31 -0500 (Tue, 31 Mar 2009) | 1 line

  using log.warn for sys.stderr
........
  r70893 | georg.brandl | 2009-03-31 15:56:32 -0500 (Tue, 31 Mar 2009) | 1 line

  #1530012: move TQS section before raw strings.
........
  r70894 | benjamin.peterson | 2009-03-31 16:06:30 -0500 (Tue, 31 Mar 2009) | 1 line

  take the usual lock precautions around _active_limbo_lock
........
  r70896 | georg.brandl | 2009-03-31 16:15:33 -0500 (Tue, 31 Mar 2009) | 1 line

  #5598: document DocFileSuite *args argument.
........
  r70897 | benjamin.peterson | 2009-03-31 16:34:42 -0500 (Tue, 31 Mar 2009) | 1 line

  fix Thread.ident when it is the main thread or a dummy thread #5632
........
  r70903 | georg.brandl | 2009-03-31 16:45:18 -0500 (Tue, 31 Mar 2009) | 1 line

  #1676135: remove trailing slashes from --prefix argument.
........
  r70905 | georg.brandl | 2009-03-31 17:03:40 -0500 (Tue, 31 Mar 2009) | 1 line

  #5563: more documentation for bdist_msi.
........
  r70906 | georg.brandl | 2009-03-31 17:11:53 -0500 (Tue, 31 Mar 2009) | 1 line

  #1651995: fix _convert_ref for non-ASCII characters.
........
  r70907 | georg.brandl | 2009-03-31 17:18:19 -0500 (Tue, 31 Mar 2009) | 1 line

  #3427: document correct return type for urlopen().info().
........
  r70915 | georg.brandl | 2009-03-31 17:40:16 -0500 (Tue, 31 Mar 2009) | 1 line

  #5018: remove confusing paragraph.
........
  r70927 | georg.brandl | 2009-03-31 18:01:27 -0500 (Tue, 31 Mar 2009) | 1 line

  Dont shout to users.
........
  r70933 | georg.brandl | 2009-03-31 19:04:33 -0500 (Tue, 31 Mar 2009) | 2 lines

  Issue #5635: Fix running test_sys with tracing enabled.
........
  r70951 | georg.brandl | 2009-04-01 09:02:27 -0500 (Wed, 01 Apr 2009) | 1 line

  Add Maksim, who worked on several issues at the sprint.
........
  r70960 | jesse.noller | 2009-04-01 11:42:19 -0500 (Wed, 01 Apr 2009) | 1 line

  Issue 3270: document Listener address restrictions on windows
........
  r70962 | brett.cannon | 2009-04-01 12:07:16 -0500 (Wed, 01 Apr 2009) | 2 lines

  Ron DuPlain was given commit privileges at PyCon 2009 to work on 3to2.
........
  r70963 | georg.brandl | 2009-04-01 12:46:01 -0500 (Wed, 01 Apr 2009) | 1 line

  #5655: fix docstring oversight.
........
  r70964 | brett.cannon | 2009-04-01 12:52:13 -0500 (Wed, 01 Apr 2009) | 2 lines

  Paul Kippes was given commit privileges to work on 3to2.
........
  r70998 | georg.brandl | 2009-04-01 16:54:21 -0500 (Wed, 01 Apr 2009) | 1 line

  In Pdb, stop assigning values to __builtin__._ which interferes with the one commonly installed by gettext.
........
  r71001 | brett.cannon | 2009-04-01 18:01:12 -0500 (Wed, 01 Apr 2009) | 3 lines

  Add my initials to Misc/developers.txt. Names are now sorted by number of
  characters in the person's name.
........
  r71006 | georg.brandl | 2009-04-01 18:32:17 -0500 (Wed, 01 Apr 2009) | 1 line

  Cache the f_locals dict of the current frame, since every access to frame.f_locals overrides its contents with the real locals which undoes modifications made by the debugging user.
........
  r71008 | andrew.kuchling | 2009-04-01 19:02:14 -0500 (Wed, 01 Apr 2009) | 1 line

  Typo fix
........
  r71010 | benjamin.peterson | 2009-04-01 19:11:52 -0500 (Wed, 01 Apr 2009) | 1 line

  fix markup
........
  r71011 | benjamin.peterson | 2009-04-01 19:12:47 -0500 (Wed, 01 Apr 2009) | 1 line

  this should be :noindex:
........
  r71019 | georg.brandl | 2009-04-01 21:00:01 -0500 (Wed, 01 Apr 2009) | 1 line

  Fix test_doctest, missed two assignments to curframe.
........
  r71037 | r.david.murray | 2009-04-01 23:34:04 -0500 (Wed, 01 Apr 2009) | 6 lines

  Clarify that datetime strftime does not produce leap seconds and datetime
  strptime does not accept it in the strftime behavior section of the
  datetime docs.

  Closes issue 2568.
........
  r71056 | georg.brandl | 2009-04-02 12:43:07 -0500 (Thu, 02 Apr 2009) | 2 lines

  Actually the displayhook should print the repr.
........
  r71094 | vinay.sajip | 2009-04-03 05:23:18 -0500 (Fri, 03 Apr 2009) | 1 line

  Added warning about logging use from asynchronous signal handlers.
........
  r71101 | andrew.kuchling | 2009-04-03 16:43:00 -0500 (Fri, 03 Apr 2009) | 1 line

  Add some items
........
  r71102 | andrew.kuchling | 2009-04-03 16:44:49 -0500 (Fri, 03 Apr 2009) | 1 line

  Fix 'the the'; grammar fix
........
  r71103 | andrew.kuchling | 2009-04-03 16:45:29 -0500 (Fri, 03 Apr 2009) | 1 line

  Fix 'the the' duplication
........
  r71106 | vinay.sajip | 2009-04-03 16:58:16 -0500 (Fri, 03 Apr 2009) | 1 line

  Clarified warning about logging use from asynchronous signal handlers.
........
  r71119 | raymond.hettinger | 2009-04-04 00:37:47 -0500 (Sat, 04 Apr 2009) | 1 line

  Add helpful link.
........
  r71123 | r.david.murray | 2009-04-04 01:39:56 -0500 (Sat, 04 Apr 2009) | 2 lines

  Fix error in description of 'oct' (issue 5678).
........
  r71149 | georg.brandl | 2009-04-04 08:42:39 -0500 (Sat, 04 Apr 2009) | 1 line

  #5642: clarify map() compatibility to the builtin.
........
  r71150 | georg.brandl | 2009-04-04 08:45:49 -0500 (Sat, 04 Apr 2009) | 1 line

  #5601: clarify that webbrowser is not meant for file names.
........
  r71203 | benjamin.peterson | 2009-04-04 18:46:34 -0500 (Sat, 04 Apr 2009) | 1 line

  note how using iter* are unsafe while mutating and document iter(dict)
........
  r71212 | georg.brandl | 2009-04-05 05:24:20 -0500 (Sun, 05 Apr 2009) | 1 line

  #1742837: expand HTTP server docs, and fix SocketServer ones to document methods as methods, not functions.
........
  r71214 | georg.brandl | 2009-04-05 05:29:57 -0500 (Sun, 05 Apr 2009) | 1 line

  Normalize spelling of Mac OS X.
........
  r71215 | georg.brandl | 2009-04-05 05:32:26 -0500 (Sun, 05 Apr 2009) | 1 line

  Avoid sure signs of a diseased mind.
........
  r71216 | georg.brandl | 2009-04-05 05:41:02 -0500 (Sun, 05 Apr 2009) | 1 line

  #1718017: document the relation of os.path and the posixpath, ntpath etc. modules better.
........
  r71217 | georg.brandl | 2009-04-05 05:48:47 -0500 (Sun, 05 Apr 2009) | 1 line

  #1726172: dont raise an unexpected IndexError if a voidresp() call has an empty response.
........
  r71221 | vinay.sajip | 2009-04-05 06:06:24 -0500 (Sun, 05 Apr 2009) | 1 line

  Issue #5695: Moved logging.captureWarnings() call inside with statement in WarningsTest.test_warnings.
........
  r71240 | georg.brandl | 2009-04-05 09:40:06 -0500 (Sun, 05 Apr 2009) | 1 line

  #5370: doc update about unpickling objects with custom __getattr__ etc. methods.
........

1 files changed, 35 insertions, 26 deletions

diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst
index f82f538..9e0e926 100644
--- a/Doc/library/socketserver.rst
+++ b/Doc/library/socketserver.rst
@@ -122,15 +122,21 @@ another way to manage this.
 Server Objects
 --------------
 
+.. class:: BaseServer
 
-.. function:: fileno()
+   This is the superclass of all Server objects in the module.  It defines the
+   interface, given below, but does not implement most of the methods, which is
+   done in subclasses.
+
+
+.. method:: BaseServer.fileno()
 
    Return an integer file descriptor for the socket on which the server is
    listening.  This function is most commonly passed to :func:`select.select`, to
    allow monitoring multiple servers in the same process.
 
 
-.. function:: handle_request()
+.. method:: BaseServer.handle_request()
 
    Process a single request.  This function calls the following methods in
    order: :meth:`get_request`, :meth:`verify_request`, and
@@ -141,30 +147,30 @@ Server Objects
    will return.
 
 
-.. function:: serve_forever(poll_interval=0.5)
+.. method:: BaseServer.serve_forever(poll_interval=0.5)
 
    Handle requests until an explicit :meth:`shutdown` request.  Polls for
    shutdown every *poll_interval* seconds.
 
 
-.. function:: shutdown()
+.. method:: BaseServer.shutdown()
 
    Tells the :meth:`serve_forever` loop to stop and waits until it does.
 
 
-.. data:: address_family
+.. attribute:: BaseServer.address_family
 
    The family of protocols to which the server's socket belongs.
    Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`.
 
 
-.. data:: RequestHandlerClass
+.. attribute:: BaseServer.RequestHandlerClass
 
    The user-provided request handler class; an instance of this class is created
    for each request.
 
 
-.. data:: server_address
+.. attribute:: BaseServer.server_address
 
    The address on which the server is listening.  The format of addresses varies
    depending on the protocol family; see the documentation for the socket module
@@ -172,22 +178,22 @@ Server Objects
    the address, and an integer port number: ``('127.0.0.1', 80)``, for example.
 
 
-.. data:: socket
+.. attribute:: BaseServer.socket
 
    The socket object on which the server will listen for incoming requests.
 
+
 The server classes support the following class variables:
 
 .. XXX should class variables be covered before instance variables, or vice versa?
 
-
-.. data:: allow_reuse_address
+.. attribute:: BaseServer.allow_reuse_address
 
    Whether the server will allow the reuse of an address. This defaults to
    :const:`False`, and can be set in subclasses to change the policy.
 
 
-.. data:: request_queue_size
+.. attribute:: BaseServer.request_queue_size
 
    The size of the request queue.  If it takes a long time to process a single
    request, any requests that arrive while the server is busy are placed into a
@@ -196,17 +202,19 @@ The server classes support the following class variables:
    value is usually 5, but this can be overridden by subclasses.
 
 
-.. data:: socket_type
+.. attribute:: BaseServer.socket_type
 
    The type of socket used by the server; :const:`socket.SOCK_STREAM` and
    :const:`socket.SOCK_DGRAM` are two common values.
 
-.. data:: timeout
+
+.. attribute:: BaseServer.timeout
 
    Timeout duration, measured in seconds, or :const:`None` if no timeout is
    desired.  If :meth:`handle_request` receives no incoming requests within the
    timeout period, the :meth:`handle_timeout` method is called.
 
+
 There are various server methods that can be overridden by subclasses of base
 server classes like :class:`TCPServer`; these methods aren't useful to external
 users of the server object.
@@ -214,27 +222,27 @@ users of the server object.
 .. XXX should the default implementations of these be documented, or should
    it be assumed that the user will look at socketserver.py?
 
-
-.. function:: finish_request()
+.. method:: BaseServer.finish_request()
 
    Actually processes the request by instantiating :attr:`RequestHandlerClass` and
    calling its :meth:`handle` method.
 
 
-.. function:: get_request()
+.. method:: BaseServer.get_request()
 
    Must accept a request from the socket, and return a 2-tuple containing the *new*
    socket object to be used to communicate with the client, and the client's
    address.
 
 
-.. function:: handle_error(request, client_address)
+.. method:: BaseServer.handle_error(request, client_address)
 
    This function is called if the :attr:`RequestHandlerClass`'s :meth:`handle`
    method raises an exception.  The default action is to print the traceback to
    standard output and continue handling further requests.
 
-.. function:: handle_timeout()
+
+.. method:: BaseServer.handle_timeout()
 
    This function is called when the :attr:`timeout` attribute has been set to a
    value other than :const:`None` and the timeout period has passed with no
@@ -242,31 +250,32 @@ users of the server object.
    to collect the status of any child processes that have exited, while
    in threading servers this method does nothing.
 
-.. function:: process_request(request, client_address)
+
+.. method:: BaseServer.process_request(request, client_address)
 
    Calls :meth:`finish_request` to create an instance of the
    :attr:`RequestHandlerClass`.  If desired, this function can create a new process
    or thread to handle the request; the :class:`ForkingMixIn` and
    :class:`ThreadingMixIn` classes do this.
 
+
 .. Is there any point in documenting the following two functions?
    What would the purpose of overriding them be: initializing server
    instance variables, adding new network families?
 
-
-.. function:: server_activate()
+.. method:: BaseServer.server_activate()
 
    Called by the server's constructor to activate the server.  The default behavior
    just :meth:`listen`\ s to the server's socket. May be overridden.
 
 
-.. function:: server_bind()
+.. method:: BaseServer.server_bind()
 
    Called by the server's constructor to bind the socket to the desired address.
    May be overridden.
 
 
-.. function:: verify_request(request, client_address)
+.. method:: BaseServer.verify_request(request, client_address)
 
    Must return a Boolean value; if the value is :const:`True`, the request will be
    processed, and if it's :const:`False`, the request will be denied. This function
@@ -282,14 +291,14 @@ override any of the following methods.  A new instance is created for each
 request.
 
 
-.. function:: finish()
+.. method:: RequestHandler.finish()
 
    Called after the :meth:`handle` method to perform any clean-up actions
    required.  The default implementation does nothing.  If :meth:`setup` or
    :meth:`handle` raise an exception, this function will not be called.
 
 
-.. function:: handle()
+.. method:: RequestHandler.handle()
 
    This function must do all the work required to service a request.  The
    default implementation does nothing.  Several instance attributes are
@@ -308,7 +317,7 @@ request.
    data or return data to the client.
 
 
-.. function:: setup()
+.. method:: RequestHandler.setup()
 
    Called before the :meth:`handle` method to perform any initialization actions
    required.  The default implementation does nothing.