From 7b794e35cf97a7c1bc5575ee2d499e0f4c0d67cb Mon Sep 17 00:00:00 2001
From: Graham Kanarek <gkanarek@stsci.edu>
Date: Wed, 3 Jan 2018 15:21:40 -0500
Subject: [PATCH 1/2] Adding type annotations to the example

I'm not sure whether some explanatory text should be included here about the type annotations, or if it should just go in the style guide...
---
 style_guide/example.py | 39 +++++++++++++++++++++------------------
 1 file changed, 21 insertions(+), 18 deletions(-)

diff --git a/style_guide/example.py b/style_guide/example.py
index 4003d0d2d..44158b259 100644
--- a/style_guide/example.py
+++ b/style_guide/example.py
@@ -59,6 +59,7 @@
 import glob
 import os
 import sys
+from typing import List, Union, Tuple, Optional, Any, Dict
 
 from astropy.io import fits
 import matplotlib.pyplot as plt
@@ -69,10 +70,10 @@
 
 # Global variables should be avioded, but if used should be named with
 # all-caps
-A_GLOBAL_VARIABLE = 'foo'
+A_GLOBAL_VARIABLE = 'foo' # type: str
 
 
-def my_main_function(path, filter):
+def my_main_function(path: str, filter: str) -> None:
     """The main function of the ``example`` module.
 
     This function performs the main tasks of the module.  See module
@@ -87,20 +88,20 @@ def my_main_function(path, filter):
     """
 
     print('Using {} as an input file'.format(path))
-    an_int = 1
-    a_float = 3.14
-    a_bool = True
-    a_list = ['Dog', 'Cat', 'Turtle', False, 7]
-    a_tuple = ('Dog', 'Cat', 'Turtle', False, 7)
-    a_dict = {'key1': 'value1', 'key2': 'value2'}
-    an_obj = object()
+    an_int = 1 # type: int
+    a_float = 3.14 # type: float
+    a_bool = True # type: bool
+    a_list = ['Dog', 'Cat', 'Turtle', False, 7] # type: List[Union[str, bool, int]]
+    a_tuple = ('Dog', 'Cat', 'Turtle', False, 7) # type: Tuple[str, str, str, bool, int]
+    a_dict = {'key1': 'value1', 'key2': 'value2'} # type: Dict[str, str]
+    an_obj = object() # type: object
 
-    result = some_other_function(an_int, a_float, a_bool, a_list, a_tuple, a_dict, an_obj)
+    result = some_other_function(an_int, a_float, a_bool, a_list, a_tuple, a_dict, an_obj) # type: Optional[int]
 
     print(result)
 
 
-def parse_args():
+def parse_args() -> argparse.Namespace:
     """Parse command line arguments. Returns ``args`` object.
 
     Returns
@@ -110,11 +111,11 @@ def parse_args():
     """
 
     # Create help strings
-    path_help = 'The path to the input file.'
-    filter_help = 'The filter to process (e.g. "F606W").'
+    path_help = 'The path to the input file.' # type: str
+    filter_help = 'The filter to process (e.g. "F606W").' # type: str
 
     # Add arguments
-    parser = argparse.ArgumentParser()
+    parser = argparse.ArgumentParser() # type: argparse.ArgumentParser
     parser.add_argument('path',
                         type=str,
                         default=os.getcwd(),
@@ -127,12 +128,13 @@ def parse_args():
                         help=filter_help)
 
     # Parse args
-    args = parser.parse_args()
+    args = parser.parse_args() # type: argparse.Namespace
 
     return args
 
 
-def some_other_function(an_int, a_float, a_bool, a_list, a_tuple, a_dict, an_obj):
+def some_other_function(an_int: int, a_float: float, a_bool: bool, a_list: List[Any], 
+                        a_tuple: Tuple[Any], a_dict: Dict[Any, Any], an_obj: object) -> int:
     """This function just does a bunch of nonsense.
 
     But it serves as a decent example of some things.
@@ -166,12 +168,13 @@ def some_other_function(an_int, a_float, a_bool, a_list, a_tuple, a_dict, an_obj
 
     # Operators should be separated by spaces
     print(a_float + a_float)
-
+    
+    return an_int
 
 
 
 if __name__ == '__main__':
 
-    args = parse_args()
+    args = parse_args() # type: argparse.Namespace
 
     my_main_function(args.path, args.filter)

From 50dde4100bb05c86a31a1f75c46f7443d9bd6073 Mon Sep 17 00:00:00 2001
From: Graham Kanarek <gkanarek@stsci.edu>
Date: Tue, 16 Jan 2018 15:29:34 -0500
Subject: [PATCH 2/2] Include type annotations note in style_guide.md

I've added a bullet point to the section for `jwql`-specific standards to recommend using type annotations & `mypy`.
---
 style_guide/style_guide.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/style_guide/style_guide.md b/style_guide/style_guide.md
index d8987e4d2..4280d4063 100644
--- a/style_guide/style_guide.md
+++ b/style_guide/style_guide.md
@@ -64,6 +64,7 @@ If `jwql` code needs to be aware of this information, it should be stored in a c
  Additionally, the code shall adhere to the following special guidelines:
 
  - Function and class definitions should be placed in alphabetical order in the module
+ - It is encouraged to annotate variables and functions using the [`typing`](https://docs.python.org/3/library/typing.html) module (see [PEP 483](https://www.python.org/dev/peps/pep-0483/), [PEP 484](https://www.python.org/dev/peps/pep-0484/), and [PEP 526](https://www.python.org/dev/peps/pep-0526/)). In addition, it is recommended that code be type-checked using [`mypy`](http://mypy-lang.org/) before a pull request is submitted.
 
 
 `jwql`-Specific Documentation Standards