[Python-checkins] r87198 - python/branches/py3k/Doc/library/socket.rst
antoine.pitrou
python-checkins at python.org
Sun Dec 12 21:57:12 CET 2010
Author: antoine.pitrou
Date: Sun Dec 12 21:57:12 2010
New Revision: 87198
Log:
Improve readability of the socket docs
Modified:
python/branches/py3k/Doc/library/socket.rst
Modified: python/branches/py3k/Doc/library/socket.rst
==============================================================================
--- python/branches/py3k/Doc/library/socket.rst (original)
+++ python/branches/py3k/Doc/library/socket.rst Sun Dec 12 21:57:12 2010
@@ -14,16 +14,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
@@ -34,26 +24,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
@@ -62,40 +89,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:
@@ -144,7 +149,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
@@ -154,8 +160,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:: SOCK_CLOEXEC
SOCK_NONBLOCK
@@ -950,3 +957,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.
+
More information about the Python-checkins
mailing list