Repository: azavea/raster-vision

Issue:
Add PyDocs to TrainingPackage class



Discussion:

Resolving patch:
diff --git a/src/rastervision/ml_backends/tf_object_detection_api.py b/src/rastervision/ml_backends/tf_object_detection_api.py
--- a/src/rastervision/ml_backends/tf_object_detection_api.py
+++ b/src/rastervision/ml_backends/tf_object_detection_api.py
@@ -252,7 +252,31 @@ def export_inference_graph(train_root_dir,
 
 
 class TrainingPackage(object):
+    """Encapsulates the files needed to train a model.
+
+    This encapsulates the files that are generated by the make_training_chips
+    command and that are used by the train command. It takes the URI of the
+    directory used to store these files (which is remote or local depending on
+    where the command is being executed), generates the URIs of all the
+    individual files, and downloads and uploads them. This assumes the
+    directory has the following structure:
+        label-map.pbtxt
+        train-debug-chips.zip
+        train.record
+        validation-debug-chips.zip
+        validation.record
+    """
+
     def __init__(self, base_uri):
+        """Constructor.
+
+        Creates a temporary directory.
+
+        Args:
+            base_uri: (string) URI of directory containing files used to
+                train model, possibly remote
+        """
+
         self.temp_dir_obj = tempfile.TemporaryDirectory()
         self.temp_dir = self.temp_dir_obj.name
 
@@ -261,24 +285,77 @@ def __init__(self, base_uri):
         make_dir(self.base_dir)
 
     def get_local_path(self, uri):
+        """Get local version of uri.
+
+        Args:
+            uri: (string) URI of file, possibly remote
+
+        Returns:
+            (string) path of local version of file
+        """
         return get_local_path(uri, self.temp_dir)
 
     def upload_if_needed(self, uri):
+        """Upload file if it's remote.
+
+        This knows how to generate the path to the local copy of the file.
+
+        Args:
+            uri: (string) URI of file, possibly remote
+        """
         upload_if_needed(self.get_local_path(uri), uri)
 
     def download_if_needed(self, uri):
+        """Download file if it's remote.
+
+        Args:
+            uri: (string) URI of file, possibly remote
+
+        Returns:
+            (string) path of local file that was downloaded
+        """
         return download_if_needed(uri, self.temp_dir)
 
     def get_record_uri(self, split):
+        """Get URI of TFRecord for dataset split.
+
+        Args:
+            split: (string) 'train' or 'validation'
+
+        Returns:
+            (string) URI of TFRecord file, possibly remote
+        """
         return join(self.base_uri, '{}.record'.format(split))
 
     def get_debug_chips_uri(self, split):
+        """Get URI of debug chips zip file for dataset split.
+
+        Args:
+            split: (string) 'train' or 'validation'
+
+        Returns:
+            (string) URI of zip file containing debug chips, possibly remote
+        """
         return join(self.base_uri, '{}-debug-chips.zip'.format(split))
 
     def get_class_map_uri(self):
+        """Get URI of class map file.
+
+        The TF Object Detection API uses its own class map file that maps
+        class_ids to class_names, which they call a "label map".
+
+        Returns:
+            (string) URI of class map file, possibly remote
+        """
         return join(self.base_uri, 'label-map.pbtxt')
 
     def upload(self, debug=False):
+        """Upload training and validation data, and class map files.
+
+        Args:
+            debug: (bool) if True, also upload the corresponding debug chip
+                zip files
+        """
         self.upload_if_needed(self.get_record_uri(TRAIN))
         self.upload_if_needed(self.get_record_uri(VALIDATION))
         self.upload_if_needed(self.get_class_map_uri())
@@ -287,14 +364,33 @@ def upload(self, debug=False):
             self.upload_if_needed(self.get_debug_chips_uri(VALIDATION))
 
     def download_data(self):
+        """Download training and validation data, and class map files."""
         # No need to download debug chips.
         self.download_if_needed(self.get_record_uri(TRAIN))
         self.download_if_needed(self.get_record_uri(VALIDATION))
         self.download_if_needed(self.get_class_map_uri())
 
     def download_pretrained_model(self, pretrained_model_zip_uri):
-        # Expected to be .tar.gz file downloaded from
-        # https://github.com/tensorflow/models/blob/master/research/object_detection/g3doc/detection_model_zoo.md # noqa
+        """Download pretrained model and unzip it.
+
+        This is used before training a model.
+
+        Args:
+            pretrained_model_zip_uri: (string) URI of .tar.gz file containing
+                pretrained model. This file is of the form that comes from the
+                Model Zoo at https://github.com/tensorflow/models/blob/master/research/object_detection/g3doc/detection_model_zoo.md # noqa
+                It contains a directory at the top level with the same name as
+                root of the zip file (if zip file is x.tar.gz, the directory
+                is x), and a set of files of the form model.ckpt.*. This file
+                can be located anywhere, and is not expected to be in the
+                directory encapsulated by this class that is generated by the
+                make_training_chips command. That is why it is passed in
+                separately.
+
+        Returns:
+            (string) path to pretrained model file (which is model.ckpt in
+                the zip file)
+        """
         pretrained_model_zip_path = self.download_if_needed(
             pretrained_model_zip_uri)
         pretrained_model_dir = join(self.temp_dir, 'pretrained_model')
@@ -310,6 +406,22 @@ def download_pretrained_model(self, pretrained_model_zip_uri):
         return pretrained_model_path
 
     def download_config(self, pretrained_model_zip_uri, backend_config_uri):
+        """Download a model and backend config and update its fields.
+
+        This is used before training a model. This downloads and unzips a bunch
+        of files that are needed to train a model, and then downloads and
+        updates the backend config file with local paths to these files. These
+        files include the pretrained model, the class map, and the training and
+        validation datasets.
+
+        Args:
+            pretrained_model_zip_uri: (string) URI of .tar.gz file containing
+                pretrained model. (See download_pretrained_model method for more
+                details.)
+            backend_config_uri: (string) URI of backend config file which is
+                a config file for the TF Object Detection API. Examples can be
+                found here https://github.com/tensorflow/models/tree/master/research/object_detection/samples/configs  # noqa
+        """
         # Download and parse config.
         config_str = file_to_str(backend_config_uri)
         config = text_format.Parse(config_str, TrainEvalPipelineConfig())


Test patch: