slidge 0.1.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

slidge/contact/contact.py

@@ -2,7 +2,8 @@ import datetime
 import logging
 import warnings
 from datetime import date
-from typing import TYPE_CHECKING, Generic, Iterable, Optional, Union
+from typing import TYPE_CHECKING, Generic, Iterable, Optional, Self, Union
+from xml.etree import ElementTree as ET
 
 from slixmpp import JID, Message, Presence
 from slixmpp.exceptions import IqError
@@ -10,12 +11,13 @@ from slixmpp.plugins.xep_0292.stanza import VCard4
 from slixmpp.types import MessageTypes
 
 from ..core import config
-from ..core.mixins import FullCarbonMixin
-from ..core.mixins.avatar import AvatarMixin
+from ..core.mixins import AvatarMixin, FullCarbonMixin, StoredAttributeMixin
+from ..core.mixins.db import UpdateInfoMixin
 from ..core.mixins.disco import ContactAccountDiscoMixin
 from ..core.mixins.recipient import ReactionRecipientMixin, ThreadRecipientMixin
+from ..db.models import Contact
 from ..util import SubclassableOnce
-from ..util.types import LegacyUserIdType, MessageOrPresenceTypeVar
+from ..util.types import ClientType, LegacyUserIdType, MessageOrPresenceTypeVar
 
 if TYPE_CHECKING:
     from ..core.session import BaseSession
@@ -24,11 +26,13 @@ if TYPE_CHECKING:
 
 class LegacyContact(
     Generic[LegacyUserIdType],
+    StoredAttributeMixin,
     AvatarMixin,
     ContactAccountDiscoMixin,
     FullCarbonMixin,
     ReactionRecipientMixin,
     ThreadRecipientMixin,
+    UpdateInfoMixin,
     metaclass=SubclassableOnce,
 ):
     """
@@ -81,7 +85,6 @@ class LegacyContact(
     STRIP_SHORT_DELAY = True
     _NON_FRIEND_PRESENCES_FILTER = {"subscribe", "unsubscribed"}
 
-    _avatar_pubsub_broadcast = True
     _avatar_bare_jid = True
 
     INVITATION_RECIPIENT = True
@@ -100,7 +103,6 @@ class LegacyContact(
         """
         super().__init__()
         self.session = session
-        self.user = session.user
         self.legacy_id: LegacyUserIdType = legacy_id
         """
         The legacy identifier of the :term:`Legacy Contact`.
@@ -116,19 +118,125 @@ class LegacyContact(
 
         self._name: Optional[str] = None
 
-        if self.xmpp.MARK_ALL_MESSAGES:
-            self._sent_order = list[str]()
-
         self.xmpp = session.xmpp
         self.jid = JID(self.jid_username + "@" + self.xmpp.boundjid.bare)
         self.jid.resource = self.RESOURCE
-        self.log = logging.getLogger(f"{self.user.bare_jid}:{self.jid.bare}")
-        self.participants = set["LegacyParticipant"]()
-        self.is_friend: bool = False
-        self.__added_to_roster = False
+        self.log = logging.getLogger(self.jid.bare)
+        self._set_logger_name()
+        self._is_friend: bool = False
+        self._added_to_roster = False
+        self._caps_ver: str | None = None
+        self._vcard_fetched = False
+        self._vcard: str | None = None
+        self._client_type: ClientType = "pc"
+
+    async def get_vcard(self, fetch=True) -> VCard4 | None:
+        if fetch and not self._vcard_fetched:
+            await self.fetch_vcard()
+        if self._vcard is None:
+            return None
+
+        return VCard4(xml=ET.fromstring(self._vcard))
+
+    @property
+    def is_friend(self):
+        return self._is_friend
+
+    @is_friend.setter
+    def is_friend(self, value: bool):
+        if value == self._is_friend:
+            return
+        self._is_friend = value
+        if self._updating_info:
+            return
+        self.__ensure_pk()
+        assert self.contact_pk is not None
+        self.xmpp.store.contacts.set_friend(self.contact_pk, value)
+
+    @property
+    def added_to_roster(self):
+        return self._added_to_roster
+
+    @added_to_roster.setter
+    def added_to_roster(self, value: bool):
+        if value == self._added_to_roster:
+            return
+        self._added_to_roster = value
+        if self._updating_info:
+            return
+        if self.contact_pk is None:
+            # during LegacyRoster.fill()
+            return
+        self.xmpp.store.contacts.set_added_to_roster(self.contact_pk, value)
+
+    @property
+    def participants(self) -> list["LegacyParticipant"]:
+        if self.contact_pk is None:
+            return []
+
+        self.__ensure_pk()
+        from ..group.participant import LegacyParticipant
+
+        return [
+            LegacyParticipant.get_self_or_unique_subclass().from_store(
+                self.session, stored, contact=self
+            )
+            for stored in self.xmpp.store.participants.get_for_contact(self.contact_pk)
+        ]
+
+    @property
+    def user_jid(self):
+        return self.session.user_jid
+
+    @property  # type:ignore
+    def DISCO_TYPE(self) -> ClientType:
+        return self._client_type
+
+    @DISCO_TYPE.setter
+    def DISCO_TYPE(self, value: ClientType) -> None:
+        self.client_type = value
+
+    @property
+    def client_type(self) -> ClientType:
+        """
+        The client type of this contact, cf https://xmpp.org/registrar/disco-categories.html#client
+
+        Default is "pc".
+        """
+        return self._client_type
+
+    @client_type.setter
+    def client_type(self, value: ClientType) -> None:
+        self._client_type = value
+        if self._updating_info:
+            return
+        self.__ensure_pk()
+        assert self.contact_pk is not None
+        self.xmpp.store.contacts.set_client_type(self.contact_pk, value)
+
+    def _set_logger_name(self):
+        self.log.name = f"{self.user_jid.bare}:contact:{self}"
 
     def __repr__(self):
-        return f"<Contact '{self.legacy_id}'/'{self.jid.bare}'>"
+        return f"<Contact #{self.contact_pk} '{self.name}' ({self.legacy_id} - {self.jid.local})'>"
+
+    def __ensure_pk(self):
+        if self.contact_pk is not None:
+            return
+        # This happens for legacy modules that don't follow the Roster.fill /
+        # populate contact attributes in Contact.update_info() method.
+        # This results in (even) less optimised SQL writes and read, but
+        # we allow it because it fits some legacy network libs better.
+        with self.xmpp.store.session() as orm:
+            orm.commit()
+            stored = self.xmpp.store.contacts.get_by_legacy_id(
+                self.user_pk, str(self.legacy_id)
+            )
+            if stored is None:
+                self.contact_pk = self.xmpp.store.contacts.update(self, commit=True)
+            else:
+                self.contact_pk = stored.id
+        assert self.contact_pk is not None
 
     def __get_subscription_string(self):
         if self.is_friend:
@@ -170,12 +278,13 @@ class LegacyContact(
     ) -> MessageOrPresenceTypeVar:
         if carbon and isinstance(stanza, Message):
             stanza["to"] = self.jid.bare
-            stanza["from"] = self.user.jid
+            stanza["from"] = self.user_jid
             self._privileged_send(stanza)
             return stanza  # type:ignore
 
         if isinstance(stanza, Presence):
-            self.__propagate_to_participants(stanza)
+            if not self._updating_info:
+                self.__propagate_to_participants(stanza)
             if (
                 not self.is_friend
                 and stanza["type"] not in self._NON_FRIEND_PRESENCES_FILTER
@@ -185,13 +294,19 @@ class LegacyContact(
             n = self.xmpp.plugin["xep_0172"].stanza.UserNick()
             n["nick"] = self.name
             stanza.append(n)
-        if self.xmpp.MARK_ALL_MESSAGES and is_markable(stanza):
-            self._sent_order.append(stanza["id"])
-        stanza["to"] = self.user.jid
+        if (
+            not self._updating_info
+            and self.xmpp.MARK_ALL_MESSAGES
+            and is_markable(stanza)
+        ):
+            self.__ensure_pk()
+            assert self.contact_pk is not None
+            self.xmpp.store.contacts.add_to_sent(self.contact_pk, stanza["id"])
+        stanza["to"] = self.user_jid
         stanza.send()
         return stanza
 
-    def get_msg_xmpp_id_up_to(self, horizon_xmpp_id: str):
+    def get_msg_xmpp_id_up_to(self, horizon_xmpp_id: str) -> list[str]:
         """
         Return XMPP msg ids sent by this contact up to a given XMPP msg id.
 
@@ -205,15 +320,9 @@ class LegacyContact(
         :param horizon_xmpp_id: The latest message
         :return: A list of XMPP ids or None if horizon_xmpp_id was not found
         """
-        for i, xmpp_id in enumerate(self._sent_order):
-            if xmpp_id == horizon_xmpp_id:
-                break
-        else:
-            return
-        i += 1
-        res = self._sent_order[:i]
-        self._sent_order = self._sent_order[i:]
-        return res
+        self.__ensure_pk()
+        assert self.contact_pk is not None
+        return self.xmpp.store.contacts.pop_sent_up_to(self.contact_pk, horizon_xmpp_id)
 
     @property
     def name(self):
@@ -226,12 +335,35 @@ class LegacyContact(
     def name(self, n: Optional[str]):
         if self._name == n:
             return
+        self._name = n
+        self._set_logger_name()
+        if self.is_friend and self.added_to_roster:
+            self.xmpp.pubsub.broadcast_nick(
+                user_jid=self.user_jid, jid=self.jid.bare, nick=n
+            )
+        if self._updating_info:
+            # means we're in update_info(), so no participants, and no need
+            # to write to DB now, it will be called in Roster.__finish_init_contact
+            return
         for p in self.participants:
             p.nickname = n
-        self._name = n
-        self.xmpp.pubsub.set_nick(user=self.user, jid=self.jid.bare, nick=n)
+        self.__ensure_pk()
+        assert self.contact_pk is not None
+        self.xmpp.store.contacts.update_nick(self.contact_pk, n)
+
+    def _get_cached_avatar_id(self) -> Optional[str]:
+        if self.contact_pk is None:
+            return None
+        return self.xmpp.store.contacts.get_avatar_legacy_id(self.contact_pk)
 
     def _post_avatar_update(self):
+        self.__ensure_pk()
+        assert self.contact_pk is not None
+        self.xmpp.store.contacts.set_avatar(
+            self.contact_pk,
+            self._avatar_pk,
+            None if self.avatar_id is None else str(self.avatar_id),
+        )
         for p in self.participants:
             self.log.debug("Propagating new avatar to %s", p.muc)
             p.send_last_presence(force=True, no_cache_online=True)
@@ -283,7 +415,26 @@ class LegacyContact(
         elif country:
             vcard.add_address(country, locality)
 
-        self.xmpp.vcard.set_vcard(self.jid.bare, vcard, {self.user.jid.bare})
+        self._vcard = str(vcard)
+        self._vcard_fetched = True
+        self.session.create_task(
+            self.xmpp.pubsub.broadcast_vcard_event(self.jid, self.user_jid, vcard)
+        )
+
+        if self._updating_info:
+            return
+
+        assert self.contact_pk is not None
+        self.xmpp.store.contacts.set_vcard(self.contact_pk, self._vcard)
+
+    def get_roster_item(self):
+        item = {
+            "subscription": self.__get_subscription_string(),
+            "groups": [self.xmpp.ROSTER_GROUP],
+        }
+        if (n := self.name) is not None:
+            item["name"] = n
+        return {self.jid.bare: item}
 
     async def add_to_roster(self, force=False):
         """
@@ -291,23 +442,15 @@ class LegacyContact(
 
         :param force: add even if the contact was already added successfully
         """
-        if self.__added_to_roster and not force:
+        if self.added_to_roster and not force:
             return
         if config.NO_ROSTER_PUSH:
             log.debug("Roster push request by plugin ignored (--no-roster-push)")
             return
-        item = {
-            "subscription": self.__get_subscription_string(),
-            "groups": [self.xmpp.ROSTER_GROUP],
-        }
-        if (n := self.name) is not None:
-            item["name"] = n
-        kw = dict(
-            jid=self.user.jid,
-            roster_items={self.jid.bare: item},
-        )
         try:
-            await self._set_roster(**kw)
+            await self._set_roster(
+                jid=self.user_jid, roster_items=self.get_roster_item()
+            )
         except PermissionError:
             warnings.warn(
                 "Slidge does not have privileges to add contacts to the roster. Refer"
@@ -325,18 +468,33 @@ class LegacyContact(
         else:
             # we only broadcast pubsub events for contacts added to the roster
             # so if something was set before, we need to push it now
-            self.__added_to_roster = True
-            self.session.create_task(self.__broadcast_pubsub_items())
+            self.added_to_roster = True
             self.send_last_presence()
 
     async def __broadcast_pubsub_items(self):
-        await self.xmpp.pubsub.broadcast_all(JID(self.jid.bare), self.user.jid)
+        if not self.is_friend:
+            return
+        if not self.added_to_roster:
+            return
+        cached_avatar = self.get_cached_avatar()
+        if cached_avatar is not None:
+            await self.xmpp.pubsub.broadcast_avatar(
+                self.jid.bare, self.session.user_jid, cached_avatar
+            )
+        nick = self.name
+
+        if nick is not None:
+            self.xmpp.pubsub.broadcast_nick(
+                self.session.user_jid,
+                self.jid.bare,
+                nick,
+            )
 
     async def _set_roster(self, **kw):
         try:
-            return await self.xmpp["xep_0356"].set_roster(**kw)
+            await self.xmpp["xep_0356"].set_roster(**kw)
         except PermissionError:
-            return await self.xmpp["xep_0356_old"].set_roster(**kw)
+            await self.xmpp["xep_0356_old"].set_roster(**kw)
 
     def send_friend_request(self, text: Optional[str] = None):
         presence = self._make_presence(ptype="subscribe", pstatus=text, bare=True)
@@ -350,6 +508,8 @@ class LegacyContact(
         :param text: Optional message from the friend to the user
         """
         self.is_friend = True
+        self.added_to_roster = True
+        self.__ensure_pk()
         self.log.debug("Accepting friend request")
         presence = self._make_presence(ptype="subscribed", pstatus=text, bare=True)
         self._send(presence, nick=True)
@@ -415,7 +575,7 @@ class LegacyContact(
         their 'friends'".
         """
         for ptype in "unsubscribe", "unsubscribed", "unavailable":
-            self.xmpp.send_presence(pfrom=self.jid, pto=self.user.jid.bare, ptype=ptype)  # type: ignore
+            self.xmpp.send_presence(pfrom=self.jid, pto=self.user_jid.bare, ptype=ptype)  # type: ignore
 
     async def update_info(self):
         """
@@ -442,6 +602,50 @@ class LegacyContact(
         """
         pass
 
+    def _make_presence(
+        self,
+        *,
+        last_seen: Optional[datetime.datetime] = None,
+        status_codes: Optional[set[int]] = None,
+        user_full_jid: Optional[JID] = None,
+        **presence_kwargs,
+    ):
+        p = super()._make_presence(last_seen=last_seen, **presence_kwargs)
+        caps = self.xmpp.plugin["xep_0115"]
+        if p.get_from().resource and self._caps_ver:
+            p["caps"]["node"] = caps.caps_node
+            p["caps"]["hash"] = caps.hash
+            p["caps"]["ver"] = self._caps_ver
+        return p
+
+    @classmethod
+    def from_store(cls, session, stored: Contact, *args, **kwargs) -> Self:
+        contact = cls(
+            session,
+            cls.xmpp.LEGACY_CONTACT_ID_TYPE(stored.legacy_id),
+            stored.jid.username,  # type: ignore
+            *args,  # type: ignore
+            **kwargs,  # type: ignore
+        )
+        contact.contact_pk = stored.id
+        contact._name = stored.nick
+        contact._is_friend = stored.is_friend
+        contact._added_to_roster = stored.added_to_roster
+        if (data := stored.extra_attributes) is not None:
+            contact.deserialize_extra_attributes(data)
+        contact._caps_ver = stored.caps_ver
+        contact._set_logger_name()
+        contact._AvatarMixin__avatar_unique_id = (  # type:ignore
+            None
+            if stored.avatar_legacy_id is None
+            else session.xmpp.AVATAR_ID_TYPE(stored.avatar_legacy_id)
+        )
+        contact._avatar_pk = stored.avatar_id
+        contact._vcard = stored.vcard
+        contact._vcard_fetched = stored.vcard_fetched
+        contact._client_type = stored.client_type
+        return contact
+
 
 def is_markable(stanza: Union[Message, Presence]):
     if isinstance(stanza, Presence):

slidge/contact/roster.py

@@ -1,11 +1,15 @@
 import asyncio
 import logging
-from typing import TYPE_CHECKING, Generic, Optional, Type
+import warnings
+from typing import TYPE_CHECKING, AsyncIterator, Generic, Iterator, Optional, Type
 
 from slixmpp import JID
+from slixmpp.exceptions import IqError, XMPPError
 from slixmpp.jid import JID_UNESCAPE_TRANSFORMATIONS, _unescape_node
 
 from ..core.mixins.lock import NamedLockMixin
+from ..db.models import Contact
+from ..db.store import ContactStore
 from ..util import SubclassableOnce
 from ..util.types import LegacyContactType, LegacyUserIdType
 from .contact import LegacyContact
@@ -43,38 +47,27 @@ class LegacyRoster(
             LegacyContact.get_self_or_unique_subclass()
         )
         self._contact_cls.xmpp = session.xmpp
+        self.__store: ContactStore = session.xmpp.store.contacts
 
         self.session = session
-        self._contacts_by_bare_jid: dict[str, LegacyContactType] = {}
-        self._contacts_by_legacy_id: dict[LegacyUserIdType, LegacyContactType] = {}
-        self.log = logging.getLogger(f"{self.session.user.bare_jid}:roster")
+        self.log = logging.getLogger(f"{self.session.user_jid.bare}:roster")
         self.user_legacy_id: Optional[LegacyUserIdType] = None
         self.ready: asyncio.Future[bool] = self.session.xmpp.loop.create_future()
+        self.__filling = False
         super().__init__()
 
     def __repr__(self):
-        return f"<Roster of {self.session.user}>"
-
-    def __iter__(self):
-        return iter(self._contacts_by_legacy_id.values())
-
-    async def __finish_init_contact(
-        self, legacy_id: LegacyUserIdType, jid_username: str, *args, **kwargs
-    ):
-        c = self._contact_cls(self.session, legacy_id, jid_username, *args, **kwargs)
-        async with self.lock(("finish", c)):
-            if legacy_id in self._contacts_by_legacy_id:
-                self.log.debug("Already updated %s", c)
-                return c
-            await c.avatar_wrap_update_info()
-            self._contacts_by_legacy_id[legacy_id] = c
-            self._contacts_by_bare_jid[c.jid.bare] = c
-        return c
+        return f"<Roster of {self.session.user_jid}>"
+
+    def __iter__(self) -> Iterator[LegacyContactType]:
+        with self.__store.session():
+            for stored in self.__store.get_all(user_pk=self.session.user_pk):
+                yield self._contact_cls.from_store(self.session, stored)
 
     def known_contacts(self, only_friends=True) -> dict[str, LegacyContactType]:
         if only_friends:
-            return {j: c for j, c in self._contacts_by_bare_jid.items() if c.is_friend}
-        return self._contacts_by_bare_jid
+            return {c.jid.bare: c for c in self if c.is_friend}
+        return {c.jid.bare: c for c in self}
 
     async def by_jid(self, contact_jid: JID) -> LegacyContactType:
         # """
@@ -89,16 +82,22 @@ class LegacyRoster(
         # """
         username = contact_jid.node
         async with self.lock(("username", username)):
-            bare = contact_jid.bare
-            c = self._contacts_by_bare_jid.get(bare)
-            if c is None:
-                legacy_id = await self.jid_username_to_legacy_id(username)
-                log.debug("Contact %s not found", contact_jid)
-                if self.get_lock(("legacy_id", legacy_id)):
-                    log.debug("Already updating %s", contact_jid)
-                    return await self.by_legacy_id(legacy_id)
-                c = await self.__finish_init_contact(legacy_id, username)
-            return c
+            legacy_id = await self.jid_username_to_legacy_id(username)
+            log.debug("Contact %s not found", contact_jid)
+            if self.get_lock(("legacy_id", legacy_id)):
+                log.debug("Already updating %s", contact_jid)
+                return await self.by_legacy_id(legacy_id)
+
+            with self.__store.session():
+                stored = self.__store.get_by_jid(self.session.user_pk, contact_jid)
+                return await self.__update_contact(stored, legacy_id, username)
+
+    def by_jid_only_if_exists(self, contact_jid: JID) -> LegacyContactType | None:
+        with self.__store.session():
+            stored = self.__store.get_by_jid(self.session.user_pk, contact_jid)
+            if stored is not None and stored.updated:
+                return self._contact_cls.from_store(self.session, stored)
+        return None
 
     async def by_legacy_id(
         self, legacy_id: LegacyUserIdType, *args, **kwargs
@@ -121,20 +120,47 @@ class LegacyRoster(
         if legacy_id == self.user_legacy_id:
             raise ContactIsUser
         async with self.lock(("legacy_id", legacy_id)):
-            c = self._contacts_by_legacy_id.get(legacy_id)
-            if c is None:
-                username = await self.legacy_id_to_jid_username(legacy_id)
-                log.debug("Contact %s not found", legacy_id)
-                if self.get_lock(("username", username)):
-                    log.debug("Already updating %s", username)
-                    jid = JID()
-                    jid.node = username
-                    jid.domain = self.session.xmpp.boundjid.bare
-                    return await self.by_jid(jid)
-                c = await self.__finish_init_contact(
-                    legacy_id, username, *args, **kwargs
+            username = await self.legacy_id_to_jid_username(legacy_id)
+            if self.get_lock(("username", username)):
+                log.debug("Already updating %s", username)
+                jid = JID()
+                jid.node = username
+                jid.domain = self.session.xmpp.boundjid.bare
+                return await self.by_jid(jid)
+
+            with self.__store.session():
+                stored = self.__store.get_by_legacy_id(
+                    self.session.user_pk, str(legacy_id)
+                )
+                return await self.__update_contact(
+                    stored, legacy_id, username, *args, **kwargs
                 )
-            return c
+
+    async def __update_contact(
+        self,
+        stored: Contact | None,
+        legacy_id: LegacyUserIdType,
+        username: str,
+        *a,
+        **kw,
+    ) -> LegacyContactType:
+        if stored is None:
+            contact = self._contact_cls(self.session, legacy_id, username, *a, **kw)
+        else:
+            contact = self._contact_cls.from_store(self.session, stored, *a, **kw)
+            if stored.updated:
+                return contact
+
+        try:
+            with contact.updating_info():
+                await contact.avatar_wrap_update_info()
+        except XMPPError:
+            raise
+        except Exception as e:
+            raise XMPPError("internal-server-error", str(e))
+        contact._caps_ver = await contact.get_caps_ver(contact.jid)
+        contact.contact_pk = self.__store.update(contact, commit=not self.__filling)
+        return contact
 
     async def by_stanza(self, s) -> LegacyContact:
         # """
@@ -174,18 +200,63 @@ class LegacyRoster(
         """
         return _unescape_node(jid_username)
 
-    async def fill(self):
+    async def _fill(self):
+        try:
+            if hasattr(self.session.xmpp, "TEST_MODE"):
+                # dirty hack to avoid mocking xmpp server replies to this
+                # during tests
+                raise PermissionError
+            iq = await self.session.xmpp["xep_0356"].get_roster(
+                self.session.user_jid.bare
+            )
+            user_roster = iq["roster"]["items"]
+        except (PermissionError, IqError):
+            user_roster = None
+
+        with self.__store.session() as orm:
+            self.__filling = True
+            async for contact in self.fill():
+                if user_roster is None:
+                    continue
+                item = contact.get_roster_item()
+                old = user_roster.get(contact.jid.bare)
+                if old is not None and all(
+                    old[k] == item[contact.jid.bare].get(k)
+                    for k in ("subscription", "groups", "name")
+                ):
+                    self.log.debug("No need to update roster")
+                    continue
+                self.log.debug("Updating roster")
+                try:
+                    await self.session.xmpp["xep_0356"].set_roster(
+                        self.session.user_jid.bare,
+                        item,
+                    )
+                except (PermissionError, IqError) as e:
+                    warnings.warn(f"Could not add to roster: {e}")
+                else:
+                    contact._added_to_roster = True
+            orm.commit()
+        self.__filling = False
+
+    async def fill(self) -> AsyncIterator[LegacyContact]:
         """
         Populate slidge's "virtual roster".
 
-        Override this and in it, ``await self.by_legacy_id(contact_id)``
-        for the every legacy contacts of the user for which you'd like to
-        set an avatar, nickname, vcard…
+        This should yield contacts that are meant to be added to the user's
+        roster, typically by using ``await self.by_legacy_id(contact_id)``.
+        Setting the contact nicknames, avatar, etc. should be in
+        :meth:`LegacyContact.update_info()`
+
+        It's not mandatory to override this method, but it is recommended way
+        to populate "friends" of the user. Calling
+        ``await (await self.by_legacy_id(contact_id)).add_to_roster()``
+        accomplishes the same thing, but doing it in here allows to batch
+        DB queries and is better performance-wise.
 
-        Await ``Contact.add_to_roster()`` in here to add the contact to the
-        user's XMPP roster.
         """
-        pass
+        return
+        yield
 
 
 ESCAPE_TABLE = "".maketrans({v: k for k, v in JID_UNESCAPE_TRANSFORMATIONS.items()})