Update README from interfaces.py. PEP8. Mention HarvestObject - Package relation in interface.

README.rst

@@ -339,11 +339,10 @@ following methods::
     '''
     implements(IHarvester)
 
-
     def info(self):
         '''
-        Harvesting implementations must provide this method, which will return a
+        Harvesting implementations must provide this method, which will return
-        dictionary containing different descriptors of the harvester. The
+        a dictionary containing different descriptors of the harvester. The
         returned dictionary should contain:
 
         * name: machine-readable name. This will be the value stored in the
@@ -351,8 +350,8 @@ following methods::
           harvester.
         * title: human-readable name. This will appear in the form's select box
           in the WUI.
-        * description: a small description of what the harvester does. This will
+        * description: a small description of what the harvester does. This
-          appear on the form as a guidance to the user.
+          will appear on the form as a guidance to the user.
 
         A complete example may be::
 
@@ -371,9 +370,10 @@ following methods::
 
         [optional]
 
-        Harvesters can provide this method to validate the configuration entered in the
+        Harvesters can provide this method to validate the configuration
-        form. It should return a single string, which will be stored in the database.
+        entered in the form. It should return a single string, which will be
-        Exceptions raised will be shown in the form's error messages.
+        stored in the database.  Exceptions raised will be shown in the form's
+        error messages.
 
         :param harvest_object_id: Config string coming from the form
         :returns: A string with the validated configuration options
@@ -404,7 +404,7 @@ following methods::
 
     def gather_stage(self, harvest_job):
         '''
-        The gather stage will recieve a HarvestJob object and will be
+        The gather stage will receive a HarvestJob object and will be
         responsible for:
             - gathering all the necessary objects to fetch on a later.
               stage (e.g. for a CSW server, perform a GetRecords request)
@@ -430,10 +430,14 @@ following methods::
             - saving the content in the provided HarvestObject.
             - creating and storing any suitable HarvestObjectErrors that may
               occur.
-            - returning True if everything went as expected, False otherwise.
+            - returning True if everything is ok (ie the object should now be
+              imported), "unchanged" if the object didn't need harvesting after
+              all (ie no error, but don't continue to import stage) or False if
+              there were errors.
 
         :param harvest_object: HarvestObject object
-        :returns: True if everything went right, False if errors were found
+        :returns: True if successful, 'unchanged' if nothing to import after
+                  all, False if not successful
         '''
 
     def import_stage(self, harvest_object):
@@ -452,12 +456,13 @@ following methods::
               objects of this harvest source if the action was successful.
             - creating and storing any suitable HarvestObjectErrors that may
               occur.
-            - returning True if the action was done, "unchanged" if nothing
+            - creating the HarvestObject - Package relation (if necessary)
-              was needed doing after all or False if there were errors.
+            - returning True if the action was done, "unchanged" if the object
+              didn't need harvesting after all or False if there were errors.
 
         :param harvest_object: HarvestObject object
-        :returns: True if the action was done, "unchanged" if nothing was
+        :returns: True if the action was done, "unchanged" if the object didn't
-                  needed doing after all and False if something went wrong.
+                  need harvesting after all or False if there were errors.
         '''
 
 

ckanext/harvest/interfaces.py

@@ -1,5 +1,6 @@
 from ckan.plugins.interfaces import Interface
 
+
 class IHarvester(Interface):
     '''
     Common harvesting interface
@@ -71,7 +72,7 @@ class IHarvester(Interface):
 
     def gather_stage(self, harvest_job):
         '''
-        The gather stage will recieve a HarvestJob object and will be
+        The gather stage will receive a HarvestJob object and will be
         responsible for:
             - gathering all the necessary objects to fetch on a later.
               stage (e.g. for a CSW server, perform a GetRecords request)
@@ -103,7 +104,8 @@ class IHarvester(Interface):
               there were errors.
 
         :param harvest_object: HarvestObject object
-        :returns: True if everything went right, False if errors were found
+        :returns: True if successful, 'unchanged' if nothing to import after
+                  all, False if not successful
         '''
 
     def import_stage(self, harvest_object):
@@ -122,10 +124,11 @@ class IHarvester(Interface):
               objects of this harvest source if the action was successful.
             - creating and storing any suitable HarvestObjectErrors that may
               occur.
+            - creating the HarvestObject - Package relation (if necessary)
             - returning True if the action was done, "unchanged" if the object
               didn't need harvesting after all or False if there were errors.
 
         :param harvest_object: HarvestObject object
-        :returns: True if the action was done, "unchanged" if nothing was
+        :returns: True if the action was done, "unchanged" if the object didn't
-                  needed doing after all and False if something went wrong.
+                  need harvesting after all or False if there were errors.
         '''