`socket` — socket module¶

This module provides access to the BSD socket interface.

Difference to CPython

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 socket module is an opaque data type returned by getaddrinfo() function, which must be used to resolve textual address (including numeric addresses):

sockaddr = socket.getaddrinfo('www.micropython.org', 80)[0][-1]
# You must use getaddrinfo() even for numeric addresses
sockaddr = socket.getaddrinfo('127.0.0.1', 80)[0][-1]
# Now you can use that address
sock.connect(sockaddr)

Using getaddrinfo() is the most efficient (both in terms of memory and processing power) and portable way to work with addresses.

The socket module also provides a CPython-compatible way to specify addresses using tuples, as described below. On the OpenMV Cam the socket module is built in; numeric addresses may be given directly in the tuple format, but domain names must first be resolved with getaddrinfo().

Summing up:

Always use getaddrinfo() to resolve host names.
Tuple addresses described below can be used as a shortcut for numeric addresses, for quick hacks and interactive use.

Tuple address format for the 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 an integer port number in the range 1-65535. Domain names are not accepted as ipv4_address; resolve them first using 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. Domain names are not accepted as ipv6_address; resolve them first using getaddrinfo().

Functions¶

socket.getaddrinfo(host: str, port: int, af: int = 0, type: int = 0, proto: int = 0, flags: int = 0, /) → List[Tuple]¶

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. Arguments af, type, and proto (which have the same meaning as for the socket function) can be used to filter which kind of addresses are returned. If a parameter is not specified or zero, all combinations of addresses can be returned (requiring filtering on the user side).

The resulting list of 5-tuples has the following structure:

(family, type, proto, canonname, sockaddr)

The following example shows how to connect to a given url:

s = socket.socket()
# This assumes that if "type" is not specified, an address for
# SOCK_STREAM will be returned, which may be not true
s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][-1])

Recommended use of filtering params:

s = socket.socket()
# Guaranteed to return an address which can be connect'ed to for
# stream operation.
s.connect(socket.getaddrinfo('www.micropython.org', 80, 0, SOCK_STREAM)[0][-1])

Difference to CPython

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 errno 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.

socket.inet_ntop(af: int, bin_addr: bytes) → str¶

Convert a binary network address bin_addr of the given address family af to a textual representation:

>>> socket.inet_ntop(socket.AF_INET, b"\x7f\0\0\1")
'127.0.0.1'

socket.inet_pton(af: int, txt_addr: str) → bytes¶

Convert a textual network address txt_addr of the given address family af to a binary representation:

>>> socket.inet_pton(socket.AF_INET, "1.2.3.4")
b'\x01\x02\x03\x04'

Constants¶

socket.AF_INET: int¶: IPv4 address family.

socket.AF_INET6: int¶: IPv6 address family.

socket.SOCK_STREAM: int¶: Stream (TCP) socket type.

socket.SOCK_DGRAM: int¶: Datagram (UDP) socket type.

socket.SOCK_RAW: int¶: Raw socket type.

socket.IPPROTO_IP: int¶: The IP protocol level. Used as the level argument to setsockopt() together with the IP_* options.

socket.IPPROTO_TCP: int¶: The TCP protocol. You do not need to pass this to socket (the SOCK_STREAM socket type selects it automatically); its only real use is as the level argument to setsockopt() together with the TCP_* options.

socket.SOL_SOCKET: int¶: The socket option level. Used as the level argument to setsockopt() together with the SO_* options.

socket.SO_REUSEADDR: int¶: Allow the socket to bind to an address/port that is still in the TIME_WAIT state.

socket.SO_BROADCAST: int¶: Permit sending datagrams to a broadcast address.

socket.SO_KEEPALIVE: int¶: Enable periodic transmission of keep-alive probes on a connected socket.

socket.SO_SNDTIMEO: int¶: Send timeout, in milliseconds, passed as the value argument to setsockopt().

socket.SO_RCVTIMEO: int¶: Receive timeout, in milliseconds, passed as the value argument to setsockopt().

socket.IP_ADD_MEMBERSHIP: int¶: Join a multicast group. An IPPROTO_IP-level setsockopt() option.

socket.IP_DROP_MEMBERSHIP: int¶: Leave a multicast group. An IPPROTO_IP-level setsockopt() option.

socket.TCP_NODELAY: int¶: Disable Nagle’s algorithm. An IPPROTO_TCP-level setsockopt() option.

socket.MSG_PEEK: int¶: For recv() / recvfrom(): return data without removing it from the input queue.

socket.MSG_DONTWAIT: int¶: For recv() / recvfrom(): perform the operation in non-blocking mode.

Classes¶

class socket.socket(af: int = AF_INET, type: int = SOCK_STREAM, proto: int = IPPROTO_TCP, /)¶

Create a new socket using the given address family, socket type and protocol number. Specifying proto is in most cases not required (and not recommended); the type argument selects the needed protocol automatically:

# Create STREAM TCP socket
socket(AF_INET, SOCK_STREAM)
# Create DGRAM UDP socket
socket(AF_INET, SOCK_DGRAM)

close() → None¶

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.

bind(address: Any) → None¶: Bind the socket to address. The socket must not already be bound.

listen(backlog: int = 2) → None¶: 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.

accept() → Tuple['socket', Tuple]¶: 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.

connect(address: Any) → None¶: Connect to a remote socket at address.

send(bytes: bytes) → int¶: 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”).

sendall(bytes: bytes) → None¶

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 behaviour 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.

recv(bufsize: int, flags: int = 0) → bytes¶

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.

The optional flags argument is a bitwise OR of message flags (MSG_PEEK, MSG_DONTWAIT), which have the same meaning as in CPython.

sendto(bytes: bytes, address: Any) → int¶: Send data to the socket. The socket should not be connected to a remote socket, since the destination socket is specified by address.

recvfrom(bufsize: int, flags: int = 0) → Tuple[bytes, Tuple]¶

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.

See the recv() function for an explanation of the optional flags argument.

setsockopt(level: int, optname: int, value: int | bytes) → None¶: 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.

settimeout(value: float | None) → None¶

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.

A portable and generic alternative is to use a select.poll object. This allows waiting 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 = select.poll()
poller.register(s, select.POLLIN)
res = poller.poll(1000)  # time in milliseconds
if not res:
    # s is still not ready for input, i.e. operation timed out

Difference to 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.

setblocking(flag: bool) → None¶

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)

makefile(mode: str = 'rb', buffering: int = 0, /) → Any¶: 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.

Difference to CPython

As MicroPython doesn’t support buffered streams, values of buffering parameter is ignored and treated as if it was 0 (unbuffered).

Difference to CPython

Closing the file object returned by makefile() WILL close the original socket as well.

read(size: int | None = None) → bytes¶: 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.

readinto(buf: bytearray | memoryview, nbytes: int | None = None) → int¶

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.

readline() → bytes¶

Read a line, ending in a newline character.

Return value: the line read.

write(buf: bytes) → int¶

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.

Note

MicroPython does not implement socket.error. CPython has a deprecated socket.error exception that is an alias of OSError; in MicroPython, use OSError directly to catch socket-related errors.

socket — socket module¶

Socket address format(s)¶

Functions¶

Constants¶

Classes¶

`socket` — socket module¶