Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71058 | georg.brandl | 2009-04-02 20:09:04 +0200 (Do, 02 Apr 2009) | 3 lines
PyErr_NormalizeException may not set an error, so convert the PyErr_SetObject
call on hitting the recursion limit into just assigning it to the arguments provided.
........
r71149 | georg.brandl | 2009-04-04 15:42:39 +0200 (Sa, 04 Apr 2009) | 1 line
#5642: clarify map() compatibility to the builtin.
........
r71150 | georg.brandl | 2009-04-04 15:45:49 +0200 (Sa, 04 Apr 2009) | 1 line
#5601: clarify that webbrowser is not meant for file names.
........
r71212 | georg.brandl | 2009-04-05 12:24:20 +0200 (So, 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 12:29:57 +0200 (So, 05 Apr 2009) | 1 line
Normalize spelling of Mac OS X.
........
r71215 | georg.brandl | 2009-04-05 12:32:26 +0200 (So, 05 Apr 2009) | 1 line
Avoid sure signs of a diseased mind.
........
r71216 | georg.brandl | 2009-04-05 12:41:02 +0200 (So, 05 Apr 2009) | 1 line
#1718017: document the relation of os.path and the posixpath, ntpath etc. modules better.
........
r71222 | georg.brandl | 2009-04-05 13:07:14 +0200 (So, 05 Apr 2009) | 1 line
#5615: make it possible to configure --without-threads again.
........
r71225 | georg.brandl | 2009-04-05 13:54:07 +0200 (So, 05 Apr 2009) | 1 line
#5580: no need to use parentheses when converterr() argument is actually a type description.
........
r71234 | georg.brandl | 2009-04-05 15:16:35 +0200 (So, 05 Apr 2009) | 1 line
Whitespace normalization.
........
r71237 | georg.brandl | 2009-04-05 16:24:52 +0200 (So, 05 Apr 2009) | 1 line
#1326077: fix traceback formatting of SyntaxErrors. This fixes two differences with formatting coming from Python: a) the reproduction of location details in the error message if no line text is given, b) the prefixing of the last line by one space.
........
r71238 | georg.brandl | 2009-04-05 16:25:41 +0200 (So, 05 Apr 2009) | 1 line
Add NEWS entry for r71237.
........
r71240 | georg.brandl | 2009-04-05 16:40:06 +0200 (So, 05 Apr 2009) | 1 line
#5370: doc update about unpickling objects with custom __getattr__ etc. methods.
........
r71241 | georg.brandl | 2009-04-05 16:48:49 +0200 (So, 05 Apr 2009) | 1 line
#5471: fix expanduser() for $HOME set to "/".
........
r71243 | georg.brandl | 2009-04-05 17:14:29 +0200 (So, 05 Apr 2009) | 1 line
#5432: make plistlib docstring a raw string, since it contains examples with backslash escapes.
........
r71249 | georg.brandl | 2009-04-05 18:30:43 +0200 (So, 05 Apr 2009) | 1 line
#5444: adapt make.bat to new htmlhelp output file name.
........
r71251 | georg.brandl | 2009-04-05 19:17:42 +0200 (So, 05 Apr 2009) | 1 line
#5298: clarify docs about GIL by using more consistent wording.
........
diff --git a/Doc/library/_winreg.rst b/Doc/library/_winreg.rst
index e9c0fa7..7876f85 100644
--- a/Doc/library/_winreg.rst
+++ b/Doc/library/_winreg.rst
@@ -252,9 +252,10 @@
associated. If this parameter is ``None`` or empty, the function retrieves the
value set by the :func:`SetValue` method for the key identified by *key*.
- Values in the registry have name, type, and data components. This method
+ Values in the registry have name, type, and data components. This method
retrieves the data for a key's first value that has a NULL name. But the
- underlying API call doesn't return the type, Lame Lame Lame, DO NOT USE THIS!!!
+ underlying API call doesn't return the type, so always use
+ :func:`QueryValueEx` if possible.
.. function:: QueryValueEx(key, value_name)
diff --git a/Doc/library/basehttpserver.rst b/Doc/library/basehttpserver.rst
index 64446f4..4662b4f 100644
--- a/Doc/library/basehttpserver.rst
+++ b/Doc/library/basehttpserver.rst
@@ -15,8 +15,6 @@
pair: HTTP; protocol
single: URL
single: httpd
-
-.. index::
module: SimpleHTTPServer
module: CGIHTTPServer
@@ -26,7 +24,8 @@
:mod:`CGIHTTPServer` modules.
The first class, :class:`HTTPServer`, is a :class:`SocketServer.TCPServer`
-subclass. It creates and listens at the HTTP socket, dispatching the requests
+subclass, and therefore implements the :class:`SocketServer.BaseServer`
+interface. It creates and listens at the HTTP socket, dispatching the requests
to a handler. Code to create and run the server looks like this::
def run(server_class=BaseHTTPServer.HTTPServer,
@@ -269,12 +268,31 @@
performed on the client's IP address.
+More examples
+-------------
+
+To create a server that doesn't run forever, but until some condition is
+fulfilled::
+
+ def run_while_true(server_class=BaseHTTPServer.HTTPServer,
+ handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
+ """
+ This assumes that keep_running() is a function of no arguments which
+ is tested initially and after each request. If its return value
+ is true, the server continues.
+ """
+ server_address = ('', 8000)
+ httpd = server_class(server_address, handler_class)
+ while keep_running():
+ httpd.handle_request()
+
+
.. seealso::
Module :mod:`CGIHTTPServer`
Extended request handler that supports CGI scripts.
Module :mod:`SimpleHTTPServer`
- Basic request handler that limits response to files actually under the document
- root.
+ Basic request handler that limits response to files actually under the
+ document root.
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index f6e223a..d39e649 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -1537,8 +1537,8 @@
.. method:: map(func, iterable[, chunksize])
- A parallel equivalent of the :func:`map` builtin function. It blocks till
- the result is ready.
+ A parallel equivalent of the :func:`map` builtin function (it supports only
+ one *iterable* argument though). It blocks till the result is ready.
This method chops the iterable into a number of chunks which it submits to
the process pool as separate tasks. The (approximate) size of these
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index bc2220d..0e7f376 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -1,11 +1,9 @@
-
:mod:`os.path` --- Common pathname manipulations
================================================
.. module:: os.path
:synopsis: Operations on pathnames.
-
.. index:: single: path; operations
This module implements some useful functions on pathnames. To read or
@@ -18,6 +16,22 @@
:func:`splitunc` and :func:`ismount` do handle them correctly.
+.. note::
+
+ Since different operating systems have different path name conventions, there
+ are several versions of this module in the standard library. The
+ :mod:`os.path` module is always the path module suitable for the operating
+ system Python is running on, and therefore usable for local paths. However,
+ you can also import and use the individual modules if you want to manipulate
+ a path that is *always* in one of the different formats. They all have the
+ same interface:
+
+ * :mod:`posixpath` for UNIX-style paths
+ * :mod:`ntpath` for Windows paths
+ * :mod:`macpath` for old-style MacOS paths
+ * :mod:`os2emxpath` for OS/2 EMX paths
+
+
.. function:: abspath(path)
Return a normalized absolutized version of the pathname *path*. On most
@@ -190,9 +204,9 @@
.. function:: normcase(path)
- Normalize the case of a pathname. On Unix and MacOSX, this returns the path unchanged; on
- case-insensitive filesystems, it converts the path to lowercase. On Windows, it
- also converts forward slashes to backward slashes.
+ Normalize the case of a pathname. On Unix and Mac OS X, this returns the
+ path unchanged; on case-insensitive filesystems, it converts the path to
+ lowercase. On Windows, it also converts forward slashes to backward slashes.
.. function:: normpath(path)
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 309fac2..4d8fc4c 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -46,15 +46,6 @@
``'ce'``, ``'java'``, ``'riscos'``.
-.. data:: path
-
- The corresponding operating system dependent standard module for pathname
- operations, such as :mod:`posixpath` or :mod:`ntpath`. Thus, given the proper
- imports, ``os.path.split(file)`` is equivalent to but more portable than
- ``posixpath.split(file)``. Note that this is also an importable module: it may
- be imported directly as :mod:`os.path`.
-
-
.. _os-procinfo:
Process Parameters
diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index a99dc86..f6b7ae4 100644
--- a/Doc/library/pickle.rst
+++ b/Doc/library/pickle.rst
@@ -458,6 +458,15 @@
For :term:`new-style class`\es, if :meth:`__getstate__` returns a false
value, the :meth:`__setstate__` method will not be called.
+.. note::
+
+ At unpickling time, some methods like :meth:`__getattr__`,
+ :meth:`__getattribute__`, or :meth:`__setattr__` may be called upon the
+ instance. In case those methods rely on some internal invariant being
+ true, the type should implement either :meth:`__getinitargs__` or
+ :meth:`__getnewargs__` to establish such an invariant; otherwise, neither
+ :meth:`__new__` nor :meth:`__init__` will be called.
+
Pickling and unpickling extension types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index b5e7eae..1afa19b 100644
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -148,7 +148,7 @@
# as d was opened WITHOUT writeback=True, beware:
d['xx'] = range(4) # this works as expected, but...
- d['xx'].append(5) # *this doesn't!* -- d['xx'] is STILL range(4)!!!
+ d['xx'].append(5) # *this doesn't!* -- d['xx'] is STILL range(4)!
# having opened d without writeback=True, you need to code carefully:
temp = d['xx'] # extracts the copy
diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst
index a4f181b..078f216 100644
--- a/Doc/library/socketserver.rst
+++ b/Doc/library/socketserver.rst
@@ -129,15 +129,21 @@
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
@@ -148,32 +154,32 @@
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.
.. versionadded:: 2.6
-.. 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
@@ -181,22 +187,22 @@
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
@@ -205,17 +211,19 @@
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.
@@ -223,27 +231,27 @@
.. 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
@@ -251,31 +259,32 @@
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
@@ -291,14 +300,14 @@
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
@@ -317,7 +326,7 @@
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.
diff --git a/Doc/library/webbrowser.rst b/Doc/library/webbrowser.rst
index 4d819e6..56aba5a 100644
--- a/Doc/library/webbrowser.rst
+++ b/Doc/library/webbrowser.rst
@@ -55,6 +55,10 @@
under many window managers this will occur regardless of the setting of this
variable).
+ Note that on some platforms, trying to open a filename using this function,
+ may work and start the operating system's associated program. However, this
+ is neither supported nor portable.
+
.. versionchanged:: 2.5
*new* can now be 2.