diff --git a/voussoirkit/bytestring.py b/voussoirkit/bytestring.py index fc028d6..634be02 100644 --- a/voussoirkit/bytestring.py +++ b/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 - 1024 => 1024 to display 1 KiB - 123456789 => 1048576 to display 117.738 MiB + + >>> get_appropriate_divisor(1000) + 1 + >>> get_appropriate_divisor(1024) + 1024 + >>> get_appropriate_divisor(123456789) + 1048576 ''' size = abs(size) for unit in UNIT_SIZES: diff --git a/voussoirkit/networktools.py b/voussoirkit/networktools.py index 68092c0..2b67caf 100644 --- a/voussoirkit/networktools.py +++ b/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 diff --git a/voussoirkit/sqlhelpers.py b/voussoirkit/sqlhelpers.py index 3f903ee..92dbf68 100644 --- a/voussoirkit/sqlhelpers.py +++ b/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'} - -> - returns ('WHERE test = ? AND ping = ?', ['toast', 'pong']) + >>> pairs={'test': 'toast', 'ping': 'pong'} + >>> delete_filler(pairs) + ('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'], - values={'score': 20, 'id': '1111', 'name': 'James'} - -> - returns ('?, ?, ?', ['1111', 'James', 20]) + >>> column_names=['id', 'name', 'score'], + >>> values={'score': 20, 'id': '1111', 'name': 'James'} + >>> insert_filler(column_names, scores) + ('?, ?, ?', ['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}, - where_key='id' - -> - returns ('SET name = ?, score = ? WHERE id == ?', ['James', 20, '1111']) + >>> pairs={'id': '1111', 'name': 'James', 'score': 20}, + >>> where_key='id' + >>> update_filler(pairs, where_key) + ('SET name = ?, score = ? WHERE id == ?', ['James', 20, '1111']) Example: - pairs={'filepath': ('/oldplace', '/newplace')}, - where_key='filepath' - -> - returns ('SET filepath = ? WHERE filepath == ?', ['/newplace', '/oldplace']) + >>> pairs={'filepath': ('/oldplace', '/newplace')}, + >>> where_key='filepath' + >>> update_filler(pairs, where_key) + ('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: - 0 -> "0" - 'hello' -> "'hello'" - b'hello' -> "X'68656c6c6f'" - [3, 'hi'] -> "(3, 'hi')" + >>> literal(0) + "0" + + >>> literal('hello') + "'hello'" + + >>> literal(b'hello') + "X'68656c6c6f'" + + >>> literal([3, 'hi']) + "(3, 'hi')" ''' if item is None: return 'NULL' @@ -240,9 +251,10 @@ 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'] - print(row[index]) + row = ('abcd', 'John', 23) + index = INDEX['people']['name'] + print(row[index]) ''' return {table: _reverse_index(columns) for (table, columns) in table_column_map.items()} diff --git a/voussoirkit/threadpool.py b/voussoirkit/threadpool.py index 2769ca5..c4ef8bd 100644 --- a/voussoirkit/threadpool.py +++ b/voussoirkit/threadpool.py @@ -1,6 +1,10 @@ ''' -The documentation for the classes and methods are below. Here are some examples -of threadpool in use: +threadpool +========== + +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: