mirror of
https://github.com/licsber/micropython.git
synced 2024-09-20 00:50:24 +08:00
docs/usocket: Dedent Methods section.
This was apparently of an ::only directive which was later removed.
This commit is contained in:
Paul Sokolovsky
parent
f23c47fea7
commit
6947a7f6a9
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user