3 files changed, 56 insertions, 14 deletions
diff --git a/examples/network/http_client.py b/examples/network/http_client.py
index 661c286b7..879cddcd8 100644
--- a/examples/network/http_client.py
+++ b/examples/network/http_client.py
@@ -1,16 +1,35 @@
-import socket
+# Very simple HTTP client example:
+# - Connects to a server.
+# - Sends a HTTP request.
+# - Reads the result.
+#
+# This example works in both MicroPython and CPython.
+#
+# To implement an HTTP client using less code, use mip to install the requests package:
+# https://github.com/micropython/micropython-lib/tree/master/python-ecosys/requests
 
+import socket
 
-def main(use_stream=False):
-    s = socket.socket()
 
-    ai = socket.getaddrinfo("google.com", 80)
+# `addr_family` selects IPv4 vs IPv6: 0 means either, or use
+# socket.AF_INET or socket.AF_INET6 to select a particular one.
+def main(domain, addr_family=0, use_stream=False):
+    # Lookup the server address, for the given family and socket type.
+    ai = socket.getaddrinfo(domain, 80, addr_family, socket.SOCK_STREAM)
     print("Address infos:", ai)
-    addr = ai[0][-1]
 
+    # Select the first address.
+    ai = ai[0]
+
+    # Create a socket with the server's family, type and proto.
+    s = socket.socket(ai[0], ai[1], ai[2])
+
+    # Connect to the server.
+    addr = ai[-1]
     print("Connect address:", addr)
     s.connect(addr)
 
+    # Send request and read response.
     if use_stream:
         # MicroPython socket objects support stream (aka file) interface
         # directly, but the line below is needed for CPython.
@@ -21,7 +40,8 @@ def main(use_stream=False):
         s.send(b"GET / HTTP/1.0\r\n\r\n")
         print(s.recv(4096))
 
+    # Close the socket.
     s.close()
 
 
-main()
+main("google.com")
diff --git a/examples/network/https_client.py b/examples/network/https_client.py
index 323971c0e..d20f283d7 100644
--- a/examples/network/https_client.py
+++ b/examples/network/https_client.py
@@ -1,20 +1,41 @@
+# Very simple HTTPS client example:
+# - Connects to a server.
+# - Upgrades the connection to a TLS connection.
+# - Sends a HTTP request.
+# - Reads the result.
+#
+# This example works in both MicroPython and CPython.
+#
+# To implement an HTTPS client using less code, use mip to install the requests package:
+# https://github.com/micropython/micropython-lib/tree/master/python-ecosys/requests
+
 import socket
 import ssl
 
 
-def main(use_stream=True):
-    s = socket.socket()
-
-    ai = socket.getaddrinfo("google.com", 443)
+# `addr_family` selects IPv4 vs IPv6: 0 means either, or use
+# socket.AF_INET or socket.AF_INET6 to select a particular one.
+def main(domain, addr_family=0, use_stream=True):
+    # Lookup the server address, for the given family and socket type.
+    ai = socket.getaddrinfo(domain, 443, addr_family, socket.SOCK_STREAM)
     print("Address infos:", ai)
-    addr = ai[0][-1]
 
+    # Select the first address.
+    ai = ai[0]
+
+    # Create a socket with the server's family, type and proto.
+    s = socket.socket(ai[0], ai[1], ai[2])
+
+    # Connect to the server.
+    addr = ai[-1]
     print("Connect address:", addr)
     s.connect(addr)
 
+    # Upgrade the socket to a TLS connection.
     s = ssl.wrap_socket(s)
     print(s)
 
+    # Send request and read response.
     if use_stream:
         # Both CPython and MicroPython SSLSocket objects support read() and
         # write() methods.
@@ -26,7 +47,8 @@ def main(use_stream=True):
         s.send(b"GET / HTTP/1.0\r\n\r\n")
         print(s.recv(4096))
 
+    # Close the socket.
     s.close()
 
 
-main()
+main("google.com")
diff --git a/examples/network/https_client_nonblocking.py b/examples/network/https_client_nonblocking.py
index 6e6b7f37b..41447e81e 100644
--- a/examples/network/https_client_nonblocking.py
+++ b/examples/network/https_client_nonblocking.py
@@ -37,13 +37,13 @@ def read_nonblocking(poller, sock, n):
     return data
 
 
-def main(url):
+def main(url, addr_family=0):
     # Split the given URL into components.
     proto, _, host, path = url.split(b"/", 3)
     assert proto == b"https:"
 
     # Note: this getaddrinfo() call is blocking!
-    ai = socket.getaddrinfo(host, 443)[0]
+    ai = socket.getaddrinfo(host, 443, addr_family, socket.SOCK_STREAM)[0]
     addr = ai[-1]
     print("Connect address:", addr)