From 8569e582f85e8a44bf34238f6a1809eb6e001de9 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 19 May 2010 20:57:08 +0000 Subject: 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. ........ --- Doc/library/fcntl.rst | 4 +-- Doc/library/ftplib.rst | 2 +- Doc/library/io.rst | 2 +- Doc/library/json.rst | 2 +- Doc/library/os.rst | 25 +++++++++----- Doc/library/socket.rst | 46 +++++++++++++------------ Doc/library/syslog.rst | 81 ++++++++++++++++++++++----------------------- Doc/library/unittest.rst | 3 +- Doc/reference/datamodel.rst | 40 ++++++++++++++++++++++ Lib/pipes.py | 17 ++++------ Lib/test/test_pipes.py | 9 +++-- Misc/NEWS | 2 ++ 12 files changed, 138 insertions(+), 95 deletions(-) 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 module defines the following items: 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 @@ I/O Base Classes 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 @@ Basic Usage 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 @@ as internal buffering of data. 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 @@ as internal buffering of data. 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 @@ as internal buffering of data. :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 @@ or `the MSDN `_ on Window 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 @@ All errors raise exceptions. The normal exceptions for invalid argument types 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 @@ correspond to Unix system calls applicable to sockets. :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 + `_ 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 @@ correspond to Unix system calls applicable to sockets. 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 @@ 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 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 @@ of its own regardless of any Python socket timeout setting. 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 @@ Example 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 @@ This module provides an interface to the Unix ``syslog`` library routines. 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 @@ A simple set of examples:: 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 @@ Test cases 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) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 5af615d..06aa0f9 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1587,6 +1587,46 @@ the new type and it saves the ordered dictionary keys in an attribute 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 diff --git a/Lib/pipes.py b/Lib/pipes.py index deab815..51666a8 100644 --- a/Lib/pipes.py +++ b/Lib/pipes.py @@ -249,11 +249,11 @@ def makepipeline(infile, steps, outfile): # 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 @@ def quote(file): 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("'", "'\"'\"'") + "'" diff --git a/Lib/test/test_pipes.py b/Lib/test/test_pipes.py index 9ce137e..3d31fce 100644 --- a/Lib/test/test_pipes.py +++ b/Lib/test/test_pipes.py @@ -70,9 +70,10 @@ class SimplePipeTests(unittest.TestCase): 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 @@ class SimplePipeTests(unittest.TestCase): "'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() diff --git a/Misc/NEWS b/Misc/NEWS index e68e5da..68bebe9 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -38,6 +38,8 @@ Core and Builtins 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 -- cgit v0.12