mirror of
https://github.com/python/cpython.git
synced 2025-09-26 18:29:57 +00:00
Tweak the socket module doc layout
This commit is contained in:
Antoine Pitrou
parent
e3658a70c3
commit
a5cc9d68b9
1 changed files with 86 additions and 64 deletions
|
|
@ -138,9 +138,12 @@ generalization of this based on timeouts is supported through
|
||||||
Module contents
|
Module contents
|
||||||
---------------
|
---------------
|
||||||
|
|
||||||
The module :mod:`socket` exports the following constants and functions:
|
The module :mod:`socket` exports the following elements.
|
||||||
|
|
||||||
|
|
||||||
|
Exceptions
|
||||||
|
^^^^^^^^^^
|
||||||
|
|
||||||
.. exception:: error
|
.. exception:: error
|
||||||
|
|
||||||
A deprecated alias of :exc:`OSError`.
|
A deprecated alias of :exc:`OSError`.
|
||||||
|
|
@ -186,6 +189,10 @@ The module :mod:`socket` exports the following constants and functions:
|
||||||
.. versionchanged:: 3.3
|
.. versionchanged:: 3.3
|
||||||
This class was made a subclass of :exc:`OSError`.
|
This class was made a subclass of :exc:`OSError`.
|
||||||
|
|
||||||
|
|
||||||
|
Constants
|
||||||
|
^^^^^^^^^
|
||||||
|
|
||||||
.. data:: AF_UNIX
|
.. data:: AF_UNIX
|
||||||
AF_INET
|
AF_INET
|
||||||
AF_INET6
|
AF_INET6
|
||||||
|
|
@ -290,6 +297,43 @@ The module :mod:`socket` exports the following constants and functions:
|
||||||
this platform.
|
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]])
|
.. function:: create_connection(address[, timeout[, source_address]])
|
||||||
|
|
||||||
Connect to a TCP service listening on the Internet *address* (a 2-tuple
|
Connect to a TCP service listening on the Internet *address* (a 2-tuple
|
||||||
|
|
@ -316,6 +360,40 @@ The module :mod:`socket` exports the following constants and functions:
|
||||||
support for the :keyword:`with` statement was added.
|
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)
|
.. 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
|
Translate the *host*/*port* argument into a sequence of 5-tuples that contain
|
||||||
|
|
@ -445,46 +523,6 @@ The module :mod:`socket` exports the following constants and functions:
|
||||||
``'udp'``, otherwise any protocol will match.
|
``'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)
|
.. function:: ntohl(x)
|
||||||
|
|
||||||
Convert 32-bit positive integers from network to host byte order. On machines
|
Convert 32-bit positive integers from network to host byte order. On machines
|
||||||
|
|
@ -680,22 +718,6 @@ The module :mod:`socket` exports the following constants and functions:
|
||||||
.. versionadded:: 3.3
|
.. 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:
|
||||||
|
|
||||||
Socket Objects
|
Socket Objects
|
||||||
|
|
@ -1106,14 +1128,14 @@ to sockets.
|
||||||
|
|
||||||
.. method:: socket.share(process_id)
|
.. 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
|
Availability: Windows.
|
||||||
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.
|
|
||||||
|
|
||||||
.. versionadded:: 3.3
|
.. versionadded:: 3.3
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue