[Python-checkins] cpython (3.3): Tweak the socket module doc layout
antoine.pitrou
python-checkins at python.org
Wed Dec 4 21:16:01 CET 2013
http://hg.python.org/cpython/rev/489001c48bf1
changeset: 87767:489001c48bf1
branch: 3.3
user: Antoine Pitrou <solipsis at pitrou.net>
date: Wed Dec 04 21:11:03 2013 +0100
summary:
Tweak the socket module doc layout
files:
Doc/library/socket.rst | 150 ++++++++++++++++------------
1 files changed, 86 insertions(+), 64 deletions(-)
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -138,9 +138,12 @@
Module contents
---------------
-The module :mod:`socket` exports the following constants and functions:
+The module :mod:`socket` exports the following elements.
+Exceptions
+^^^^^^^^^^
+
.. exception:: error
A deprecated alias of :exc:`OSError`.
@@ -186,6 +189,10 @@
.. versionchanged:: 3.3
This class was made a subclass of :exc:`OSError`.
+
+Constants
+^^^^^^^^^
+
.. data:: AF_UNIX
AF_INET
AF_INET6
@@ -290,6 +297,43 @@
this platform.
+Functions
+^^^^^^^^^
+
+Creating sockets
+''''''''''''''''
+
+The following functions all create :ref:`socket objects <socket-objects>`.
+
+
+.. function:: socket([family[, type[, proto]]])
+
+ Create a new socket using the given address family, socket type and protocol
+ number. The address family should be :const:`AF_INET` (the default),
+ :const:`AF_INET6`, :const:`AF_UNIX`, :const:`AF_CAN` or :const:`AF_RDS`. The
+ socket type should be :const:`SOCK_STREAM` (the default),
+ :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_``
+ constants. The protocol number is usually zero and may be omitted in that
+ case or :const:`CAN_RAW` in case the address family is :const:`AF_CAN`.
+
+ .. versionchanged:: 3.3
+ The AF_CAN family was added.
+ The AF_RDS family was added.
+
+
+.. function:: socketpair([family[, type[, proto]]])
+
+ Build a pair of connected socket objects using the given address family, socket
+ type, and protocol number. Address family, socket type, and protocol number are
+ as for the :func:`.socket` function above. The default family is :const:`AF_UNIX`
+ if defined on the platform; otherwise, the default is :const:`AF_INET`.
+ Availability: Unix.
+
+ .. versionchanged:: 3.2
+ The returned socket objects now support the whole socket API, rather
+ than a subset.
+
+
.. function:: create_connection(address[, timeout[, source_address]])
Connect to a TCP service listening on the Internet *address* (a 2-tuple
@@ -316,6 +360,40 @@
support for the :keyword:`with` statement was added.
+.. function:: fromfd(fd, family, type[, proto])
+
+ Duplicate the file descriptor *fd* (an integer as returned by a file object's
+ :meth:`fileno` method) and build a socket object from the result. Address
+ family, socket type and protocol number are as for the :func:`.socket` function
+ above. The file descriptor should refer to a socket, but this is not checked ---
+ subsequent operations on the object may fail if the file descriptor is invalid.
+ This function is rarely needed, but can be used to get or set socket options on
+ a socket passed to a program as standard input or output (such as a server
+ started by the Unix inet daemon). The socket is assumed to be in blocking mode.
+
+
+.. function:: fromshare(data)
+
+ Instantiate a socket from data obtained from the :meth:`socket.share`
+ method. The socket is assumed to be in blocking mode.
+
+ Availability: Windows.
+
+ .. versionadded:: 3.3
+
+
+.. data:: SocketType
+
+ This is a Python type object that represents the socket object type. It is the
+ same as ``type(socket(...))``.
+
+
+Other functions
+'''''''''''''''
+
+The :mod:`socket` module also offers various network-related services:
+
+
.. function:: getaddrinfo(host, port, family=0, type=0, proto=0, flags=0)
Translate the *host*/*port* argument into a sequence of 5-tuples that contain
@@ -445,46 +523,6 @@
``'udp'``, otherwise any protocol will match.
-.. function:: socket([family[, type[, proto]]])
-
- Create a new socket using the given address family, socket type and protocol
- number. The address family should be :const:`AF_INET` (the default),
- :const:`AF_INET6`, :const:`AF_UNIX`, :const:`AF_CAN` or :const:`AF_RDS`. The
- socket type should be :const:`SOCK_STREAM` (the default),
- :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_``
- constants. The protocol number is usually zero and may be omitted in that
- case or :const:`CAN_RAW` in case the address family is :const:`AF_CAN`.
-
- .. versionchanged:: 3.3
- The AF_CAN family was added.
- The AF_RDS family was added.
-
-
-.. function:: socketpair([family[, type[, proto]]])
-
- Build a pair of connected socket objects using the given address family, socket
- type, and protocol number. Address family, socket type, and protocol number are
- as for the :func:`.socket` function above. The default family is :const:`AF_UNIX`
- if defined on the platform; otherwise, the default is :const:`AF_INET`.
- Availability: Unix.
-
- .. versionchanged:: 3.2
- The returned socket objects now support the whole socket API, rather
- than a subset.
-
-
-.. function:: fromfd(fd, family, type[, proto])
-
- Duplicate the file descriptor *fd* (an integer as returned by a file object's
- :meth:`fileno` method) and build a socket object from the result. Address
- family, socket type and protocol number are as for the :func:`.socket` function
- above. The file descriptor should refer to a socket, but this is not checked ---
- subsequent operations on the object may fail if the file descriptor is invalid.
- This function is rarely needed, but can be used to get or set socket options on
- a socket passed to a program as standard input or output (such as a server
- started by the Unix inet daemon). The socket is assumed to be in blocking mode.
-
-
.. function:: ntohl(x)
Convert 32-bit positive integers from network to host byte order. On machines
@@ -680,22 +718,6 @@
.. versionadded:: 3.3
-.. function:: fromshare(data)
-
- Instantiate a socket from data obtained from :meth:`~socket.share`.
- The socket is assumed to be in blocking mode.
-
- Availability: Windows.
-
- .. versionadded:: 3.3
-
-
-.. data:: SocketType
-
- This is a Python type object that represents the socket object type. It is the
- same as ``type(socket(...))``.
-
-
.. _socket-objects:
Socket Objects
@@ -1106,14 +1128,14 @@
.. method:: socket.share(process_id)
- :platform: Windows
+ Duplicate a socket and prepare it for sharing with a target process. The
+ target process must be provided with *process_id*. The resulting bytes object
+ can then be passed to the target process using some form of interprocess
+ communication and the socket can be recreated there using :func:`fromshare`.
+ Once this method has been called, it is safe to close the socket since
+ the operating system has already duplicated it for the target process.
- Duplacet a socket and prepare it for sharing with a target process. The
- target process must be provided with *process_id*. The resulting bytes object
- can then be passed to the target process using some form of interprocess
- communication and the socket can be recreated there using :func:`fromshare`.
- Once this method has been called, it is safe to close the socket since
- the operating system has already duplicated it for the target process.
+ Availability: Windows.
.. versionadded:: 3.3
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list