Merged revisions 87197-87198 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r87197 | antoine.pitrou | 2010-12-12 21:34:49 +0100 (dim., 12 déc. 2010) | 3 lines
Homogenize the "optional OS services" menu
........
r87198 | antoine.pitrou | 2010-12-12 21:57:12 +0100 (dim., 12 déc. 2010) | 3 lines
Improve readability of the socket docs
........
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index f726a02..f280223 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -1,8 +1,8 @@
-:mod:`multiprocessing` --- Process-based "threading" interface
-==============================================================
+:mod:`multiprocessing` --- Process-based parallelism
+====================================================
.. module:: multiprocessing
- :synopsis: Process-based "threading" interface.
+ :synopsis: Process-based parallelism.
Introduction
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 391216e..bbe512b 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -15,16 +15,6 @@
Some behavior may be platform dependent, since calls are made to the operating
system socket APIs.
-For an introduction to socket programming (in C), see the following papers: An
-Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest and
-An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et
-al, both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
-PS1:7 and PS1:8). The platform-specific reference material for the various
-socket-related system calls are also a valuable source of information on the
-details of socket semantics. For Unix, refer to the manual pages; for Windows,
-see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may
-want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6.
-
.. index:: object: socket
The Python interface is a straightforward transliteration of the Unix system
@@ -35,26 +25,63 @@
files, buffer allocation on receive operations is automatic, and buffer length
is implicit on send operations.
-Socket addresses are represented as follows: A single string is used for the
-:const:`AF_UNIX` address family. A pair ``(host, port)`` is used for the
-:const:`AF_INET` address family, where *host* is a string representing either a
-hostname in Internet domain notation like ``'daring.cwi.nl'`` or an IPv4 address
-like ``'100.50.200.5'``, and *port* is an integral port number. For
-:const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
-scopeid)`` is used, where *flowinfo* and *scopeid* represents ``sin6_flowinfo``
-and ``sin6_scope_id`` member in :const:`struct sockaddr_in6` in C. For
-:mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for
-backward compatibility. Note, however, omission of *scopeid* can cause problems
-in manipulating scoped IPv6 addresses. Other address families are currently not
-supported. The address format required by a particular socket object is
-automatically selected based on the address family specified when the socket
-object was created.
+
+Socket families
+---------------
+
+Depending on the system and the build options, various socket families
+are supported by this module.
+
+Socket addresses are represented as follows:
+
+- A single string is used for the :const:`AF_UNIX` address family.
+
+- A pair ``(host, port)`` is used for the :const:`AF_INET` address family,
+ where *host* is a string representing either a hostname in Internet domain
+ notation like ``'daring.cwi.nl'`` or an IPv4 address like ``'100.50.200.5'``,
+ and *port* is an integral port number.
+
+- For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
+ scopeid)`` is used, where *flowinfo* and *scopeid* represent the ``sin6_flowinfo``
+ and ``sin6_scope_id`` members in :const:`struct sockaddr_in6` in C. For
+ :mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for
+ backward compatibility. Note, however, omission of *scopeid* can cause problems
+ in manipulating scoped IPv6 addresses.
+
+- :const:`AF_NETLINK` sockets are represented as pairs ``(pid, groups)``.
+
+- Linux-only support for TIPC is available using the :const:`AF_TIPC`
+ address family. TIPC is an open, non-IP based networked protocol designed
+ for use in clustered computer environments. Addresses are represented by a
+ tuple, and the fields depend on the address type. The general tuple form is
+ ``(addr_type, v1, v2, v3 [, scope])``, where:
+
+ - *addr_type* is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or
+ TIPC_ADDR_ID.
+ - *scope* is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and
+ TIPC_NODE_SCOPE.
+ - If *addr_type* is TIPC_ADDR_NAME, then *v1* is the server type, *v2* is
+ the port identifier, and *v3* should be 0.
+
+ If *addr_type* is TIPC_ADDR_NAMESEQ, then *v1* is the server type, *v2*
+ is the lower port number, and *v3* is the upper port number.
+
+ If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the
+ reference, and *v3* should be set to 0.
+
+ If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the
+ reference, and *v3* should be set to 0.
+
+- Certain other address families (:const:`AF_BLUETOOTH`, :const:`AF_PACKET`)
+ support specific representations.
+
+ .. XXX document them!
For IPv4 addresses, two special forms are accepted instead of a host address:
the empty string represents :const:`INADDR_ANY`, and the string
-``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. The behavior is not
-available for IPv6 for backward compatibility, therefore, you may want to avoid
-these if you intend to support IPv6 with your Python programs.
+``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. This behavior is not
+compatible with IPv6, therefore, you may want to avoid these if you intend
+to support IPv6 with your Python programs.
If you use a hostname in the *host* portion of IPv4/v6 socket address, the
program may show a nondeterministic behavior, as Python uses the first address
@@ -63,40 +90,18 @@
resolution and/or the host configuration. For deterministic behavior use a
numeric address in *host* portion.
-AF_NETLINK sockets are represented as pairs ``pid, groups``.
-
-
-Linux-only support for TIPC is also available using the :const:`AF_TIPC`
-address family. TIPC is an open, non-IP based networked protocol designed
-for use in clustered computer environments. Addresses are represented by a
-tuple, and the fields depend on the address type. The general tuple form is
-``(addr_type, v1, v2, v3 [, scope])``, where:
-
-- *addr_type* is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or
- TIPC_ADDR_ID.
-- *scope* is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and
- TIPC_NODE_SCOPE.
-- If *addr_type* is TIPC_ADDR_NAME, then *v1* is the server type, *v2* is
- the port identifier, and *v3* should be 0.
-
- If *addr_type* is TIPC_ADDR_NAMESEQ, then *v1* is the server type, *v2*
- is the lower port number, and *v3* is the upper port number.
-
- If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the
- reference, and *v3* should be set to 0.
-
- If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the
- reference, and *v3* should be set to 0.
-
-
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`.
+semantics raise :exc:`socket.error` or one of its subclasses.
Non-blocking mode is supported through :meth:`~socket.setblocking`. A
generalization of this based on timeouts is supported through
:meth:`~socket.settimeout`.
+
+Module contents
+---------------
+
The module :mod:`socket` exports the following constants and functions:
@@ -145,7 +150,8 @@
These constants represent the address (and protocol) families, used for the
first argument to :func:`socket`. If the :const:`AF_UNIX` constant is not
- defined then this protocol is unsupported.
+ defined then this protocol is unsupported. More constants may be available
+ depending on the system.
.. data:: SOCK_STREAM
@@ -155,8 +161,9 @@
SOCK_SEQPACKET
These constants represent the socket types, used for the second argument to
- :func:`socket`. (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be
- generally useful.)
+ :func:`socket`. More constants may be available depending on the system.
+ (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be generally
+ useful.)
.. data:: SO_*
@@ -911,3 +918,21 @@
# disabled promiscuous mode
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)
+
+
+.. seealso::
+
+ For an introduction to socket programming (in C), see the following papers:
+
+ - *An Introductory 4.3BSD Interprocess Communication Tutorial*, by Stuart Sechrest
+
+ - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Leffler et
+ al,
+
+ both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
+ PS1:7 and PS1:8). The platform-specific reference material for the various
+ socket-related system calls are also a valuable source of information on the
+ details of socket semantics. For Unix, refer to the manual pages; for Windows,
+ see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may
+ want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6.
+
diff --git a/Doc/library/someos.rst b/Doc/library/someos.rst
index baa1989..cf3eb6b 100644
--- a/Doc/library/someos.rst
+++ b/Doc/library/someos.rst
@@ -14,10 +14,10 @@
select.rst
threading.rst
- dummy_threading.rst
- _thread.rst
- _dummy_thread.rst
multiprocessing.rst
mmap.rst
readline.rst
rlcompleter.rst
+ dummy_threading.rst
+ _thread.rst
+ _dummy_thread.rst
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 8b4babc..910e49d 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -1,8 +1,8 @@
-:mod:`threading` --- Higher-level threading interface
-=====================================================
+:mod:`threading` --- Thread-based parallelism
+=============================================
.. module:: threading
- :synopsis: Higher-level threading interface.
+ :synopsis: Thread-based parallelism.
This module constructs higher-level threading interfaces on top of the lower