traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merged revisions 80465-80470 via svnmerge from 

svn+ssh://pythondev@svn.python.org/python/trunk

........
  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.
........
This commit is contained in:
Georg Brandl 2010-04-25 17:15:51 +00:00
parent a33971a395
commit 34e44c4361
3 changed files with 63 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
Doc/library/_winreg.rst
View File

@ -15,20 +15,20 @@
.. versionadded:: 2.0
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 exposes a very low-level interface to the Windows registry; it is
expected that in the future a new ``winreg`` module will be created offering a
higher-level interface to the registry API.
expected that in the future a new module will be created offering a higher-level
interface to the registry API.
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 that if *hkey* is not closed using this method (or via
@ -134,13 +134,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(unicode)
Expands environment strings %NAME% in unicode string like const:`REG_EXPAND_SZ`::
Expands environment variable placeholders ``%NAME%`` in unicode strings like
:const:`REG_EXPAND_SZ`::
>>> ExpandEnvironmentStrings(u"%windir%")
u"C:\\Windows"
@ -173,24 +175,23 @@ This module offers the following functions:
Creates a subkey under the specified key and stores registration information
from a specified file into that subkey.
*key* is an already open key, or any of the predefined :const:`HKEY_\*`
constants.
*key* is a handle returned by :func:`ConnectRegistry` or one of the constants
:const:`HKEY_USER` 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
permissions -- see the Win32 documentation for more details.
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 `Win32 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]])
@ -205,7 +206,10 @@ 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`
security access for the key. Default is :const:`KEY_READ`. See the `Win32
documentation
<http://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`_ for
other allowed values.
The result is a new handle to the specified key.
@ -277,7 +281,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`) |
+-------+-----------------------------------------+
@ -288,10 +293,10 @@ This module offers the following functions:
*key* is an already open key, or one of the predefined :const:`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
@ -391,7 +396,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.
@ -411,8 +416,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()
@ -437,11 +442,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.

4
Doc/library/fcntl.rst
View File

@ -9,8 +9,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.

47
Doc/library/socket.rst
View File

@ -1,4 +1,3 @@
:mod:`socket` --- Low-level networking interface
================================================
@ -91,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:
@ -597,7 +597,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.
@ -705,7 +707,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)``.
@ -737,21 +739,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)
@ -773,8 +775,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.
@ -809,11 +811,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. ::