Expose http_client and public_room_list_manager as properties

UPGRADE.rst

@@ -1,16 +1,3 @@
-Upgrading to v1.20.0
-====================
-
-Shared rooms endpoint (MSC2666)
--------------------------------
-
-This release contains a new unstable endpoint `/_matrix/client/unstable/uk.half-shot.msc2666/user/shared_rooms/.*`
-for fetching rooms one user has in common with another. This feature requires the
-`update_user_directory` config flag to be `True`. If you are you are using a `synapse.app.user_dir`
-worker, requests to this endpoint must be handled by that worker.
-See `docs/workers.md <docs/workers.md>`_ for more details.
-
-
 Upgrading Synapse
 =================
 
@@ -145,12 +132,15 @@ ThirdPartyEventRules breaking changes
 -------------------------------------
 
 This release introduces a backwards-incompatible change to modules making use of
-`ThirdPartyEventRules` in Synapse.
+``ThirdPartyEventRules`` in Synapse. If you make use of a module defined under the
+``third_party_event_rules`` config option, please make sure it is updated to handle
+the below change:
 
-The `http_client` argument is no longer passed to modules as they are initialised. Instead,
-modules are expected to make use of the `http_client` property on the `ModuleApi` class.
-Modules are now passed a `module_api` argument during initialisation, which is an instance of
-`ModuleApi`.
+The ``http_client`` argument is no longer passed to modules as they are initialised. Instead,
+modules are expected to make use of the ``http_client`` property on the ``ModuleApi`` class.
+Modules are now passed a ``module_api`` argument during initialisation, which is an instance of
+``ModuleApi``. ``ModuleApi`` instances have a ``http_client`` property which acts the same as
+the ``http_client`` argument previously passed to ``ThirdPartyEventRules`` modules.
 
 Upgrading to v1.18.0
 ====================

synapse/module_api/__init__.py

@@ -36,50 +36,6 @@ __all__ = ["errors", "make_deferred_yieldable", "run_in_background", "ModuleApi"
 logger = logging.getLogger(__name__)
 
 
-class PublicRoomListManager:
-    """Contains methods for adding to, removing from and querying whether a room
-    is in the public room list.
-
-    Args:
-        hs: The Homeserver object
-    """
-
-    def __init__(self, hs: "HomeServer"):
-        self._store = hs.get_datastore()
-
-    async def room_is_in_public_room_list(self, room_id: str) -> bool:
-        """Checks whether a room is in the public room list.
-
-        Args:
-            room_id: The ID of the room.
-
-        Returns:
-            Whether the room is in the public room list. Returns False if the room does
-            not exist.
-        """
-        room = await self._store.get_room(room_id)
-        if not room:
-            return False
-
-        return room.get("is_public", False)
-
-    async def add_room_to_public_room_list(self, room_id: str) -> None:
-        """Publishes a room to the public room list.
-
-        Args:
-            room_id: The ID of the room.
-        """
-        await self._store.set_room_is_public(room_id, True)
-
-    async def remove_room_from_public_room_list(self, room_id: str) -> None:
-        """Removes a room from the public room list.
-
-        Args:
-            room_id: The ID of the room.
-        """
-        await self._store.set_room_is_public(room_id, False)
-
-
 class ModuleApi:
     """A proxy object that gets passed to various plugin modules so they
     can register new users etc if necessary.
@@ -92,8 +48,26 @@ class ModuleApi:
         self._auth = hs.get_auth()
         self._auth_handler = auth_handler
 
-        self.http_client = hs.get_simple_http_client()  # type: SimpleHttpClient
-        self.public_room_list_manager = PublicRoomListManager(hs)
+        # We expose these as properties below in order to attach a helpful docstring.
+        self._http_client = hs.get_simple_http_client()  # type: SimpleHttpClient
+        self._public_room_list_manager = PublicRoomListManager(hs)
+
+    @property
+    def http_client(self):
+        """Allows making outbound HTTP requests to remote resources.
+
+        An instance of synapse.http.client.SimpleHttpClient
+        """
+        return self._http_client
+
+    @property
+    def public_room_list_manager(self):
+        """Allows adding to, removing from and checking the status of rooms in the
+        public room list.
+
+        An instance of synapse.module_api.PublicRoomListManager
+        """
+        return self._public_room_list_manager
 
     def get_user_by_req(self, req, allow_guest=False):
         """Check the access_token provided for a request
@@ -318,3 +292,44 @@ class ModuleApi:
         await self._auth_handler.complete_sso_login(
             registered_user_id, request, client_redirect_url,
         )
+
+
+class PublicRoomListManager:
+    """Contains methods for adding to, removing from and querying whether a room
+    is in the public room list.
+    """
+
+    def __init__(self, hs: "HomeServer"):
+        self._store = hs.get_datastore()
+
+    async def room_is_in_public_room_list(self, room_id: str) -> bool:
+        """Checks whether a room is in the public room list.
+
+        Args:
+            room_id: The ID of the room.
+
+        Returns:
+            Whether the room is in the public room list. Returns False if the room does
+            not exist.
+        """
+        room = await self._store.get_room(room_id)
+        if not room:
+            return False
+
+        return room.get("is_public", False)
+
+    async def add_room_to_public_room_list(self, room_id: str) -> None:
+        """Publishes a room to the public room list.
+
+        Args:
+            room_id: The ID of the room.
+        """
+        await self._store.set_room_is_public(room_id, True)
+
+    async def remove_room_from_public_room_list(self, room_id: str) -> None:
+        """Removes a room from the public room list.
+
+        Args:
+            room_id: The ID of the room.
+        """
+        await self._store.set_room_is_public(room_id, False)