Commit 6947a7f6 authored by Paul Sokolovsky's avatar Paul Sokolovsky
Browse files

docs/usocket: Dedent Methods section.

This was apparently of an ::only directive which was later removed.
parent f23c47fe
......@@ -117,146 +117,146 @@ class socket
Methods
-------
.. method:: socket.close
.. method:: socket.close
Mark the socket closed. Once that happens, all future operations on the socket
object will fail. The remote end will receive no more data (after queued data is flushed).
Mark the socket closed. Once that happens, all future operations on the socket
object will fail. The remote end will receive no more data (after queued data is flushed).
Sockets are automatically closed when they are garbage-collected, but it is recommended
to close() them explicitly, or to use a with statement around them.
Sockets are automatically closed when they are garbage-collected, but it is recommended
to close() them explicitly, or to use a with statement around them.
.. method:: socket.bind(address)
.. method:: socket.bind(address)
Bind the socket to address. The socket must not already be bound.
Bind the socket to address. The socket must not already be bound.
.. method:: socket.listen([backlog])
.. method:: socket.listen([backlog])
Enable a server to accept connections. If backlog is specified, it must be at least 0
(if it's lower, it will be set to 0); and specifies the number of unaccepted connections
that the system will allow before refusing new connections. If not specified, a default
reasonable value is chosen.
Enable a server to accept connections. If backlog is specified, it must be at least 0
(if it's lower, it will be set to 0); and specifies the number of unaccepted connections
that the system will allow before refusing new connections. If not specified, a default
reasonable value is chosen.
.. method:: socket.accept()
.. method:: socket.accept()
Accept a connection. The socket must be bound to an address and listening for connections.
The return value is a pair (conn, address) where conn is a new socket object usable to send
and receive data on the connection, and address is the address bound to the socket on the
other end of the connection.
Accept a connection. The socket must be bound to an address and listening for connections.
The return value is a pair (conn, address) where conn is a new socket object usable to send
and receive data on the connection, and address is the address bound to the socket on the
other end of the connection.
.. method:: socket.connect(address)
.. method:: socket.connect(address)
Connect to a remote socket at address.
Connect to a remote socket at address.
.. method:: socket.send(bytes)
.. method:: socket.send(bytes)
Send data to the socket. The socket must be connected to a remote socket.
Returns number of bytes sent, which may be smaller than the length of data
("short write").
Send data to the socket. The socket must be connected to a remote socket.
Returns number of bytes sent, which may be smaller than the length of data
("short write").
.. method:: socket.sendall(bytes)
.. method:: socket.sendall(bytes)
Send all data to the socket. The socket must be connected to a remote socket.
Unlike ``send()``, this method will try to send all of data, by sending data
chunk by chunk consecutively.
Send all data to the socket. The socket must be connected to a remote socket.
Unlike ``send()``, this method will try to send all of data, by sending data
chunk by chunk consecutively.
The behavior of this method on non-blocking sockets is undefined. Due to this,
on MicroPython, it's recommended to use ``write()`` method instead, which
has the same "no short writes" policy for blocking sockets, and will return
number of bytes sent on non-blocking sockets.
The behavior of this method on non-blocking sockets is undefined. Due to this,
on MicroPython, it's recommended to use ``write()`` method instead, which
has the same "no short writes" policy for blocking sockets, and will return
number of bytes sent on non-blocking sockets.
.. method:: socket.recv(bufsize)
.. method:: socket.recv(bufsize)
Receive data from the socket. The return value is a bytes object representing the data
received. The maximum amount of data to be received at once is specified by bufsize.
Receive data from the socket. The return value is a bytes object representing the data
received. The maximum amount of data to be received at once is specified by bufsize.
.. method:: socket.sendto(bytes, address)
.. method:: socket.sendto(bytes, address)
Send data to the socket. The socket should not be connected to a remote socket, since the
destination socket is specified by `address`.
Send data to the socket. The socket should not be connected to a remote socket, since the
destination socket is specified by `address`.
.. method:: socket.recvfrom(bufsize)
.. method:: socket.recvfrom(bufsize)
Receive data from the socket. The return value is a pair (bytes, address) where bytes is a
bytes object representing the data received and address is the address of the socket sending
the data.
Receive data from the socket. The return value is a pair (bytes, address) where bytes is a
bytes object representing the data received and address is the address of the socket sending
the data.
.. method:: socket.setsockopt(level, optname, value)
.. method:: socket.setsockopt(level, optname, value)
Set the value of the given socket option. The needed symbolic constants are defined in the
socket module (SO_* etc.). The value can be an integer or a bytes-like object representing
a buffer.
Set the value of the given socket option. The needed symbolic constants are defined in the
socket module (SO_* etc.). The value can be an integer or a bytes-like object representing
a buffer.
.. method:: socket.settimeout(value)
.. method:: socket.settimeout(value)
Set a timeout on blocking socket operations. The value argument can be a nonnegative floating
point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations
will raise an ``OSError`` exception if the timeout period value has elapsed before the operation has
completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket
is put in blocking mode.
Set a timeout on blocking socket operations. The value argument can be a nonnegative floating
point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations
will raise an ``OSError`` exception if the timeout period value has elapsed before the operation has
completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket
is put in blocking mode.
.. admonition:: Difference to CPython
:class: attention
.. admonition:: Difference to CPython
:class: attention
CPython raises a ``socket.timeout`` exception in case of timeout,
which is an ``OSError`` subclass. MicroPython raises an OSError directly
instead. If you use ``except OSError:`` to catch the exception,
your code will work both in MicroPython and CPython.
CPython raises a ``socket.timeout`` exception in case of timeout,
which is an ``OSError`` subclass. MicroPython raises an OSError directly
instead. If you use ``except OSError:`` to catch the exception,
your code will work both in MicroPython and CPython.
.. method:: socket.setblocking(flag)
.. method:: socket.setblocking(flag)
Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking,
else to blocking mode.
Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking,
else to blocking mode.
This method is a shorthand for certain ``settimeout()`` calls:
This method is a shorthand for certain ``settimeout()`` calls:
* ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)``
* ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0)``
* ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)``
* ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0)``
.. method:: socket.makefile(mode='rb', buffering=0)
.. method:: socket.makefile(mode='rb', buffering=0)
Return a file object associated with the socket. The exact returned type depends on the arguments
given to makefile(). The support is limited to binary modes only ('rb', 'wb', and 'rwb').
CPython's arguments: ``encoding``, ``errors`` and ``newline`` are not supported.
Return a file object associated with the socket. The exact returned type depends on the arguments
given to makefile(). The support is limited to binary modes only ('rb', 'wb', and 'rwb').
CPython's arguments: ``encoding``, ``errors`` and ``newline`` are not supported.
.. admonition:: Difference to CPython
:class: attention
.. admonition:: Difference to CPython
:class: attention
As MicroPython doesn't support buffered streams, values of ``buffering``
parameter is ignored and treated as if it was 0 (unbuffered).
As MicroPython doesn't support buffered streams, values of ``buffering``
parameter is ignored and treated as if it was 0 (unbuffered).
.. admonition:: Difference to CPython
:class: attention
.. admonition:: Difference to CPython
:class: attention
Closing the file object returned by makefile() WILL close the
original socket as well.
Closing the file object returned by makefile() WILL close the
original socket as well.
.. method:: socket.read([size])
.. method:: socket.read([size])
Read up to size bytes from the socket. Return a bytes object. If ``size`` is not given, it
reads all data available from the socket until ``EOF``; as such the method will not return until
the socket is closed. This function tries to read as much data as
requested (no "short reads"). This may be not possible with
non-blocking socket though, and then less data will be returned.
Read up to size bytes from the socket. Return a bytes object. If ``size`` is not given, it
reads all data available from the socket until ``EOF``; as such the method will not return until
the socket is closed. This function tries to read as much data as
requested (no "short reads"). This may be not possible with
non-blocking socket though, and then less data will be returned.
.. method:: socket.readinto(buf[, nbytes])
.. method:: socket.readinto(buf[, nbytes])
Read bytes into the ``buf``. If ``nbytes`` is specified then read at most
that many bytes. Otherwise, read at most ``len(buf)`` bytes. Just as
``read()``, this method follows "no short reads" policy.
Read bytes into the ``buf``. If ``nbytes`` is specified then read at most
that many bytes. Otherwise, read at most ``len(buf)`` bytes. Just as
``read()``, this method follows "no short reads" policy.
Return value: number of bytes read and stored into ``buf``.
Return value: number of bytes read and stored into ``buf``.
.. method:: socket.readline()
.. method:: socket.readline()
Read a line, ending in a newline character.
Read a line, ending in a newline character.
Return value: the line read.
Return value: the line read.
.. method:: socket.write(buf)
.. method:: socket.write(buf)
Write the buffer of bytes to the socket. This function will try to
write all data to a socket (no "short writes"). This may be not possible
with a non-blocking socket though, and returned value will be less than
the length of ``buf``.
Write the buffer of bytes to the socket. This function will try to
write all data to a socket (no "short writes"). This may be not possible
with a non-blocking socket though, and returned value will be less than
the length of ``buf``.
Return value: number of bytes written.
Return value: number of bytes written.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment