From a94de2adde662a8ba0b836ecb312f37e4b409882 Mon Sep 17 00:00:00 2001
From: Ethan Dalool <git@voussoir.net>
Date: Sun, 10 Oct 2021 12:06:54 -0700
Subject: [PATCH] Add some docstrings, return annotations.

---
 voussoirkit/networktools.py | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/voussoirkit/networktools.py b/voussoirkit/networktools.py
index b7a4b68..69e6563 100644
--- a/voussoirkit/networktools.py
+++ b/voussoirkit/networktools.py
@@ -23,14 +23,14 @@ class NetworkToolsException(Exception):
 class NoInternet(NetworkToolsException):
     pass
 
-def get_external_ip():
+def get_external_ip() -> str:
     url = 'https://voussoir.net/whatsmyip'
     response = requests.get(url)
     response.raise_for_status()
     ip = response.text.strip()
     return ip
 
-def get_lan_ip():
+def get_lan_ip() -> str:
     '''
     thank you unknwntech
     https://stackoverflow.com/a/166589
@@ -47,7 +47,10 @@ def has_lan():
     # Open a socket to the router
     raise NotImplementedError
 
-def has_internet(timeout=2):
+def has_internet(timeout=2) -> bool:
+    '''
+    Return True if an internet connection is available.
+    '''
     socket.setdefaulttimeout(timeout)
     try:
         sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
@@ -56,7 +59,16 @@ def has_internet(timeout=2):
     except socket.error as exc:
         return False
 
-def wait_for_internet(timeout):
+def wait_for_internet(timeout) -> None:
+    '''
+    This function blocks until an internet connection is available, or the
+    timeout is reached.
+
+    Raises NoInternet if the timeout expires.
+    '''
+    if timeout <= 0:
+        raise ValueError(f'timeout should be greater than 0, not {timeout}.')
+
     started = time.time()
     while True:
         if time.time() - started >= timeout: