From 735ff80458d9d9be25c0dc1ef9afb55c2e77ddc8 Mon Sep 17 00:00:00 2001 From: Peter Silva Date: Tue, 19 Mar 2024 02:16:20 -0400 Subject: [PATCH] updating documentation of gather routine's new variable return formats --- docs/source/Explanation/SarraPluginDev.rst | 5 +++++ docs/source/How2Guides/FlowCallbacks.rst | 6 +++++- docs/source/fr/CommentFaire/FlowCallbacks.rst | 2 ++ docs/source/fr/Explication/SarraPluginDev.rst | 4 ++++ 4 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/source/Explanation/SarraPluginDev.rst b/docs/source/Explanation/SarraPluginDev.rst index cc7364354..8927b46c5 100644 --- 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 index 8469f2412..876a92f9e 100644 --- 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 index ecf8fb931..70bff1dfe 100644 --- 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 index d0e1056e5..0eb1ea4c1 100644 --- 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 |