Add ability to Knock on a Room and enable Knocking for a Room (#418)

* Adds working knock

* Adds basic tests for client/type Knock

* Adds comments on the RoomKnock classes

* Adds ability to enable knocking for a room

* Use suggested commit. Ran linters

nio/api.py

@@ -777,6 +777,36 @@ def room_unban(
             Api.to_json(body),
         )
 
+    @staticmethod
+    def room_knock(
+        access_token: str,
+        room_id: str,
+        reason: Optional[str] = None,
+    ) -> Tuple[str, str, str]:
+        """Knocks on a room for the user.
+
+        Returns the HTTP method, HTTP path and data for the request.
+
+        Args:
+            access_token (str): The access token to be used with the request.
+            room_id (str): The room id of the room that the user will be
+                knocking on.
+            reason (str, optional): The reason the user is knocking.
+        """
+
+        path = ["knock", room_id]
+        query_parameters = {"access_token": access_token}
+        body = {}
+
+        if reason:
+            body["reason"] = reason
+
+        return (
+            "POST",
+            Api._build_path(path, query_parameters),
+            Api.to_json(body),
+        )
+
     @staticmethod
     def room_invite(access_token, room_id, user_id):
         # type (str, str, str) -> Tuple[str, str, str]

nio/client/async_client.py

@@ -173,6 +173,8 @@
     RoomKeyRequestResponse,
     RoomKickError,
     RoomKickResponse,
+    RoomKnockError,
+    RoomKnockResponse,
     RoomLeaveError,
     RoomLeaveResponse,
     RoomMessagesError,
@@ -2234,6 +2236,50 @@ async def join(self, room_id: str) -> Union[JoinResponse, JoinError]:
         method, path, data = Api.join(self.access_token, room_id)
         return await self._send(JoinResponse, method, path, data)
 
+    @logged_in_async
+    async def room_knock(
+        self,
+        room_id: str,
+        reason: Optional[str] = None,
+    ) -> Union[RoomKnockResponse, RoomKnockError]:
+        """Knock on a room.
+
+        Calls receive_response() to update the client state if necessary.
+
+        Returns either a `RoomKnockResponse` if the request was successful or
+        a `RoomKnockError` if there was an error with the request.
+
+        Args:
+            room_id (str): The room id of the room that the user is
+                knocking on.
+            reason (str, optional): The reason for the knock.
+        """
+        method, path, data = Api.room_knock(
+            self.access_token,
+            room_id,
+            reason,
+        )
+        return await self._send(RoomKnockResponse, method, path, data)
+
+    @logged_in_async
+    async def room_enable_knocking(
+        self,
+        room_id: str,
+    ) -> Union[RoomPutStateResponse, RoomPutStateError]:
+        """Enables knocking for a room.
+
+        Returns either a `RoomPutStateResponse` if the request was successful
+        or a `RoomPutStateError` if there was an error with the request.
+
+        Args:
+            room_id (str): The room id of the room to enable knocking for.
+        """
+        return await self.room_put_state(
+            room_id,
+            event_type="m.room.join_rules",
+            content={"join_rule": "knock"},
+        )
+
     @logged_in_async
     async def room_invite(
         self,

nio/events/room_events.py

@@ -1483,7 +1483,7 @@ class RoomMemberEvent(Event):
             cases except for when membership is join, the user ID in the sender
             attribute does not need to match the user ID in the state_key.
         membership (str): The membership state of the user. One of "invite",
-            "join", "leave", "ban".
+            "join", "leave", "ban", "knock".
         prev_membership (str, optional): The previous membership state that
             this one is overwriting. Can be None in which case the membership
             state is assumed to have been "leave".

nio/responses.py

@@ -97,6 +97,8 @@
     "RoomInviteError",
     "RoomKickResponse",
     "RoomKickError",
+    "RoomKnockResponse",
+    "RoomKnockError",
     "RoomLeaveResponse",
     "RoomLeaveError",
     "RoomForgetResponse",
@@ -505,6 +507,12 @@ class JoinError(ErrorResponse):
     pass
 
 
+class RoomKnockError(ErrorResponse):
+    """A response representing a unsuccessful room knock request."""
+
+    pass
+
+
 class RoomLeaveError(ErrorResponse):
     pass
 
@@ -1263,6 +1271,12 @@ def create_error(parsed_dict):
         return JoinError.from_dict(parsed_dict)
 
 
+class RoomKnockResponse(RoomIdResponse):
+    @staticmethod
+    def create_error(parsed_dict):
+        return RoomKnockError.from_dict(parsed_dict)
+
+
 class RoomLeaveResponse(EmptyResponse):
     @staticmethod
     def create_error(parsed_dict):

tests/async_client_test.py

@@ -95,6 +95,7 @@
     RoomInviteResponse,
     RoomKeyRequest,
     RoomKickResponse,
+    RoomKnockResponse,
     RoomLeaveResponse,
     RoomMemberEvent,
     RoomMessagesResponse,
@@ -1431,6 +1432,21 @@ async def test_room_invite(self, async_client, aioresponse):
         resp = await async_client.room_invite(TEST_ROOM_ID, ALICE_ID)
         assert isinstance(resp, RoomInviteResponse)
 
+    async def test_room_knock(self, async_client, aioresponse):
+        await async_client.receive_response(
+            LoginResponse.from_dict(self.login_response)
+        )
+        assert async_client.logged_in
+
+        aioresponse.post(
+            f"https://example.org/_matrix/client/r0/knock/{TEST_ROOM_ID}?access_token=abc123",
+            status=200,
+            payload=self.room_id_response(TEST_ROOM_ID),
+        )
+
+        resp = await async_client.room_knock(TEST_ROOM_ID, reason="test")
+        assert isinstance(resp, RoomKnockResponse)
+
     async def test_room_leave(self, async_client, aioresponse):
         await async_client.receive_response(
             LoginResponse.from_dict(self.login_response)

tests/responses_test.py

@@ -30,6 +30,7 @@
     RoomForgetResponse,
     RoomKeyRequestError,
     RoomKeyRequestResponse,
+    RoomKnockResponse,
     RoomLeaveResponse,
     RoomMessagesResponse,
     RoomTypingResponse,
@@ -251,6 +252,11 @@ def test_join(self):
         response = JoinResponse.from_dict(parsed_dict)
         assert isinstance(response, JoinResponse)
 
+    def test_knock(self):
+        parsed_dict = TestClass._load_response("tests/data/room_id.json")
+        response = RoomKnockResponse.from_dict(parsed_dict)
+        assert isinstance(response, RoomKnockResponse)
+
     def test_room_leave(self):
         response = RoomLeaveResponse.from_dict({})
         assert isinstance(response, RoomLeaveResponse)