diff options
| -rw-r--r-- | Doc/library/fcntl.rst | 4 | ||||
| -rw-r--r-- | Doc/library/ftplib.rst | 17 | ||||
| -rw-r--r-- | Doc/library/io.rst | 2 | ||||
| -rw-r--r-- | Doc/library/json.rst | 2 | ||||
| -rw-r--r-- | Doc/library/os.rst | 25 | ||||
| -rw-r--r-- | Doc/library/socket.rst | 46 | ||||
| -rw-r--r-- | Doc/library/winreg.rst | 81 | ||||
| -rw-r--r-- | Doc/reference/datamodel.rst | 40 | ||||
| -rw-r--r-- | Lib/pipes.py | 18 | ||||
| -rw-r--r-- | Lib/test/test_pipes.py | 7 | ||||
| -rw-r--r-- | Misc/NEWS | 2 |
11 files changed, 150 insertions, 94 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 bd35728..9a3b305 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -46,14 +46,6 @@ The module defines the following items: connection attempt (if is not specified, the global default timeout setting will be used). - .. attribute:: all_errors - - 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 - :exc:`IOError`. - .. exception:: error_reply @@ -76,6 +68,15 @@ The module defines the following items: with a digit in the range 1--5. +.. data:: all_errors + + 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 above as well as :exc:`socket.error` and + :exc:`IOError`. + + .. seealso:: Module :mod:`netrc` diff --git a/Doc/library/io.rst b/Doc/library/io.rst index e9cae7c..8bbd6cb 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -235,7 +235,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 b14dc92..28d8c53 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -584,6 +584,14 @@ by file descriptors. 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 @@ -593,7 +601,8 @@ by file descriptors. 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. @@ -681,6 +690,12 @@ by file descriptors. :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 @@ -732,14 +747,6 @@ or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ 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 60dc02e..75454cb 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -90,8 +90,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: @@ -553,7 +554,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 + <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. @@ -656,7 +659,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)``. @@ -685,21 +688,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) @@ -721,8 +724,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. @@ -751,11 +754,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/winreg.rst b/Doc/library/winreg.rst index cc0313f..bd7e8d4 100644 --- a/Doc/library/winreg.rst +++ b/Doc/library/winreg.rst @@ -8,21 +8,23 @@ These functions expose the Windows registry API to Python. Instead of using an -integer as the registry handle, a handle object is used to ensure that the -handles are closed correctly, even if the programmer neglects to explicitly -close them. +integer as the registry handle, a :ref:`handle object <handle-object>` is used +to ensure that the handles are closed correctly, even if the programmer neglects +to explicitly close them. This module offers the following functions: .. function:: CloseKey(hkey) - Closes a previously opened registry key. The hkey argument specifies a + Closes a previously opened registry key. The *hkey* argument specifies a previously opened key. .. note:: - If *hkey* is not closed using this method (or via :meth:`hkey.Close() <PyHKEY.Close>`), - it is closed when the *hkey* object is destroyed by Python. + + If *hkey* is not closed using this method (or via :meth:`hkey.Close() + <PyHKEY.Close>`), it is closed when the *hkey* object is destroyed by + Python. .. function:: ConnectRegistry(computer_name, key) @@ -123,13 +125,15 @@ This module offers the following functions: | | registry type | +-------+--------------------------------------------+ | ``2`` | An integer that identifies the type of the | - | | value data | + | | value data (see table in docs for | + | | :meth:`SetValueEx`) | +-------+--------------------------------------------+ .. function:: ExpandEnvironmentStrings(str) - Expands environment strings %NAME% in unicode string like :const:`REG_EXPAND_SZ`:: + Expands environment variable placeholders ``%NAME%`` in strings like + :const:`REG_EXPAND_SZ`:: >>> ExpandEnvironmentStrings('%windir%') 'C:\\Windows' @@ -163,23 +167,20 @@ This module offers the following functions: *key* is a handle returned by :func:`ConnectRegistry` or one of the constants :const:`HKEY_USERS` or :const:`HKEY_LOCAL_MACHINE`. - *sub_key* is a string that identifies the sub_key to load. + *sub_key* is a string that identifies the subkey to load. *file_name* is the name of the file to load registry data from. This file must have been created with the :func:`SaveKey` function. Under the file allocation table (FAT) file system, the filename may not have an extension. - A call to LoadKey() fails if the calling process does not have the - :const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different than + A call to :func:`LoadKey` fails if the calling process does not have the + :const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different from permissions -- see the `RegLoadKey documentation <http://msdn.microsoft.com/en-us/library/ms724889%28v=VS.85%29.aspx>`__ for more details. If *key* is a handle returned by :func:`ConnectRegistry`, then the path - specified in *fileName* is relative to the remote computer. - - The Win32 documentation implies *key* must be in the :const:`HKEY_USER` or - :const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true. + specified in *file_name* is relative to the remote computer. .. function:: OpenKey(key, sub_key[, res[, sam]]) @@ -194,8 +195,8 @@ This module offers the following functions: *res* is a reserved integer, and must be zero. The default is zero. *sam* is an integer that specifies an access mask that describes the desired - security access for the key. Default is :const:`KEY_READ`. See - :ref:`Access Rights <access-rights>` for other allowed values. + security access for the key. Default is :const:`KEY_READ`. See :ref:`Access + Rights <access-rights>` for other allowed values. The result is a new handle to the specified key. @@ -267,7 +268,8 @@ This module offers the following functions: | ``0`` | The value of the registry item. | +-------+-----------------------------------------+ | ``1`` | An integer giving the registry type for | - | | this value. | + | | this value (see table in docs for | + | | :meth:`SetValueEx`) | +-------+-----------------------------------------+ @@ -278,10 +280,10 @@ This module offers the following functions: *key* is an already open key, or one of the predefined :ref:`HKEY_* constants <hkey-constants>`. - *file_name* is the name of the file to save registry data to. This file cannot - already exist. If this filename includes an extension, it cannot be used on file - allocation table (FAT) file systems by the :meth:`LoadKey`, :meth:`ReplaceKey` - or :meth:`RestoreKey` methods. + *file_name* is the name of the file to save registry data to. This file + cannot already exist. If this filename includes an extension, it cannot be + used on file allocation table (FAT) file systems by the :meth:`LoadKey` + method. If *key* represents a key on a remote computer, the path described by *file_name* is relative to the remote computer. The caller of this method must @@ -351,16 +353,16 @@ This module offers the following functions: .. function:: DisableReflectionKey(key) Disables registry reflection for 32-bit processes running on a 64-bit - Operating System. + operating system. - *key* is an already open key, or one of the predefined - :ref:`HKEY_* constants <hkey-constants>`. + *key* is an already open key, or one of the predefined :ref:`HKEY_* constants + <hkey-constants>`. - Will generally raise :exc:`NotImplemented` if executed on a 32-bit - Operating System. + Will generally raise :exc:`NotImplemented` if executed on a 32-bit operating + system. If the key is not on the reflection list, the function succeeds but has no - effect. Disabling reflection for a key does not affect reflection of any + effect. Disabling reflection for a key does not affect reflection of any subkeys. @@ -368,11 +370,11 @@ This module offers the following functions: Restores registry reflection for the specified disabled key. - *key* is an already open key, or one of the predefined - :ref:`HKEY_* constants <hkey-constants>`. + *key* is an already open key, or one of the predefined :ref:`HKEY_* constants + <hkey-constants>`. - Will generally raise :exc:`NotImplemented` if executed on a 32-bit - Operating System. + Will generally raise :exc:`NotImplemented` if executed on a 32-bit operating + system. Restoring reflection for a key does not affect reflection of any subkeys. @@ -387,7 +389,7 @@ This module offers the following functions: Returns ``True`` if reflection is disabled. Will generally raise :exc:`NotImplemented` if executed on a 32-bit - Operating System. + operating system. .. _constants: @@ -586,7 +588,7 @@ Registry Handle Objects This object wraps a Windows HKEY object, automatically closing it when the object is destroyed. To guarantee cleanup, you can call either the -:meth:`Close` method on the object, or the :func:`CloseKey` function. +:meth:`~PyHKEY.Close` method on the object, or the :func:`CloseKey` function. All registry functions in this module return one of these objects. @@ -606,8 +608,8 @@ true if they both reference the same underlying Windows handle value. Handle objects can be converted to an integer (e.g., using the built-in :func:`int` function), in which case the underlying Windows handle value is -returned. You can also use the :meth:`Detach` method to return the integer -handle, and also disconnect the Windows handle from the handle object. +returned. You can also use the :meth:`~PyHKEY.Detach` method to return the +integer handle, and also disconnect the Windows handle from the handle object. .. method:: PyHKEY.Close() @@ -632,11 +634,12 @@ handle, and also disconnect the Windows handle from the handle object. .. method:: PyHKEY.__enter__() PyHKEY.__exit__(\*exc_info) - The HKEY object implements :meth:`__enter__` and :meth:`__exit__` and thus - supports the context protocol for the :keyword:`with` statement:: + The HKEY object implements :meth:`~object.__enter__` and + :meth:`~object.__exit__` and thus supports the context protocol for the + :keyword:`with` statement:: with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key: - # ... work with key ... + ... # work with key will automatically close *key* when control leaves the :keyword:`with` block. diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index d2f8c16..a32a84d 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1588,6 +1588,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 6a473ae..51666a8 100644 --- a/Lib/pipes.py +++ b/Lib/pipes.py @@ -249,20 +249,18 @@ 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.""" for c in file: if c not in _safechars: break else: + 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 da6af5c..9c7e8e1 100644 --- a/Lib/test/test_pipes.py +++ b/Lib/test/test_pipes.py @@ -62,9 +62,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: @@ -72,7 +73,7 @@ class SimplePipeTests(unittest.TestCase): "'test%sname'" % u) for u in unsafe: self.assertEqual(pipes.quote("test%s'name'" % u), - '"test\\%s\'name\'"' % u) + "'test%s'\"'\"'name'\"'\"''" % u) def testRepr(self): t = pipes.Template() @@ -43,6 +43,8 @@ Core and Builtins Library ------- +- Issue #7507: Quote "!" in pipes.quote(); it is special to some shells. + - Issue #8663: distutils.log emulates backslashreplace error handler. Fix compilation in a non-ASCII directory if stdout encoding is ASCII (eg. if stdout is not a TTY). |