Merged revisions 80030,80067,80069,80080-80081,80084,80432-80433,80465-80470,81059,81065-81067 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r80030 | georg.brandl | 2010-04-13 08:43:54 +0200 (Di, 13 Apr 2010) | 1 line
Get rid of multi-row cells.
........
r80067 | georg.brandl | 2010-04-14 10:53:38 +0200 (Mi, 14 Apr 2010) | 1 line
#5341: typo.
........
r80069 | georg.brandl | 2010-04-14 15:50:31 +0200 (Mi, 14 Apr 2010) | 1 line
Add an x-ref to where the O_ constants are documented and move the SEEK_ constants after lseek().
........
r80080 | georg.brandl | 2010-04-14 21:16:38 +0200 (Mi, 14 Apr 2010) | 1 line
#8399: add note about Windows and O_BINARY.
........
r80081 | georg.brandl | 2010-04-14 23:34:44 +0200 (Mi, 14 Apr 2010) | 1 line
#5250: document __instancecheck__ and __subclasscheck__. I hope the part about the class/metaclass distinction is understandable.
........
r80084 | georg.brandl | 2010-04-14 23:46:45 +0200 (Mi, 14 Apr 2010) | 1 line
Fix missing.
........
r80432 | georg.brandl | 2010-04-24 10:56:58 +0200 (Sa, 24 Apr 2010) | 1 line
Markup fixes.
........
r80433 | georg.brandl | 2010-04-24 11:08:10 +0200 (Sa, 24 Apr 2010) | 1 line
#7507: quote "!" in pipes.quote(); it is a special character for some shells.
........
r80465 | georg.brandl | 2010-04-25 12:29:17 +0200 (So, 25 Apr 2010) | 1 line
Remove LaTeXy index entry syntax.
........
r80466 | georg.brandl | 2010-04-25 12:54:42 +0200 (So, 25 Apr 2010) | 1 line
Patch from Tim Hatch: Better cross-referencing in socket and winreg docs.
........
r80467 | georg.brandl | 2010-04-25 12:55:16 +0200 (So, 25 Apr 2010) | 1 line
Patch from Tim Hatch: Remove reference to winreg being the fabled high-level registry interface.
........
r80468 | georg.brandl | 2010-04-25 12:55:58 +0200 (So, 25 Apr 2010) | 1 line
Patch from Tim Hatch: Minor spelling changes to _winreg docs.
........
r80469 | georg.brandl | 2010-04-25 12:56:41 +0200 (So, 25 Apr 2010) | 1 line
Fix code example to have valid syntax so that it can be highlighted.
........
r80470 | georg.brandl | 2010-04-25 12:57:15 +0200 (So, 25 Apr 2010) | 1 line
Patch from Tim Hatch: Make socket setblocking <-> settimeout examples symmetric.
........
r81059 | georg.brandl | 2010-05-10 23:02:51 +0200 (Mo, 10 Mai 2010) | 1 line
#8642: fix wrong function name.
........
r81065 | georg.brandl | 2010-05-10 23:46:50 +0200 (Mo, 10 Mai 2010) | 1 line
Fix reference direction.
........
r81066 | georg.brandl | 2010-05-10 23:50:57 +0200 (Mo, 10 Mai 2010) | 1 line
Consolidate deprecation messages.
........
r81067 | georg.brandl | 2010-05-10 23:51:33 +0200 (Mo, 10 Mai 2010) | 1 line
Fix typo.
........
diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst
index aaff852..e21c1ed 100644
--- a/Doc/library/fcntl.rst
+++ b/Doc/library/fcntl.rst
@@ -8,8 +8,8 @@
.. index::
- pair: UNIX@Unix; file control
- pair: UNIX@Unix; I/O control
+ pair: UNIX; file control
+ pair: UNIX; I/O control
This module performs file control and I/O control on file descriptors. It is an
interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.
diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index 857f413..35e9ce2 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -122,7 +122,7 @@
The set of all exceptions (as a tuple) that methods of :class:`FTP`
instances may raise as a result of problems with the FTP connection (as
opposed to programming errors made by the caller). This set includes the
- four exceptions listed below as well as :exc:`socket.error` and
+ four exceptions listed above as well as :exc:`socket.error` and
:exc:`IOError`.
.. seealso::
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 451b33f..24db64a 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -240,7 +240,7 @@
Flush and close this stream. This method has no effect if the file is
already closed. Once the file is closed, any operation on the file
- (e.g. reading or writing) will raise an :exc:`ValueError`.
+ (e.g. reading or writing) will raise a :exc:`ValueError`.
As a convenience, it is allowed to call this method more than once;
only the first call, however, will have an effect.
diff --git a/Doc/library/json.rst b/Doc/library/json.rst
index 6ad95b2..e1f5cf2 100644
--- a/Doc/library/json.rst
+++ b/Doc/library/json.rst
@@ -209,7 +209,7 @@
specified. Encodings that are not ASCII based (such as UCS-2) are not
allowed and should be decoded to :class:`str` first.
- The other arguments have the same meaning as in :func:`dump`.
+ The other arguments have the same meaning as in :func:`load`.
Encoders and decoders
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 7b37629..eb48bf1 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -697,6 +697,14 @@
Availability: Unix, Windows.
+.. data:: SEEK_SET
+ SEEK_CUR
+ SEEK_END
+
+ Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
+ respectively. Availability: Windows, Unix.
+
+
.. function:: open(file, flags[, mode])
Open the file *file* and set various flags according to *flags* and possibly
@@ -706,7 +714,8 @@
For a description of the flag and mode values, see the C run-time documentation;
flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
- this module too (see below).
+ this module too (see :ref:`open-constants`). In particular, on Windows adding
+ :const:`O_BINARY` is needed to open files in binary mode.
Availability: Unix, Windows.
@@ -794,6 +803,12 @@
:func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
:meth:`~file.write` method.
+
+.. _open-constants:
+
+``open()`` flag constants
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
The following constants are options for the *flags* parameter to the
:func:`~os.open` function. They can be combined using the bitwise OR operator
``|``. Some of them are not available on all platforms. For descriptions of
@@ -845,14 +860,6 @@
the C library.
-.. data:: SEEK_SET
- SEEK_CUR
- SEEK_END
-
- Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
- respectively. Availability: Windows, Unix.
-
-
.. _os-file-dir:
Files and Directories
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index e73aefb..0e91278 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -89,8 +89,9 @@
and out-of-memory conditions can be raised; errors related to socket or address
semantics raise the error :exc:`socket.error`.
-Non-blocking mode is supported through :meth:`setblocking`. A generalization of
-this based on timeouts is supported through :meth:`settimeout`.
+Non-blocking mode is supported through :meth:`~socket.setblocking`. A
+generalization of this based on timeouts is supported through
+:meth:`~socket.settimeout`.
The module :mod:`socket` exports the following constants and functions:
@@ -559,7 +560,9 @@
:platform: Windows
The :meth:`ioctl` method is a limited interface to the WSAIoctl system
- interface. Please refer to the MSDN documentation for more information.
+ interface. Please refer to the `Win32 documentation
+ <http://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more
+ information.
On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl`
functions may be used; they accept a socket object as their first argument.
@@ -662,7 +665,7 @@
blocking mode. In non-blocking mode, if a :meth:`recv` call doesn't find any
data, or if a :meth:`send` call can't immediately dispose of the data, a
:exc:`error` exception is raised; in blocking mode, the calls block until they
- can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0)``;
+ can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0.0)``;
``s.setblocking(1)`` is equivalent to ``s.settimeout(None)``.
@@ -691,21 +694,21 @@
non-blocking mode, operations fail (with an error that is unfortunately
system-dependent) if they cannot be completed immediately. In timeout mode,
operations fail if they cannot be completed within the timeout specified for the
-socket or if the system returns an error. The :meth:`setblocking` method is simply
-a shorthand for certain :meth:`settimeout` calls.
+socket or if the system returns an error. The :meth:`~socket.setblocking`
+method is simply a shorthand for certain :meth:`~socket.settimeout` calls.
Timeout mode internally sets the socket in non-blocking mode. The blocking and
timeout modes are shared between file descriptors and socket objects that refer
to the same network endpoint. A consequence of this is that file objects
-returned by the :meth:`makefile` method must only be used when the socket is in
-blocking mode; in timeout or non-blocking mode file operations that cannot be
-completed immediately will fail.
+returned by the :meth:`~socket.makefile` method must only be used when the
+socket is in blocking mode; in timeout or non-blocking mode file operations
+that cannot be completed immediately will fail.
-Note that the :meth:`connect` operation is subject to the timeout setting, and
-in general it is recommended to call :meth:`settimeout` before calling
-:meth:`connect` or pass a timeout parameter to :meth:`create_connection`.
-The system network stack may return a connection timeout error
-of its own regardless of any Python socket timeout setting.
+Note that the :meth:`~socket.connect` operation is subject to the timeout
+setting, and in general it is recommended to call :meth:`~socket.settimeout`
+before calling :meth:`~socket.connect` or pass a timeout parameter to
+:meth:`create_connection`. The system network stack may return a connection
+timeout error of its own regardless of any Python socket timeout setting.
.. method:: socket.setsockopt(level, optname, value)
@@ -727,8 +730,8 @@
are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives are
disallowed.
-Note that there are no methods :meth:`read` or :meth:`write`; use :meth:`recv`
-and :meth:`send` without *flags* argument instead.
+Note that there are no methods :meth:`read` or :meth:`write`; use
+:meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead.
Socket objects also have these (read-only) attributes that correspond to the
values given to the :class:`socket` constructor.
@@ -757,11 +760,12 @@
Here are four minimal example programs using the TCP/IP protocol: a server that
echoes all data that it receives back (servicing only one client), and a client
using it. Note that a server must perform the sequence :func:`socket`,
-:meth:`bind`, :meth:`listen`, :meth:`accept` (possibly repeating the
-:meth:`accept` to service more than one client), while a client only needs the
-sequence :func:`socket`, :meth:`connect`. Also note that the server does not
-:meth:`send`/:meth:`recv` on the socket it is listening on but on the new
-socket returned by :meth:`accept`.
+:meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly
+repeating the :meth:`~socket.accept` to service more than one client), while a
+client only needs the sequence :func:`socket`, :meth:`~socket.connect`. Also
+note that the server does not :meth:`~socket.send`/:meth:`~socket.recv` on the
+socket it is listening on but on the new socket returned by
+:meth:`~socket.accept`.
The first two examples support IPv4 only. ::
diff --git a/Doc/library/syslog.rst b/Doc/library/syslog.rst
index c25ed41..a3b374a 100644
--- a/Doc/library/syslog.rst
+++ b/Doc/library/syslog.rst
@@ -10,66 +10,63 @@
Refer to the Unix manual pages for a detailed description of the ``syslog``
facility.
-This module wraps the system ``syslog`` module. A pure Python
-library that can speak to a syslog server is available in
-the :mod:`logging.handlers` module as :class:`SysLogHandler`.
+This module wraps the system ``syslog`` family of routines. A pure Python
+library that can speak to a syslog server is available in the
+:mod:`logging.handlers` module as :class:`SysLogHandler`.
The module defines the following functions:
.. function:: syslog([priority,] message)
- Send the string *message* to the system logger. A trailing newline is
- added if necessary. Each message is tagged with a priority composed
- of a *facility* and a *level*. The optional *priority* argument, which
- defaults to :const:`LOG_INFO`, determines the message priority. If the
- facility is not encoded in *priority* using logical-or (``LOG_INFO |
- LOG_USER``), the value given in the :func:`openlog` call is used.
+ Send the string *message* to the system logger. A trailing newline is added
+ if necessary. Each message is tagged with a priority composed of a
+ *facility* and a *level*. The optional *priority* argument, which defaults
+ to :const:`LOG_INFO`, determines the message priority. If the facility is
+ not encoded in *priority* using logical-or (``LOG_INFO | LOG_USER``), the
+ value given in the :func:`openlog` call is used.
- If :func:`openlog` has not been called prior to the call to
- :func:'syslog', ``openlog()`` will be called with no arguments.
+ If :func:`openlog` has not been called prior to the call to :func:`syslog`,
+ ``openlog()`` will be called with no arguments.
.. function:: openlog([ident[, logopt[, facility]]])
- Logging options of subsequent :func:`syslog` calls can be set by
- calling :func:`openlog`. :func:`syslog` will call :func:`openlog`
- with no arguments if the log is not currently open.
+ Logging options of subsequent :func:`syslog` calls can be set by calling
+ :func:`openlog`. :func:`syslog` will call :func:`openlog` with no arguments
+ if the log is not currently open.
- The optional *ident* keyword argument is a string which is prepended
- to every message, and defaults to ''sys.argv[0]'' with leading
- path components stripped. The optional *logopt* keyword argument
- (default=0) is a bit field - see below for possible values to combine.
- The optional *facility* keyword argument (default=:const:`LOG_USER`)
- sets the default facility for messages which do not have a facility
- explicitly encoded.
+ The optional *ident* keyword argument is a string which is prepended to every
+ message, and defaults to ``sys.argv[0]`` with leading path components
+ stripped. The optional *logopt* keyword argument (default is 0) is a bit
+ field -- see below for possible values to combine. The optional *facility*
+ keyword argument (default is :const:`LOG_USER`) sets the default facility for
+ messages which do not have a facility explicitly encoded.
- .. versionchanged::3.2
- In previous versions, keyword arguments were not allowed, and *ident*
- was required. The default for *ident* was dependent on the system
- libraries, and often was ''python'' instead of the name of the
- python program file.
+ .. versionchanged:: 3.2
+ In previous versions, keyword arguments were not allowed, and *ident* was
+ required. The default for *ident* was dependent on the system libraries,
+ and often was ``python`` instead of the name of the python program file.
.. function:: closelog()
- Reset the syslog module values and call the system library
- ''closelog()''.
+ Reset the syslog module values and call the system library ``closelog()``.
- This causes the module to behave as it does when initially imported.
- For example, :func:'openlog' will be called on the first :func:'syslog'
- call (if :func:'openlog' hasn't already been called), and *ident*
- and other :func:'openlog' parameters are reset to defaults.
+ This causes the module to behave as it does when initially imported. For
+ example, :func:`openlog` will be called on the first :func:`syslog` call (if
+ :func:`openlog` hasn't already been called), and *ident* and other
+ :func:`openlog` parameters are reset to defaults.
.. function:: setlogmask(maskpri)
- Set the priority mask to *maskpri* and return the previous mask value.
- Calls to :func:`syslog` with a priority level not set in *maskpri*
- are ignored. The default is to log all priorities. The function
- ``LOG_MASK(pri)`` calculates the mask for the individual priority
- *pri*. The function ``LOG_UPTO(pri)`` calculates the mask for all
- priorities up to and including *pri*.
+ Set the priority mask to *maskpri* and return the previous mask value. Calls
+ to :func:`syslog` with a priority level not set in *maskpri* are ignored.
+ The default is to log all priorities. The function ``LOG_MASK(pri)``
+ calculates the mask for the individual priority *pri*. The function
+ ``LOG_UPTO(pri)`` calculates the mask for all priorities up to and including
+ *pri*.
The module defines the following constants:
@@ -100,11 +97,11 @@
syslog.syslog('Processing started')
if error:
- syslog.syslog(syslog.LOG_ERR, 'Processing started')
+ syslog.syslog(syslog.LOG_ERR, 'Processing started')
-An example of setting some log options, these would include the process ID
-in logged messages, and write the messages to the destination facility
-used for mail logging::
+An example of setting some log options, these would include the process ID in
+logged messages, and write the messages to the destination facility used for
+mail logging::
syslog.openlog(logopt=syslog.LOG_PID, facility=syslog.LOG_MAIL)
syslog.syslog('E-mail processing initiated...')
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index edf0ebf..1cb4124 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -773,8 +773,7 @@
will be *msg* if given, otherwise it will be :const:`None`.
.. deprecated:: 3.1
- :meth:`failUnless`; use one of the ``assert`` variants.
- :meth:`assert_`; use :meth:`assertTrue`.
+ :meth:`failUnless` and :meth:`assert_`; use :meth:`assertTrue`.
.. method:: assertEqual(first, second, msg=None)