Mirrors
/
cpython
mirror of https://github.com/python/cpython
3
0
Fork 0
Code Releases Activity
Browse Source

Tweak the socket module doc layout

pull/2332/head
Antoine Pitrou 12 years ago
parent
e3658a70c3
commit
a5cc9d68b9
1 changed files with 86 additions and 64 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 150
      Doc/library/socket.rst

150
Doc/library/socket.rst
View File

@ -138,9 +138,12 @@ generalization of this based on timeouts is supported through
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 @@ The module :mod:`socket` exports the following constants and functions:
.. versionchanged:: 3.3
This class was made a subclass of :exc:`OSError`.
Constants
^^^^^^^^^
.. data:: AF_UNIX
AF_INET
AF_INET6
@ -290,6 +297,43 @@ The module :mod:`socket` exports the following constants and functions:
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 @@ The module :mod:`socket` exports the following constants and functions:
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 @@ The module :mod:`socket` exports the following constants and functions:
``'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 @@ The module :mod:`socket` exports the following constants and functions:
.. 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 @@ to sockets.
.. 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

Write Preview
Loading…
Cancel
Save