Add some docstrings and improve some others

Author: Bjwebb

flattentool/__init__.py

@@ -14,6 +14,7 @@ def create_template(schema, output_name='releases', output_format='all', main_sh
     Creates template file(s) from given inputs
     This function is built to deal with commandline input and arguments
     but to also be called from elswhere in future
+
     """
 
     parser = SchemaParser(schema_filename=schema, main_sheet_name=main_sheet_name, rollup=rollup, root_id=root_id, use_titles=use_titles)
@@ -38,6 +39,11 @@ def spreadsheet_output(spreadsheet_output_class, name):
 
 
 def flatten(input_name, schema=None, output_name='releases', output_format='all', main_sheet_name='main', root_list_path='releases', rollup=False, root_id='ocid', use_titles=False, **_):
+    """
+    Flatten a nested structure (JSON) to a flat structure (spreadsheet - csv or xlsx).
+
+    """
+
     if schema:
         schema_parser = SchemaParser(
             schema_filename=schema,
@@ -99,6 +105,10 @@ def decimal_default(o):
 def unflatten(input_name, base_json=None, input_format=None, output_name='releases.json',
               main_sheet_name='releases', encoding='utf8', timezone_name='UTC',
               root_id='ocid', schema='', convert_titles=False, **_):
+    """
+    Unflatten a flat structure (spreadsheet - csv or xlsx) into a nested structure (JSON).
+
+    """
     if input_format is None:
         raise Exception('You must specify an input format (may autodetect in future')
     elif input_format not in INPUT_FORMATS:

flattentool/cli.py

@@ -3,8 +3,28 @@
 from flattentool import create_template, unflatten, flatten
 from six import text_type
 
+"""
+This file does most of the work of the flatten-tool commandline command.
+
+It takes any commandline arguments, and passes them to a function in
+``__init__.py``.
+
+It is callable via the ``flatten-tool`` executable in the directory below, or
+using ``python -m flattentool.cli``.
+
+"""
+
 
 def create_parser():
+    """
+    Create an argparse ArgumentParser for our commandline arguments
+
+    Defaults are not set here, but rather given in the appropriate function.
+
+    (This is split out as it's own function primarily so it can be tested.)
+
+    """
+
     parser = argparse.ArgumentParser()
     subparsers = parser.add_subparsers(dest='subparser_name')
 
@@ -109,15 +129,20 @@ def create_parser():
 
 
 def kwargs_from_parsed_args(args):
+    """
+    Transforms argparse's parsed args object into a dictionary to be passed  as
+    kwargs.
+
+    """
     return {k: v for k, v in vars(args).items() if v is not None}
 
 
 def main():
     """
-    Takes any command line arguments and then passes them onto
-    create_template
-    Defaults are not set here, but rather given in the create_template
-    function incase that function is called from elsewhere in future.
+    Use ``create_parser`` to get the commandline arguments, and pass them to
+    the appropriate function in __init__.py (create_template, flatten or
+    unflatten).
+
     """
     parser = create_parser()
     # Store the supplied arguments in args

flattentool/input.py

@@ -1,3 +1,8 @@
+"""
+This file has classes describing input from spreadsheets.
+
+"""
+
 from __future__ import print_function
 from __future__ import unicode_literals
 import sys
@@ -25,7 +30,17 @@
 
 
 class SpreadsheetInput(object):
+    """
+    Base class describing a spreadsheet input. Has stubs which are
+    implemented via inheritance for particular types of spreadsheet (e.g. xlsx
+    or csv).
+
+    """
     def convert_dict_titles(self, dicts, titles):
+        """
+        Replace titles with field names in the given list of dictionaries (``dicts``) using the mapping in ``titles``.
+
+        """
         titles = titles or {}
         titles_map = {title.replace(' ', '').lower(): title for title in titles}
         for d in dicts:

flattentool/json_input.py

@@ -1,6 +1,6 @@
 """
 
-This file contains code that takes an OCDS JSON release ifle as input (not a
+This file contains code that takes an OCDS JSON release file as input (not a
 JSON schema, for that see schema.py).
 
 """

flattentool/output.py

@@ -1,5 +1,8 @@
-"""Code to output a parsed flattened JSON schema in various spreadsheet
-formats."""
+"""
+Code to output a parsed flattened JSON schema in various spreadsheet
+formats.
+
+"""
 
 import openpyxl
 import csv

flattentool/sheet.py

@@ -1,4 +1,9 @@
 class Sheet(object):
+    """
+    An abstract representation of a single sheet of a spreadsheet.
+
+    """
+
     def __init__(self, columns=None, root_id='', name=None):
         self.id_columns = []
         self.columns = columns if columns else []