:mod:`socket`
=============

.. py:module:: socket

.. autoapi-nested-parse::

   TCP, UDP and RAW socket support

   Create TCP, UDP and RAW sockets for communicating over the Internet.





.. py:class:: socket(family: int, type: int, proto: int)

   .. method:: bind(self, address: tuple)


      Bind a socket to an address

      :param ~tuple address: tuple of (remote_address, remote_port)


   .. method:: listen(self, backlog: int)


      Set socket to listen for incoming connections

      :param ~int backlog: length of backlog queue for waiting connetions


   .. method:: accept(self)


      Accept a connection on a listening socket of type SOCK_STREAM,
      creating a new socket of type SOCK_STREAM.
      Returns a tuple of (new_socket, remote_address)


   .. method:: connect(self, address: tuple)


      Connect a socket to a remote address

      :param ~tuple address: tuple of (remote_address, remote_port)


   .. method:: send(self, bytes: bytes)


      Send some bytes to the connected remote address.
      Suits sockets of type SOCK_STREAM

      :param ~bytes bytes: some bytes to send


   .. method:: recv_into(self, buffer: bytearray, bufsize: int)


      Reads some bytes from the connected remote address, writing
      into the provided buffer. If bufsize <= len(buffer) is given,
      a maximum of bufsize bytes will be read into the buffer. If no
      valid value is given for bufsize, the default is the length of
      the given buffer.

      Suits sockets of type SOCK_STREAM
      Returns an int of number of bytes read.

      :param bytearray buffer: buffer to receive into
      :param int bufsize: optionally, a maximum number of bytes to read.


   .. method:: recv(self, bufsize: int)


      Reads some bytes from the connected remote address.
      Suits sockets of type SOCK_STREAM
      Returns a bytes() of length <= bufsize

      :param ~int bufsize: maximum number of bytes to receive


   .. method:: sendto(self, bytes: bytes, address: tuple)


      Send some bytes to a specific address.
      Suits sockets of type SOCK_DGRAM

      :param ~bytes bytes: some bytes to send
      :param ~tuple address: tuple of (remote_address, remote_port)


   .. method:: recvfrom(self, bufsize: int)


      Reads some bytes from the connected remote address.
      Suits sockets of type SOCK_STREAM

      Returns a tuple containing
      * a bytes() of length <= bufsize
      * a remote_address, which is a tuple of ip address and port number

      :param ~int bufsize: maximum number of bytes to receive


   .. method:: setsockopt(self, level: Any, optname: Any, value: Any)


      Sets socket options


   .. method:: settimeout(self, value: int)


      Set the timeout value for this socket.

      :param ~int value: timeout in seconds.  0 means non-blocking.  None means block indefinitely.


   .. method:: setblocking(self, flag: bool)


      Set the blocking behaviour of this socket.

      :param ~bool flag: False means non-blocking, True means block indefinitely.



.. function:: getaddrinfo(host: Any, port: Any) -> Any

   Gets the address information for a hostname and port

   Returns the appropriate family, socket type, socket protocol and
   address information to call socket.socket() and socket.connect() with,
   as a tuple.