A few docstring improvements.

voussoirkit/bytestring.py

@@ -109,10 +109,13 @@ def bytestring(size, decimal_places=3, force_unit=None):
 def get_appropriate_divisor(size):
     '''
     Return the divisor that would be appropriate for displaying this byte size.
-    For example:
+
-        1000 => 1 to display 1,000 b
+    >>> get_appropriate_divisor(1000)
-        1024 => 1024 to display 1 KiB
+    1
-        123456789 => 1048576 to display 117.738 MiB
+    >>> get_appropriate_divisor(1024)
+    1024
+    >>> get_appropriate_divisor(123456789)
+    1048576
     '''
     size = abs(size)
     for unit in UNIT_SIZES:

voussoirkit/networktools.py

@@ -1,3 +1,10 @@
+'''
+networktools
+============
+
+This module provides functions for learning the current network status and
+internal / external IP addresses.
+'''
 import requests
 import socket
 

voussoirkit/sqlhelpers.py

@@ -1,3 +1,11 @@
+'''
+sqlhelpers
+==========
+
+This module provides functions for SQL string manipulation that I need often.
+Most importantly, creating the right number of ? for binding insert / update
+statements.
+'''
 import re
 import types
 
@@ -7,10 +15,9 @@ def delete_filler(pairs):
     Given a dictionary of {column: value}, return the "WHERE ..." portion of
     the query and the bindings in the correct order.
 
-    Example:
+    >>> pairs={'test': 'toast', 'ping': 'pong'}
-    pairs={'test': 'toast', 'ping': 'pong'}
+    >>> delete_filler(pairs)
-    ->
+    ('WHERE test = ? AND ping = ?', ['toast', 'pong'])
-    returns ('WHERE test = ? AND ping = ?', ['toast', 'pong'])
 
     In context:
     (qmarks, bindings) = delete_filler(pairs)
@@ -37,11 +44,10 @@ def insert_filler(column_names, values, require_all=True):
         an exception?
         Otherwise, that column will simply receive None.
 
-    Example:
+    >>> column_names=['id', 'name', 'score'],
-    column_names=['id', 'name', 'score'],
+    >>> values={'score': 20, 'id': '1111', 'name': 'James'}
-    values={'score': 20, 'id': '1111', 'name': 'James'}
+    >>> insert_filler(column_names, scores)
-    ->
+    ('?, ?, ?', ['1111', 'James', 20])
-    returns ('?, ?, ?', ['1111', 'James', 20])
 
     In context:
     (qmarks, bindings) = insert_filler(COLUMN_NAMES, data)
@@ -75,17 +81,16 @@ def update_filler(pairs, where_key):
     where [0] is the current value used for WHERE, and [1] is the new value
     used for SET.
 
-    Example:
+    >>> pairs={'id': '1111', 'name': 'James', 'score': 20},
-    pairs={'id': '1111', 'name': 'James', 'score': 20},
+    >>> where_key='id'
-    where_key='id'
+    >>> update_filler(pairs, where_key)
-    ->
+    ('SET name = ?, score = ? WHERE id == ?', ['James', 20, '1111'])
-    returns ('SET name = ?, score = ? WHERE id == ?', ['James', 20, '1111'])
 
     Example:
-    pairs={'filepath': ('/oldplace', '/newplace')},
+    >>> pairs={'filepath': ('/oldplace', '/newplace')},
-    where_key='filepath'
+    >>> where_key='filepath'
-    ->
+    >>> update_filler(pairs, where_key)
-    returns ('SET filepath = ? WHERE filepath == ?', ['/newplace', '/oldplace'])
+    ('SET filepath = ? WHERE filepath == ?', ['/newplace', '/oldplace'])
 
     In context:
     (qmarks, bindings) = update_filler(data, where_key)
@@ -138,11 +143,17 @@ def literal(item):
     '''
     Return a string depicting the SQL literal for this item.
 
-    Example:
+    >>> literal(0)
-    0 -> "0"
+    "0"
-    'hello' -> "'hello'"
+
-    b'hello' -> "X'68656c6c6f'"
+    >>> literal('hello')
-    [3, 'hi'] -> "(3, 'hi')"
+    "'hello'"
+
+    >>> literal(b'hello')
+    "X'68656c6c6f'"
+
+    >>> literal([3, 'hi'])
+    "(3, 'hi')"
     '''
     if item is None:
         return 'NULL'
@@ -240,6 +251,7 @@ def reverse_table_column_map(table_column_map):
     }
     If you have a row of data and you want to access one of the columns, you can
     use this map to figure out which tuple index corresponds to the column name.
+
     For example:
     row = ('abcd', 'John', 23)
     index = INDEX['people']['name']

voussoirkit/threadpool.py

@@ -1,6 +1,10 @@
 '''
-The documentation for the classes and methods are below. Here are some examples
+threadpool
-of threadpool in use:
+==========
+
+This module provides the ThreadPool class, which manages a pool of threads to
+complete many jobs. The documentation for the classes and methods are below.
+Here are some examples of threadpool in use:
 
 1. Powering a single api scraping generator with many threads: