diff options
Diffstat (limited to 'docs/library/usocket.rst')
| -rw-r--r-- | docs/library/usocket.rst | 66 |
1 files changed, 53 insertions, 13 deletions
diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index 70d4f49fc..dfdcd68bc 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -12,12 +12,6 @@ This module provides access to the BSD socket interface. .. 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. - -.. 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 @@ -27,11 +21,47 @@ This module provides access to the BSD socket interface. Socket address format(s) ------------------------ -The functions below which expect a network address, accept it in the format of -*(ipv4_address, port)*, where *ipv4_address* is a string with dot-notation numeric -IPv4 address, e.g. ``"8.8.8.8"``, and port is 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()`. +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 --------- @@ -87,12 +117,12 @@ Constants .. data:: usocket.SOL_* Socket option levels (an argument to `setsockopt()`). The exact - inventory depends on a MicroPython port. + inventory depends on a `MicroPython port`. .. data:: usocket.SO_* Socket options (an argument to `setsockopt()`). The exact - inventory depends on a MicroPython port. + inventory depends on a `MicroPython port`. Constants specific to WiPy: @@ -250,3 +280,13 @@ Methods the length of *buf*. Return value: number of bytes written. + +.. exception:: socket.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. |