340 lines
13 KiB
ReStructuredText
340 lines
13 KiB
ReStructuredText
*******************************
|
|
:mod:`usocket` -- socket module
|
|
*******************************
|
|
|
|
.. module:: usocket
|
|
:synopsis: socket module
|
|
|
|
|see_cpython_module| :mod:`python:socket`.
|
|
|
|
This module provides access to the BSD socket interface.
|
|
|
|
.. admonition:: Difference to CPython
|
|
:class: attention
|
|
|
|
For efficiency and consistency, socket objects in MicroPython implement a `stream`
|
|
(file-like) interface directly. In CPython, you need to convert a socket to
|
|
a file-like object using `makefile()` method. This method is still supported
|
|
by MicroPython (but is a no-op), so where compatibility with CPython matters,
|
|
be sure to use it.
|
|
|
|
Socket address format(s)
|
|
------------------------
|
|
|
|
The native socket address format of the ``usocket`` module is an opaque data type
|
|
returned by `getaddrinfo` function, which must be used to resolve textual address
|
|
(including numeric addresses)::
|
|
|
|
sockaddr = usocket.getaddrinfo('www.micropython.org', 80)[0][-1]
|
|
# You must use getaddrinfo() even for numeric addresses
|
|
sockaddr = usocket.getaddrinfo('127.0.0.1', 80)[0][-1]
|
|
# Now you can use that address
|
|
sock.connect(addr)
|
|
|
|
Using `getaddrinfo` is the most efficient (both in terms of memory and processing
|
|
power) and portable way to work with addresses.
|
|
|
|
However, ``socket`` module (note the difference with native MicroPython
|
|
``usocket`` module described here) provides CPython-compatible way to specify
|
|
addresses using tuples, as described below. Note that depending on a
|
|
`MicroPython port`, ``socket`` module can be builtin or need to be
|
|
installed from `micropython-lib` (as in the case of `MicroPython Unix port`),
|
|
and some ports still accept only numeric addresses in the tuple format,
|
|
and require to use `getaddrinfo` function to resolve domain names.
|
|
|
|
Summing up:
|
|
|
|
* Always use `getaddrinfo` when writing portable applications.
|
|
* Tuple addresses described below can be used as a shortcut for
|
|
quick hacks and interactive use, if your port supports them.
|
|
|
|
Tuple address format for ``socket`` module:
|
|
|
|
* IPv4: *(ipv4_address, port)*, where *ipv4_address* is a string with
|
|
dot-notation numeric IPv4 address, e.g. ``"8.8.8.8"``, and *port* is and
|
|
integer port number in the range 1-65535. Note the domain names are not
|
|
accepted as *ipv4_address*, they should be resolved first using
|
|
`usocket.getaddrinfo()`.
|
|
* IPv6: *(ipv6_address, port, flowinfo, scopeid)*, where *ipv6_address*
|
|
is a string with colon-notation numeric IPv6 address, e.g. ``"2001:db8::1"``,
|
|
and *port* is an integer port number in the range 1-65535. *flowinfo*
|
|
must be 0. *scopeid* is the interface scope identifier for link-local
|
|
addresses. Note the domain names are not accepted as *ipv6_address*,
|
|
they should be resolved first using `usocket.getaddrinfo()`. Availability
|
|
of IPv6 support depends on a `MicroPython port`.
|
|
|
|
Functions
|
|
---------
|
|
|
|
.. function:: socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP)
|
|
|
|
Create a new socket using the given address family, socket type and
|
|
protocol number. Note that specifying *proto* in most cases is not
|
|
required (and not recommended, as some MicroPython ports may omit
|
|
``IPPROTO_*`` constants). Instead, *type* argument will select needed
|
|
protocol automatically::
|
|
|
|
# Create STREAM TCP socket
|
|
socket(AF_INET, SOCK_STREAM)
|
|
# Create DGRAM UDP socket
|
|
socket(AF_INET, SOCK_DGRAM)
|
|
|
|
.. function:: getaddrinfo(host, port)
|
|
|
|
Translate the host/port argument into a sequence of 5-tuples that contain all the
|
|
necessary arguments for creating a socket connected to that service. The list of
|
|
5-tuples has following structure::
|
|
|
|
(family, type, proto, canonname, sockaddr)
|
|
|
|
The following example shows how to connect to a given url::
|
|
|
|
s = usocket.socket()
|
|
s.connect(usocket.getaddrinfo('www.micropython.org', 80)[0][-1])
|
|
|
|
.. admonition:: Difference to CPython
|
|
:class: attention
|
|
|
|
CPython raises a ``socket.gaierror`` exception (`OSError` subclass) in case
|
|
of error in this function. MicroPython doesn't have ``socket.gaierror``
|
|
and raises OSError directly. Note that error numbers of `getaddrinfo()`
|
|
form a separate namespace and may not match error numbers from
|
|
the :mod:`uerrno` module. To distinguish `getaddrinfo()` errors, they are
|
|
represented by negative numbers, whereas standard system errors are
|
|
positive numbers (error numbers are accessible using ``e.args[0]`` property
|
|
from an exception object). The use of negative values is a provisional
|
|
detail which may change in the future.
|
|
|
|
.. function:: inet_ntop(af, bin_addr)
|
|
|
|
Convert a binary network address *bin_addr* of the given address family *af*
|
|
to a textual representation::
|
|
|
|
>>> usocket.inet_ntop(usocket.AF_INET, b"\x7f\0\0\1")
|
|
'127.0.0.1'
|
|
|
|
.. function:: inet_pton(af, txt_addr)
|
|
|
|
Convert a textual network address *txt_addr* of the given address family *af*
|
|
to a binary representation::
|
|
|
|
>>> usocket.inet_pton(usocket.AF_INET, "1.2.3.4")
|
|
b'\x01\x02\x03\x04'
|
|
|
|
Constants
|
|
---------
|
|
|
|
.. data:: AF_INET
|
|
AF_INET6
|
|
|
|
Address family types. Availability depends on a particular `MicroPython port`.
|
|
|
|
.. data:: SOCK_STREAM
|
|
SOCK_DGRAM
|
|
|
|
Socket types.
|
|
|
|
.. data:: IPPROTO_UDP
|
|
IPPROTO_TCP
|
|
|
|
IP protocol numbers. Availability depends on a particular `MicroPython port`.
|
|
Note that you don't need to specify these in a call to `usocket.socket()`,
|
|
because `SOCK_STREAM` socket type automatically selects `IPPROTO_TCP`, and
|
|
`SOCK_DGRAM` - `IPPROTO_UDP`. Thus, the only real use of these constants
|
|
is as an argument to `setsockopt()`.
|
|
|
|
.. data:: usocket.SOL_*
|
|
|
|
Socket option levels (an argument to `setsockopt()`). The exact
|
|
inventory depends on a `MicroPython port`.
|
|
|
|
.. data:: usocket.SO_*
|
|
|
|
Socket options (an argument to `setsockopt()`). The exact
|
|
inventory depends on a `MicroPython port`.
|
|
|
|
Constants specific to WiPy:
|
|
|
|
.. data:: IPPROTO_SEC
|
|
|
|
Special protocol value to create SSL-compatible socket.
|
|
|
|
class socket
|
|
============
|
|
|
|
Methods
|
|
-------
|
|
|
|
.. method:: socket.close()
|
|
|
|
Mark the socket closed and release all resources. Once that happens, all future operations
|
|
on the socket object will fail. The remote end will receive EOF indication if
|
|
supported by protocol.
|
|
|
|
Sockets are automatically closed when they are garbage-collected, but it is recommended
|
|
to `close()` them explicitly as soon you finished working with them.
|
|
|
|
.. method:: socket.bind(address)
|
|
|
|
Bind the socket to *address*. The socket must not already be bound.
|
|
|
|
.. 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.
|
|
|
|
.. 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.
|
|
|
|
.. method:: socket.connect(address)
|
|
|
|
Connect to a remote socket at *address*.
|
|
|
|
.. 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").
|
|
|
|
.. 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.
|
|
|
|
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)
|
|
|
|
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)
|
|
|
|
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)
|
|
|
|
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)
|
|
|
|
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)
|
|
|
|
**Note**: Not every port supports this method, see below.
|
|
|
|
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.
|
|
|
|
Not every `MicroPython port` supports this method. A more portable and
|
|
generic solution is to use `uselect.poll` object. This allows to wait on
|
|
multiple objects at the same time (and not just on sockets, but on generic
|
|
`stream` objects which support polling). Example::
|
|
|
|
# Instead of:
|
|
s.settimeout(1.0) # time in seconds
|
|
s.read(10) # may timeout
|
|
|
|
# Use:
|
|
poller = uselect.poll()
|
|
poller.register(s, uselect.POLLIN)
|
|
res = poller.poll(1000) # time in milliseconds
|
|
if not res:
|
|
# s is still not ready for input, i.e. operation timed out
|
|
|
|
.. 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.
|
|
|
|
.. 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.
|
|
|
|
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)``
|
|
|
|
.. 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.
|
|
|
|
.. 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).
|
|
|
|
.. admonition:: Difference to CPython
|
|
:class: attention
|
|
|
|
Closing the file object returned by makefile() WILL close the
|
|
original socket as well.
|
|
|
|
.. 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.
|
|
|
|
.. 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.
|
|
|
|
Return value: number of bytes read and stored into *buf*.
|
|
|
|
.. method:: socket.readline()
|
|
|
|
Read a line, ending in a newline character.
|
|
|
|
Return value: the line read.
|
|
|
|
.. 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*.
|
|
|
|
Return value: number of bytes written.
|
|
|
|
.. exception:: usocket.error
|
|
|
|
MicroPython does NOT have this exception.
|
|
|
|
.. admonition:: Difference to CPython
|
|
:class: attention
|
|
|
|
CPython used to have a ``socket.error`` exception which is now deprecated,
|
|
and is an alias of `OSError`. In MicroPython, use `OSError` directly.
|