fix:better_stop (#643)

* fix:better_stop

* requirements.txt

* python versions

* requirements.txt

* 📝 Add docstrings to `stop` (#644)

Docstrings generation was requested by @JarbasAl.

* #643 (comment)

The following files were modified:

* `ovos_core/intent_services/__init__.py`
* `ovos_core/intent_services/converse_service.py`
* `ovos_core/intent_services/stop_service.py`

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* fix: stop DRY

no need for 2 handlers, decrease complexity

the only difference is an emitted event that is not listened too anywhere

* requirements.txt

* tests

* tests

* tests

* tests

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

.github/workflows/build_tests.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       max-parallel: 2
       matrix:
-        python-version: [3.8, 3.9, "3.10", "3.11"]
+        python-version: ["3.10", "3.11"]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2

.github/workflows/coverage.yml

@@ -15,7 +15,7 @@ jobs:
     - name: Setup Python
       uses: actions/setup-python@master
       with:
-        python-version: 3.9
+        python-version: "3.10"
     - name: Install System Dependencies
       run: |
         sudo apt-get update

.github/workflows/license_tests.yml

@@ -37,7 +37,7 @@ jobs:
           requirements: 'requirements-all.txt'
           fail: 'Copyleft,Other,Error'
           fails-only: true
-          exclude: '^(precise-runner|fann2|ovos-adapt-parser|ovos-padatious|tqdm|bs4|sonopy|caldav|recurring-ical-events|x-wr-timezone|zeroconf|mutagen).*'
+          exclude: '^(precise-runner|fann2|ovos-adapt-parser|ovos-padatious|tqdm|bs4|sonopy|caldav|recurring-ical-events|x-wr-timezone|zeroconf|mutagen|attrs).*'
           exclude-license: '^(Mozilla).*$'
       - name: Print report
         if: ${{ always() }}

.github/workflows/pipaudit.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       max-parallel: 2
       matrix:
-        python-version: [ 3.7, 3.8, 3.9, "3.10", "3.11" ]
+        python-version: [3.9, "3.10", "3.11"]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2

.github/workflows/sync_tx.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v1
         with:
-          python-version: 3.9
+          python-version: "3.10"
 
       - name: Run script if merged by gitlocalize-app[bot]
         if: github.event_name == 'push' && github.event.head_commit.author.username == 'gitlocalize-app[bot]'

ovos_core/intent_services/__init__.py

@@ -268,15 +268,34 @@ def _handle_deactivate(self, message):
         self._deactivations[sess.session_id].append(skill_id)
 
     def _emit_match_message(self, match: Union[IntentHandlerMatch, PipelineMatch], message: Message):
-        """Update the message data with the matched utterance information and
-        activate the corresponding skill if available.
-
+        """
+        Emit a reply message for a matched intent, updating session and skill activation.
+        
+        This method processes matched intents from either a pipeline matcher or an intent handler,
+        creating a reply message with matched intent details and managing skill activation.
+        
         Args:
-            match (IntentHandlerMatch): The matched utterance object.
-            message (Message): The messagebus data.
+            match (Union[IntentHandlerMatch, PipelineMatch]): The matched intent object containing
+                utterance and matching information.
+            message (Message): The original messagebus message that triggered the intent match.
+        
+        Details:
+            - Handles two types of matches: PipelineMatch and IntentHandlerMatch
+            - Creates a reply message with matched intent data
+            - Activates the corresponding skill if not previously deactivated
+            - Updates session information
+            - Emits the reply message on the messagebus
+        
+        Side Effects:
+            - Modifies session state
+            - Emits a messagebus event
+            - Can trigger skill activation events
+        
+        Returns:
+            None
         """
         reply = None
-        sess = SessionManager.get(message)
+        sess = match.updated_session or SessionManager.get(message)
 
         # utterance fully handled by pipeline matcher
         if isinstance(match, PipelineMatch):
@@ -303,13 +322,34 @@ def _emit_match_message(self, match: Union[IntentHandlerMatch, PipelineMatch], m
                 was_deactivated = match.skill_id in self._deactivations[sess.session_id]
                 if not was_deactivated:
                     sess.activate_skill(match.skill_id)
-                    reply.context["session"] = sess.serialize()
                     # emit event for skills callback -> self.handle_activate
                     self.bus.emit(reply.forward(f"{match.skill_id}.activate"))
 
+            # update Session if modified by pipeline
+            reply.context["session"] = sess.serialize()
+
+            # finally emit reply message
             self.bus.emit(reply)
 
     def send_cancel_event(self, message):
+        """
+        Emit events and play a sound when an utterance is canceled.
+        
+        Logs the cancellation with the specific cancel word, plays a predefined cancel sound,
+        and emits multiple events to signal the utterance cancellation.
+        
+        Parameters:
+            message (Message): The original message that triggered the cancellation.
+        
+        Events Emitted:
+            - 'mycroft.audio.play_sound': Plays a cancel sound from configuration
+            - 'ovos.utterance.cancelled': Signals that the utterance was canceled
+            - 'ovos.utterance.handled': Indicates the utterance processing is complete
+        
+        Notes:
+            - Uses the default cancel sound path 'snd/cancel.mp3' if not specified in configuration
+            - Ensures events are sent as replies to the original message
+        """
         LOG.info("utterance canceled, cancel_word:" + message.context.get("cancel_word"))
         # play dedicated cancel sound
         sound = Configuration().get('sounds', {}).get('cancel', "snd/cancel.mp3")

ovos_core/intent_services/converse_service.py

@@ -313,15 +313,29 @@ def converse(self, utterances: List[str], skill_id: str, lang: str, message: Mes
         return False
 
     def converse_with_skills(self, utterances: List[str], lang: str, message: Message) -> Optional[PipelineMatch]:
-        """Give active skills a chance at the utterance
-
+        """
+        Attempt to converse with active skills for a given set of utterances.
+        
+        Iterates through active skills to find one that can handle the utterance. Filters skills based on timeout and blacklist status.
+        
         Args:
-            utterances (list):  list of utterances
-            lang (string):      4 letter ISO language code
-            message (Message):  message to use to generate reply
-
+            utterances (List[str]): List of utterance strings to process
+            lang (str): 4-letter ISO language code for the utterances
+            message (Message): Message context for generating a reply
+        
         Returns:
-            IntentMatch if handled otherwise None.
+            PipelineMatch: Match details if a skill successfully handles the utterance, otherwise None
+            - handled (bool): Whether the utterance was fully handled
+            - match_data (dict): Additional match metadata
+            - skill_id (str): ID of the skill that handled the utterance
+            - updated_session (Session): Current session state after skill interaction
+            - utterance (str): The original utterance processed
+        
+        Notes:
+            - Standardizes language tag
+            - Filters out blacklisted skills
+            - Checks for skill conversation timeouts
+            - Attempts conversation with each eligible skill
         """
         lang = standardize_lang_tag(lang)
         session = SessionManager.get(message)
@@ -342,6 +356,7 @@ def converse_with_skills(self, utterances: List[str], lang: str, message: Messag
                                      # handled == True -> emit "ovos.utterance.handled"
                                      match_data={},
                                      skill_id=skill_id,
+                                     updated_session=session,
                                      utterance=utterances[0])
         return None