Skip to content
Snippets Groups Projects
Select Git revision
  • ed9c0185d80514670244b0c2147958dea00159a9
  • master default protected
2 results

usocket.rst

Blame
  • user avatar
    Damien George authored
    11a7a70a
    History
    usocket.rst 13.45 KiB

    :mod:`usocket` -- socket module

    |see_cpython_module| :mod:`python:socket`.

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

    Constants

    Constants specific to WiPy:

    class socket

    Methods