[Python-checkins] r81365 - in python/branches/py3k: Doc/library/fcntl.rst Doc/library/ftplib.rst Doc/library/io.rst Doc/library/json.rst Doc/library/os.rst Doc/library/socket.rst Doc/library/syslog.rst Doc/library/unittest.rst Doc/reference/datamodel.rst Lib/pipes.py Lib/test/test_pipes.py Misc/NEWS
georg.brandl
python-checkins at python.org
Wed May 19 22:57:08 CEST 2010
Author: georg.brandl
Date: Wed May 19 22:57:08 2010
New Revision: 81365
Log:
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.
........
Modified:
python/branches/py3k/Doc/library/fcntl.rst
python/branches/py3k/Doc/library/ftplib.rst
python/branches/py3k/Doc/library/io.rst
python/branches/py3k/Doc/library/json.rst
python/branches/py3k/Doc/library/os.rst
python/branches/py3k/Doc/library/socket.rst
python/branches/py3k/Doc/library/syslog.rst
python/branches/py3k/Doc/library/unittest.rst
python/branches/py3k/Doc/reference/datamodel.rst
python/branches/py3k/Lib/pipes.py
python/branches/py3k/Lib/test/test_pipes.py
python/branches/py3k/Misc/NEWS
Modified: python/branches/py3k/Doc/library/fcntl.rst
==============================================================================
--- python/branches/py3k/Doc/library/fcntl.rst (original)
+++ python/branches/py3k/Doc/library/fcntl.rst Wed May 19 22:57:08 2010
@@ -8,8 +8,8 @@
.. index::
- pair: UNIX at Unix; file control
- pair: UNIX at 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.
Modified: python/branches/py3k/Doc/library/ftplib.rst
==============================================================================
--- python/branches/py3k/Doc/library/ftplib.rst (original)
+++ python/branches/py3k/Doc/library/ftplib.rst Wed May 19 22:57:08 2010
@@ -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::
Modified: python/branches/py3k/Doc/library/io.rst
==============================================================================
--- python/branches/py3k/Doc/library/io.rst (original)
+++ python/branches/py3k/Doc/library/io.rst Wed May 19 22:57:08 2010
@@ -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.
Modified: python/branches/py3k/Doc/library/json.rst
==============================================================================
--- python/branches/py3k/Doc/library/json.rst (original)
+++ python/branches/py3k/Doc/library/json.rst Wed May 19 22:57:08 2010
@@ -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
Modified: python/branches/py3k/Doc/library/os.rst
==============================================================================
--- python/branches/py3k/Doc/library/os.rst (original)
+++ python/branches/py3k/Doc/library/os.rst Wed May 19 22:57:08 2010
@@ -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
Modified: python/branches/py3k/Doc/library/socket.rst
==============================================================================
--- python/branches/py3k/Doc/library/socket.rst (original)
+++ python/branches/py3k/Doc/library/socket.rst Wed May 19 22:57:08 2010
@@ -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.
-
-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.
+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:`~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. ::
Modified: python/branches/py3k/Doc/library/syslog.rst
==============================================================================
--- python/branches/py3k/Doc/library/syslog.rst (original)
+++ python/branches/py3k/Doc/library/syslog.rst Wed May 19 22:57:08 2010
@@ -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.
-
- 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.
-
- .. 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.
+ 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 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.
.. 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...')
Modified: python/branches/py3k/Doc/library/unittest.rst
==============================================================================
--- python/branches/py3k/Doc/library/unittest.rst (original)
+++ python/branches/py3k/Doc/library/unittest.rst Wed May 19 22:57:08 2010
@@ -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)
Modified: python/branches/py3k/Doc/reference/datamodel.rst
==============================================================================
--- python/branches/py3k/Doc/reference/datamodel.rst (original)
+++ python/branches/py3k/Doc/reference/datamodel.rst Wed May 19 22:57:08 2010
@@ -1587,6 +1587,46 @@
called *members*.
+Customizing instance and subclass checks
+----------------------------------------
+
+The following methods are used to override the default behavior of the
+:func:`isinstance` and :func:`issubclass` built-in functions.
+
+In particular, the metaclass :class:`abc.ABCMeta` implements these methods in
+order to allow the addition of Abstract Base Classes (ABCs) as "virtual base
+classes" to any class or type (including built-in types), and including to other
+ABCs.
+
+.. method:: class.__instancecheck__(self, instance)
+
+ Return true if *instance* should be considered a (direct or indirect)
+ instance of *class*. If defined, called to implement ``isinstance(instance,
+ class)``.
+
+
+.. method:: class.__subclasscheck__(self, subclass)
+
+ Return true if *subclass* should be considered a (direct or indirect)
+ subclass of *class*. If defined, called to implement ``issubclass(subclass,
+ class)``.
+
+
+Note that these methods are looked up on the type (metaclass) of a class. They
+cannot be defined as class methods in the actual class. This is consistent with
+the lookup of special methods that are called on instances, only that in this
+case the instance is itself a class.
+
+.. seealso::
+
+ :pep:`3119` - Introducing Abstract Base Classes
+ Includes the specification for customizing :func:`isinstance` and
+ :func:`issubclass` behavior through :meth:`__instancecheck__` and
+ :meth:`__subclasscheck__`, with motivation for this functionality in the
+ context of adding Abstract Base Classes (see the :mod:`abc` module) to the
+ language.
+
+
.. _callable-types:
Emulating callable objects
Modified: python/branches/py3k/Lib/pipes.py
==============================================================================
--- python/branches/py3k/Lib/pipes.py (original)
+++ python/branches/py3k/Lib/pipes.py Wed May 19 22:57:08 2010
@@ -249,11 +249,11 @@
# Reliably quote a string as a single argument for /bin/sh
-_safechars = string.ascii_letters + string.digits + '!@%_-+=:,./' # Safe unquoted
-_funnychars = '"`$\\' # Unsafe inside "double quotes"
+# Safe unquoted
+_safechars = frozenset(string.ascii_letters + string.digits + '@%_-+=:,./')
def quote(file):
- ''' return a shell-escaped version of the file string '''
+ """Return a shell-escaped version of the file string."""
for c in file:
if c not in _safechars:
break
@@ -261,11 +261,6 @@
if not file:
return "''"
return file
- if '\'' not in file:
- return '\'' + file + '\''
- res = ''
- for c in file:
- if c in _funnychars:
- c = '\\' + c
- res = res + c
- return '"' + res + '"'
+ # use single quotes, and put single quotes into double quotes
+ # the string $'b is then quoted as '$'"'"'b'
+ return "'" + file.replace("'", "'\"'\"'") + "'"
Modified: python/branches/py3k/Lib/test/test_pipes.py
==============================================================================
--- python/branches/py3k/Lib/test/test_pipes.py (original)
+++ python/branches/py3k/Lib/test/test_pipes.py Wed May 19 22:57:08 2010
@@ -70,9 +70,10 @@
self.assertEqual(open(TESTFN).read(), d)
def testQuoting(self):
- safeunquoted = string.ascii_letters + string.digits + '!@%_-+=:,./'
- unsafe = '"`$\\'
+ safeunquoted = string.ascii_letters + string.digits + '@%_-+=:,./'
+ unsafe = '"`$\\!'
+ self.assertEqual(pipes.quote(''), "''")
self.assertEqual(pipes.quote(safeunquoted), safeunquoted)
self.assertEqual(pipes.quote('test file name'), "'test file name'")
for u in unsafe:
@@ -80,9 +81,7 @@
"'test%sname'" % u)
for u in unsafe:
self.assertEqual(pipes.quote("test%s'name'" % u),
- '"test\\%s\'name\'"' % u)
-
- self.assertEqual(pipes.quote(''), "''")
+ "'test%s'\"'\"'name'\"'\"''" % u)
def testRepr(self):
t = pipes.Template()
Modified: python/branches/py3k/Misc/NEWS
==============================================================================
--- python/branches/py3k/Misc/NEWS (original)
+++ python/branches/py3k/Misc/NEWS Wed May 19 22:57:08 2010
@@ -38,6 +38,8 @@
PyUnicode_FromString() to support surrogates in the filename and use the
right encoding
+- Issue #7507: Quote "!" in pipes.quote(); it is special to some shells.
+
- PyUnicode_DecodeFSDefaultAndSize() uses surrogateescape error handler
- Issue #8419: Prevent the dict constructor from accepting non-string keyword
More information about the Python-checkins
mailing list