Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from

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

........
  r69520 | benjamin.peterson | 2009-02-12 04:50:00 +0100 (Do, 12 Feb 2009) | 1 line

  os.fsync() should be used to ensure that data is written to disk
........
  r69633 | hirokazu.yamamoto | 2009-02-15 10:19:48 +0100 (So, 15 Feb 2009) | 1 line

  Fixed typo.
........
  r69672 | benjamin.peterson | 2009-02-16 15:54:34 +0100 (Mo, 16 Feb 2009) | 1 line

  note functions that are not aliased to PyBytes_ #5280
........
  r69703 | raymond.hettinger | 2009-02-16 23:42:54 +0100 (Mo, 16 Feb 2009) | 3 lines

  Issue 5229: Documentation for super() neglects to say what super() actually does
........
  r69704 | raymond.hettinger | 2009-02-17 00:00:25 +0100 (Di, 17 Feb 2009) | 1 line

  Add explanation for super(type1, type2).
........
  r69717 | marc-andre.lemburg | 2009-02-17 13:48:19 +0100 (Di, 17 Feb 2009) | 5 lines

  Clarify the deprecation of platform.dist().

  Add versionadded tags.
........
  r69731 | gregory.p.smith | 2009-02-18 06:46:11 +0100 (Mi, 18 Feb 2009) | 3 lines

  Clarify socket timeout behavior vs system network stack behavior on connect
  for issue5293.
........

5 files changed, 52 insertions, 8 deletions

diff --git a/Doc/c-api/string.rst b/Doc/c-api/string.rst
index 156c8f2..c7d27a3 100644
--- a/Doc/c-api/string.rst
+++ b/Doc/c-api/string.rst
@@ -9,8 +9,10 @@ These functions raise :exc:`TypeError` when expecting a string parameter and are
 called with a non-string parameter.
 
 .. note::
-   These functions have been renamed to PyBytes_* in Python 3.x. The PyBytes
-   names are also available in 2.6.
+
+   These functions have been renamed to PyBytes_* in Python 3.x. Unless
+   otherwise noted, the PyBytes functions available in 3.x are aliased to their
+   PyString_* equivalents to help porting.
 
 .. index:: object: string
 
@@ -238,6 +240,10 @@ called with a non-string parameter.
    reference-count-neutral; you own the object after the call if and only if you
    owned it before the call.)
 
+   .. note::
+
+      This function is not available in 3.x and does not have a PyBytes alias.
+
 
 .. cfunction:: PyObject* PyString_InternFromString(const char *v)
 
@@ -246,6 +252,10 @@ called with a non-string parameter.
    been interned, or a new ("owned") reference to an earlier interned string object
    with the same value.
 
+   .. note::
+
+      This function is not available in 3.x and does not have a PyBytes alias.
+
 
 .. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
 
@@ -255,6 +265,10 @@ called with a non-string parameter.
    The codec to be used is looked up using the Python codec registry.  Return
    *NULL* if an exception was raised by the codec.
 
+   .. note::
+
+      This function is not available in 3.x and does not have a PyBytes alias.
+
    .. versionchanged:: 2.5
       This function used an :ctype:`int` type for *size*. This might require
       changes in your code for properly supporting 64-bit systems.
@@ -268,6 +282,10 @@ called with a non-string parameter.
    The codec to be used is looked up using the Python codec registry. Return *NULL*
    if an exception was raised by the codec.
 
+   .. note::
+
+      This function is not available in 3.x and does not have a PyBytes alias.
+
 
 .. cfunction:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
 
@@ -277,6 +295,10 @@ called with a non-string parameter.
    :meth:`encode` method. The codec to be used is looked up using the Python codec
    registry.  Return *NULL* if an exception was raised by the codec.
 
+   .. note::
+
+      This function is not available in 3.x and does not have a PyBytes alias.
+
    .. versionchanged:: 2.5
       This function used an :ctype:`int` type for *size*. This might require
       changes in your code for properly supporting 64-bit systems.
@@ -289,3 +311,7 @@ called with a non-string parameter.
    parameters of the same name in the string :meth:`encode` method. The codec to be
    used is looked up using the Python codec registry. Return *NULL* if an exception
    was raised by the codec.
+
+   .. note::
+
+      This function is not available in 3.x and does not have a PyBytes alias.
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 49c2abe..fdacabb 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -633,7 +633,7 @@ Text I/O
 
 .. class:: StringIO([initial_value[, encoding[, errors[, newline]]]])
 
-   An in-memory stream for text.  It in inherits :class:`TextIOWrapper`.
+   An in-memory stream for text.  It inherits :class:`TextIOWrapper`.
 
    Create a new StringIO stream with an inital value, encoding, error handling,
    and newline setting.  See :class:`TextIOWrapper`\'s constructor for more
diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst
index 3c98a1e..cd90c38 100644
--- a/Doc/library/platform.rst
+++ b/Doc/library/platform.rst
@@ -234,7 +234,15 @@ Unix Platforms
 
 .. function:: dist(distname='', version='', id='', supported_dists=('SuSE','debian','redhat','mandrake',...))
 
-   This is another name for :func:`linux_distribution`.
+   This is an old version of the functionality now provided by
+   :func:`linux_distribution`. For new code, please use the
+   :func:`linux_distribution`.
+
+   The only difference between the two is that ``dist()`` always
+   returns the short name of the distribution taken from the
+   ``supported_dists`` parameter.
+
+   .. deprecated:: 2.6
 
 .. function:: linux_distribution(distname='', version='', id='', supported_dists=('SuSE','debian','redhat','mandrake',...), full_distribution_name=1)
 
@@ -252,6 +260,8 @@ Unix Platforms
    parameters.  ``id`` is the item in parentheses after the version number.  It
    is usually the version codename.
 
+   .. versionadded:: 2.6
+
 .. function:: libc_ver(executable=sys.executable, lib='', version='', chunksize=2048)
 
    Tries to determine the libc version against which the file executable (defaults
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index a435b820..d1b107e 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -731,12 +731,13 @@ correspond to Unix system calls applicable to sockets.
 
 Some notes on socket blocking and timeouts: A socket object can be in one of
 three modes: blocking, non-blocking, or timeout.  Sockets are always created in
-blocking mode.  In blocking mode, operations block until complete.  In
+blocking mode.  In blocking mode, operations block until complete or
+the system returns an error (such as connection timed out).  In
 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.  The :meth:`setblocking` method is simply a shorthand for certain
-:meth:`settimeout` calls.
+socket or if the system returns an error.  The :meth:`setblocking` method is simply
+a shorthand for certain :meth:`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
@@ -747,7 +748,9 @@ 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`.
+: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.
 
 
 .. method:: socket.setsockopt(level, optname, value)
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 4069d07..3417970 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -2114,6 +2114,11 @@ Files have the following methods:
    Flush the internal buffer, like ``stdio``'s :cfunc:`fflush`.  This may be a
    no-op on some file-like objects.
 
+   .. note::
+
+      :meth:`flush` does not necessarily write the file's data to disk.  Use
+      :meth:`flush` followed by :func:`os.fsync` to ensure this behavior.
+
 
 .. method:: file.fileno()