updating documentation of gather routine's new variable return formats

MetPX · Mar 19, 2024 · 735ff80 · 735ff80
1 parent 0aa63d1
commit 735ff80
Show file tree

Hide file tree

Showing 4 changed files with 16 additions and 1 deletion.
diff --git a/docs/source/Explanation/SarraPluginDev.rst b/docs/source/Explanation/SarraPluginDev.rst
@@ -585,12 +585,17 @@ for detailed information about call signatures and return values, etc...
 |                     | permanent name.                                    |
 |                     |                                                    |
 |                     | return the new name for the downloaded/sent file.  |
+|                     |                                                    |
 +---------------------+----------------------------------------------------+
 | download(self,msg)  | replace built-in downloader return true on success |
 |                     | takes message as argument.                         |
 +---------------------+----------------------------------------------------+
 | gather(self)        | gather messages from a source, returns a list of   |
 |                     | messages.                                          |
+|                     | can also return a tuple where the first element    |
+|                     | is a boolean flag keep_going indicating whether    |
+|                     | to stop gather processing.                         |
+|                     |                                                    |
 +---------------------+----------------------------------------------------+
 |                     | Called every housekeeping interval (minutes)       |
 |                     | used to clean cache, check for occasional issues.  |

diff --git a/docs/source/How2Guides/FlowCallbacks.rst b/docs/source/How2Guides/FlowCallbacks.rst
@@ -215,7 +215,11 @@ Other entry_points, extracted from sarracenia/flowcb/__init__.py ::
 
 
     def gather(self):
-        Task: gather notification messages from a source... return a list of notification messages.
+        Task: gather notification messages from a source... return either:
+              * a list of notification messages, or
+              * a tuple, (bool:keep_going, list of messages)
+              * to curtail further gathers in this cycle.
+                
         return []
 
     def metrics_report(self) -> dict:

diff --git a/docs/source/fr/CommentFaire/FlowCallbacks.rst b/docs/source/fr/CommentFaire/FlowCallbacks.rst
@@ -182,6 +182,8 @@ Autres entry_points, extraits de sarracenia/flowcb/__init__.py ::
 
     def gather(self):
         Task: gather notification messages from a source... return a list of notification messages.
+              can also return tuple (keep_going, new_messages) where keep_going is a flag 
+              that when False stops processing of further gather routines.
         return []
 
     """

diff --git a/docs/source/fr/Explication/SarraPluginDev.rst b/docs/source/fr/Explication/SarraPluginDev.rst
@@ -554,6 +554,10 @@ pour des informations détaillées sur les signatures d’appel et les valeurs d
 +---------------------+----------------------------------------------------+
 | gather(self)        | Rassembler les messages a la source, retourne une  |
 |                     | une liste de messages.                             |
+|                     | on peut également retourner un tuple dont le       |
+|                     | première élément est une valeur booléen keep_going |
+|                     | qui peut arreter l´execution des gather.           |
+|                     |                                                    |
 +---------------------+----------------------------------------------------+
 |                     | Appelé à chaque intervalle housekeeping (minutes). |
 |                     | utilisé pour nettoyer le cache, vérifier les       |