core: findByFeatures type hints

sat/core/sat_main.py

@@ -23,6 +23,7 @@ import uuid
 import hashlib
 import copy
 from pathlib import Path
+from typing import Optional, List, Tuple, Dict
 import sat
 from sat.core.i18n import _, D_, languageSwitch
 from sat.core import patches
@@ -1091,26 +1092,40 @@ class SAT(service.Service):
             local_device))
 
     async def findByFeatures(
-        self, client, namespaces, identities=None, bare_jids=False, service=True,
-        roster=True, own_jid=True, local_device=False):
+        self,
+        client: xmpp.SatXMPPEntity,
+        namespaces: List[str],
+        identities: Optional[List[Tuple[str, str]]]=None,
+        bare_jids: bool=False,
+        service: bool=True,
+        roster: bool=True,
+        own_jid: bool=True,
+        local_device: bool=False
+    ) -> Tuple[
+        Dict[jid.JID, Tuple[str, str, str]],
+        Dict[jid.JID, Tuple[str, str, str]],
+        Dict[jid.JID, Tuple[str, str, str]]
+    ]:
         """Retrieve all services or contacts managing a set a features
 
-        @param namespaces(list[unicode]): features which must be handled
-        @param identities(list[tuple[unicode,unicode]], None): if not None or empty,
-            only keep those identities tuple must by (category, type)
-        @param bare_jids(bool): retrieve only bare_jids if True
+        @param namespaces: features which must be handled
+        @param identities: if not None or empty,
+            only keep those identities
+            tuple must be (category, type)
+        @param bare_jids: retrieve only bare_jids if True
             if False, retrieve full jid of connected devices
-        @param service(bool): if True return service from our roster
-        @param roster(bool): if True, return entities in roster
+        @param service: if True return service from our server
+        @param roster: if True, return entities in roster
             full jid of all matching resources available will be returned
-        @param own_jid(bool): if True, return profile's jid resources
-        @param local_device(bool): if True, return profile's jid local resource
+        @param own_jid: if True, return profile's jid resources
+        @param local_device: if True, return profile's jid local resource
             (i.e. client.jid)
-        @return (tuple(dict[jid.JID(), tuple[unicode, unicode, unicode]]*3)): found
-            entities in a tuple with:
+        @return: found entities in a tuple with:
             - service entities
             - own entities
             - roster entities
+            Each element is a dict mapping from jid to a tuple with category, type and
+            name of the entity
         """
         assert isinstance(namespaces, list)
         if not identities: