#221 Deliver a 2.0.0 version (#228)

* #226 Added the search messages by query endpoint (#227)

* Bumped version to 2.0.0

Author: symphony-elias

docsrc/markdown/message_service.md

@@ -5,6 +5,7 @@ More precisely:
 * [Get a message](https://developers.symphony.com/restapi/reference#get-message-v1)
 * [Get messages](https://developers.symphony.com/restapi/reference#messages-v4)
 * [Get message IDs by timestamp](https://developers.symphony.com/restapi/reference#get-message-ids-by-timestamp)
+* [Search messages](https://developers.symphony.com/restapi/reference#message-search-post)
 * [Send message](https://developers.symphony.com/restapi/reference#create-message-v4)
 * [Import messages](https://developers.symphony.com/restapi/reference#import-message-v4)
 * [Get attachment](https://developers.symphony.com/restapi/reference#attachment)

examples/services/messages.py

@@ -5,6 +5,7 @@
 from symphony.bdk.core.config.loader import BdkConfigLoader
 from symphony.bdk.core.service.message.model import Message
 from symphony.bdk.core.symphony_bdk import SymphonyBdk
+from symphony.bdk.gen.agent_model.message_search_query import MessageSearchQuery
 
 
 async def run():
@@ -28,6 +29,10 @@ async def run():
             message = Message(content="<messageML>Hello, World!</messageML>", attachments=[(attachment, preview)])
             await message_service.blast_message([stream_id_1, stream_id_2], message)
 
+        async for m in await message_service.search_all_messages(MessageSearchQuery(text="some_text",
+                                                                                    stream_id=stream_id_1)):
+            logging.debug(m.message_id)
+
         logging.info("Obo example:")
         obo_auth_session = bdk.obo(username="username")
         async with bdk.obo_services(obo_auth_session) as obo_services:

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "symphony_bdk_python"
-version = "2.0b6"
+version = "2.0.0"
 license = "Apache-2.0"
 description = "Symphony Bot Development Kit for Python"
 readme = "README.md"

symphony/bdk/core/service/message/message_service.py

@@ -1,10 +1,12 @@
-from typing import Union, List, Tuple, IO
+from typing import Union, List, Tuple, IO, AsyncGenerator
 
 from symphony.bdk.core.auth.auth_session import AuthSession
 from symphony.bdk.core.config.model.bdk_retry_config import BdkRetryConfig
 from symphony.bdk.core.service.message.model import Message
 from symphony.bdk.core.service.message.multi_attachments_messages_api import MultiAttachmentsMessagesApi
+from symphony.bdk.core.service.pagination import offset_based_pagination
 from symphony.bdk.gen.agent_api.attachments_api import AttachmentsApi
+from symphony.bdk.gen.agent_model.message_search_query import MessageSearchQuery
 from symphony.bdk.gen.agent_model.v4_import_response import V4ImportResponse
 from symphony.bdk.gen.agent_model.v4_imported_message import V4ImportedMessage
 from symphony.bdk.gen.agent_model.v4_message import V4Message
@@ -419,3 +421,58 @@ async def get_message_relationships(
             "user_agent": ""
         }
         return await self._default_api.v1_admin_messages_message_id_metadata_relationships_get(**params)
+
+    @retry
+    async def search_messages(self, query: MessageSearchQuery, sort_dir: str = "desc", skip: int = 0,
+                              limit: int = 50) -> List[V4Message]:
+        """Searches for messages in the context of a specified user, given an argument-based query and pagination
+        attributes (skip and limit parameters).
+        See: `Message Search (using POST) <https://developers.symphony.com/restapi/reference#message-search-post>`_
+
+        :param query: The search query arguments
+        :param sort_dir: Sorting direction for response. Possible values are desc (default) and asc.
+        :param skip: Number of messages to skip. Default: 0
+        :param limit: Maximum number of messages to return. Default: 50
+        :return: The list of matching messages in the stream
+        """
+        MessageService._validate_message_search_query(query)
+        params = {
+            "session_token": await self._auth_session.session_token,
+            "key_manager_token": await self._auth_session.key_manager_token,
+            "query": query,
+            "sort_dir": sort_dir,
+            "skip": skip,
+            "limit": limit
+        }
+        message_list = await self._messages_api.v1_message_search_post(**params)
+        return message_list.value  # endpoint returns empty list when no values found
+
+    async def search_all_messages(self, query: MessageSearchQuery, sort_dir: str = "desc", chunk_size: int = 50,
+                                  max_number: int = None) -> AsyncGenerator[V4Message, None]:
+        """Searches for messages in the context of a specified user, given an argument-based query.
+        See: `Message Search (using POST) <https://developers.symphony.com/restapi/reference#message-search-post>`_
+
+        :param query: The search query arguments
+        :param sort_dir: Sorting direction for response. Possible values are desc (default) and asc.
+        :param chunk_size: the maximum number of elements to retrieve in one underlying HTTP call
+        :param max_number: the total maximum number of elements to retrieve
+        :return: an asynchronous generator of matching messages
+        """
+
+        async def search_messages_one_page(skip, limit):
+            return await self.search_messages(query, sort_dir, skip, limit)
+
+        return offset_based_pagination(search_messages_one_page, chunk_size, max_number)
+
+    @staticmethod
+    def _validate_message_search_query(query: MessageSearchQuery):
+        # Check streamType value among accepted ones if specified
+        if query.stream_type is not None and query.stream_type not in ["CHAT", "IM", "MIM", "ROOM", "POST"]:
+            raise ValueError(f"Wrong stream type {query.stream_type}. "
+                             f"Accepted values are: CHAT (1-1 instant messages and multi-party instant messages), "
+                             f"IM (1-1 instant message), MIM (multi-party instant message), "
+                             f"ROOM or POST (user profile wall posts)")
+
+        # Text queries require streamId to be provided
+        if query.text is not None and query.stream_id is None:
+            raise ValueError("Message text queries require a stream_id to be provided.")

tests/core/service/message/message_service_test.py

@@ -8,6 +8,7 @@
 from symphony.bdk.core.service.message.model import Message
 from symphony.bdk.core.service.message.multi_attachments_messages_api import MultiAttachmentsMessagesApi
 from symphony.bdk.gen.agent_api.attachments_api import AttachmentsApi
+from symphony.bdk.gen.agent_model.message_search_query import MessageSearchQuery
 from symphony.bdk.gen.agent_model.v4_import_response_list import V4ImportResponseList
 from symphony.bdk.gen.agent_model.v4_imported_message import V4ImportedMessage
 from symphony.bdk.gen.agent_model.v4_message import V4Message
@@ -324,3 +325,90 @@ async def test_get_message_relationships(mocked_api_client, message_service):
     assert message_relationships.message_id == "TYgOZ65dVsu3SeK7u2YdfH///o6fzBu"
     assert message_relationships.parent.message_id == "/rbLQW5UHKZffM0FlLO2rn///o6vTck"
     assert message_relationships.parent.relationship_type == "REPLY"
+
+
+@pytest.mark.asyncio
+async def test_search_messages_with_hashtag(mocked_api_client, message_service):
+    mocked_api_client.call_api.return_value = \
+        get_deserialized_object_from_resource(V4MessageList, "message_response/list_messages.json")
+
+    messages = await message_service.search_messages(MessageSearchQuery(hashtag="tag"))
+    assert len(messages) == 1
+    assert messages[0].message_id == "test-message1"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("stream_type", ["CHAT", "IM", "MIM", "ROOM", "POST"])
+async def test_search_messages_with_valid_stream_type(mocked_api_client, message_service, stream_type):
+    mocked_api_client.call_api.return_value = \
+        get_deserialized_object_from_resource(V4MessageList, "message_response/list_messages.json")
+
+    messages = await message_service.search_messages(MessageSearchQuery(stream_type=stream_type))
+    assert len(messages) == 1
+    assert messages[0].message_id == "test-message1"
+
+
+@pytest.mark.asyncio
+async def test_search_messages_with_invalid_stream_type(mocked_api_client, message_service):
+    mocked_api_client.call_api.return_value = \
+        get_deserialized_object_from_resource(V4MessageList, "message_response/list_messages.json")
+
+    with pytest.raises(ValueError):
+        await message_service.search_messages(MessageSearchQuery(stream_type="invalid"))
+
+
+@pytest.mark.asyncio
+async def test_search_messages_with_text_and_sid(mocked_api_client, message_service):
+    mocked_api_client.call_api.return_value = \
+        get_deserialized_object_from_resource(V4MessageList, "message_response/list_messages.json")
+
+    messages = await message_service.search_messages(MessageSearchQuery(text="some text", stream_id="sid"))
+    assert len(messages) == 1
+    assert messages[0].message_id == "test-message1"
+
+
+@pytest.mark.asyncio
+async def test_search_messages_with_text_and_no_sid(mocked_api_client, message_service):
+    mocked_api_client.call_api.return_value = \
+        get_deserialized_object_from_resource(V4MessageList, "message_response/list_messages.json")
+
+    with pytest.raises(ValueError):
+        await message_service.search_messages(MessageSearchQuery(text="some text"))
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("stream_type", ["CHAT", "IM", "MIM", "ROOM", "POST"])
+async def test_search_messages_with_stream_type_text_and_sid(mocked_api_client, message_service, stream_type):
+    mocked_api_client.call_api.return_value = \
+        get_deserialized_object_from_resource(V4MessageList, "message_response/list_messages.json")
+
+    messages = await message_service.search_messages(
+        MessageSearchQuery(text="some text", stream_id="sid", stream_type=stream_type))
+    assert len(messages) == 1
+    assert messages[0].message_id == "test-message1"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("stream_type", ["CHAT", "IM", "MIM", "ROOM", "POST"])
+async def test_search_messages_with_stream_type_text_and_no_sid(mocked_api_client, message_service, stream_type):
+    mocked_api_client.call_api.return_value = \
+        get_deserialized_object_from_resource(V4MessageList, "message_response/list_messages.json")
+
+    with pytest.raises(ValueError):
+        await message_service.search_messages(MessageSearchQuery(text="some text", stream_type=stream_type))
+
+
+@pytest.mark.asyncio
+async def test_search_all_messages(mocked_api_client, message_service):
+    mocked_api_client.call_api.side_effect = \
+        [get_deserialized_object_from_resource(V4MessageList, "message_response/list_messages.json"),
+         V4MessageList(value=[])]
+    chunk_size = 1
+
+    message_generator = await message_service.search_all_messages(MessageSearchQuery(hashtag="tag"),
+                                                                  chunk_size=chunk_size)
+    messages = [m async for m in message_generator]
+    assert len(messages) == 1
+    assert messages[0].message_id == "test-message1"
+
+    assert mocked_api_client.call_api.call_count == 2