diff options
| -rw-r--r-- | docs/library/usocket.rst | 190 |
1 files changed, 95 insertions, 95 deletions
diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index a750497270..dd0f5708ba 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -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. |