ports/nrf: Upmerging port with upstream master

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.