From 25301e2152ba423777c0ba1dd24fe0041caba6d3 Mon Sep 17 00:00:00 2001 From: David Read Date: Tue, 1 Dec 2015 17:51:35 +0000 Subject: [PATCH] Update README from interfaces.py. PEP8. Mention HarvestObject - Package relation in interface. --- README.rst | 35 ++++++++++++++++++++--------------- ckanext/harvest/interfaces.py | 11 +++++++---- 2 files changed, 27 insertions(+), 19 deletions(-) diff --git a/README.rst b/README.rst index d851b64..34c7e47 100644 --- a/README.rst +++ b/README.rst @@ -339,11 +339,10 @@ following methods:: ''' implements(IHarvester) - def info(self): ''' - Harvesting implementations must provide this method, which will return a - dictionary containing different descriptors of the harvester. The + Harvesting implementations must provide this method, which will return + 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 - appear on the form as a guidance to the user. + * description: a small description of what the harvester does. This + 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 - form. It should return a single string, which will be stored in the database. - Exceptions raised will be shown in the form's error messages. + Harvesters can provide this method to validate the configuration + entered in the form. It should return a single string, which will be + 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 - was needed doing after all or False if there were errors. + - 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 - needed doing after all and False if something went wrong. + :returns: True if the action was done, "unchanged" if the object didn't + need harvesting after all or False if there were errors. ''' diff --git a/ckanext/harvest/interfaces.py b/ckanext/harvest/interfaces.py index f0f5773..1e19635 100644 --- a/ckanext/harvest/interfaces.py +++ b/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 - needed doing after all and False if something went wrong. + :returns: True if the action was done, "unchanged" if the object didn't + need harvesting after all or False if there were errors. '''