From 58ed928c950d76fdeb3577a9d0207f8a81dd4e7a Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 27 Oct 2009 13:38:33 +0000 Subject: [PATCH] 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. ........ --- Doc/c-api/string.rst | 30 ++++++++++++++++++++++++++++-- Doc/library/io.rst | 2 +- Doc/library/platform.rst | 12 +++++++++++- Doc/library/socket.rst | 11 +++++++---- Doc/library/stdtypes.rst | 5 +++++ 5 files changed, 52 insertions(+), 8 deletions(-) diff --git a/Doc/c-api/string.rst b/Doc/c-api/string.rst index 156c8f259b8..c7d27a31c79 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 49c2abe3e37..fdacabb5a2c 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 3c98a1eeba9..cd90c389c3c 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 a435b820125..d1b107ecc63 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 4069d07abab..3417970dcb7 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()