.. 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.
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
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`
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.
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
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
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.
: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
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
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:
: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.
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)``.
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)
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.
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. ::
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)
| | 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'
*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]])
*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.
| ``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`) |
+-------+-----------------------------------------+
*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
.. 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.
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.
Returns ``True`` if reflection is disabled.
Will generally raise :exc:`NotImplemented` if executed on a 32-bit
- Operating System.
+ operating system.
.. _constants:
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.
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()
.. 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.
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
# 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("'", "'\"'\"'") + "'"
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:
"'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()
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).
projects / python / commitdiff