Add docstring

Author: Palbahngmiyine

solapi/services/message_service.py

@@ -30,7 +30,20 @@
 
 
 class SolapiMessageService:
+    """Solapi Message Service for handling message-related operations.
+
+    This class provides methods to interact with the Solapi API for sending various types of messages
+    (SMS, LMS, MMS, 알림톡, 친구톡, RCS, etc.), managing message groups, uploading files, 
+    and checking account balance.
+    """
+
     def __init__(self, api_key: str, api_secret: str):
+        """Initialize the Solapi Message Service.
+
+        Args:
+            api_key: The API key for authentication.
+            api_secret: The API secret for authentication.
+        """
         self.base_url = "https://api.solapi.com"
         self.auth_info: AuthenticationParameter = {
             "api_key": api_key,
@@ -42,6 +55,28 @@ def send(
         messages: Union[list[Message], Message],
         request_config: Optional[SendRequestConfig] = None,
     ) -> SendMessageResponse:
+        """Send one or more messages using the Solapi API.
+
+        This method sends various types of messages (SMS, LMS, MMS, 알림톡, 친구톡, RCS, etc.) to recipients.
+        It supports sending a single message or multiple messages in one request (대량 발송).
+
+        Args:
+            messages: A single Message object or a list of Message objects to send.
+                      Each Message object contains recipient (수신번호), sender (발신번호), content (내용), 
+                      and other message details.
+            request_config: Optional configuration for the send request.
+                           Can include app_id, allow_duplicates (중복 수신번호 허용), 
+                           scheduled_date (예약 발송), and other settings.
+
+        Returns:
+            SendMessageResponse: The response from the API containing message status, group info,
+                               and other details about the sent messages.
+
+        Raises:
+            TypeError: If messages parameter is not a Message object or list of Message objects.
+            ValueError: If no valid messages are provided.
+            MessageNotReceivedError: If all messages failed to be registered.
+        """
         payload = []
         if isinstance(messages, Message):
             payload.append(messages)
@@ -99,6 +134,22 @@ def send(
     def upload_file(
         self, file_path: str, upload_type: FileTypeEnum = FileTypeEnum.MMS
     ) -> FileUploadResponse:
+        """Upload a file to the Solapi storage service.
+
+        This method uploads a file (such as an image) to be used in MMS (사진 문자) or other message types.
+        The file is encoded in base64 before being sent to the API.
+
+        Args:
+            file_path: The path to the file to be uploaded (파일 경로).
+            upload_type: The type of file being uploaded, defaults to MMS (사진 문자용).
+                        Other possible values are defined in FileTypeEnum.
+
+        Returns:
+            FileUploadResponse: The response from the API containing the file ID (파일 ID) and other details.
+
+        Raises:
+            FileNotFoundError: If the specified file path does not exist.
+        """
         path = Path(file_path)
         with open(path, "rb") as image_file:
             encoded_string = base64.b64encode(image_file.read())
@@ -118,6 +169,20 @@ def upload_file(
         return FileUploadResponse.model_validate(response)
 
     def get_groups(self, query: Optional[GetGroupsRequest] = None) -> GetGroupsResponse:
+        """Retrieve message groups (메시지 그룹) from the Solapi API.
+
+        This method fetches message groups based on the provided query parameters.
+        If no query is provided, it returns all message groups.
+        메시지 그룹은 대량 발송 시 생성되는 메시지들의 묶음입니다.
+
+        Args:
+            query: Optional query parameters to filter the groups.
+                  Can include group_id (그룹 ID), criteria, cond, value, and other filters.
+
+        Returns:
+            GetGroupsResponse: The response from the API containing the list of message groups
+                             and other metadata.
+        """
         request = GetGroupsFinalizeRequest()
         if query is not None:
             request = request.model_copy(update=query.model_dump(exclude_unset=True))
@@ -140,6 +205,17 @@ def get_groups(self, query: Optional[GetGroupsRequest] = None) -> GetGroupsRespo
         return GetGroupsResponse.model_validate(response)
 
     def get_group(self, group_id: str) -> GroupMessageResponse:
+        """Retrieve a specific message group (메시지 그룹) by its ID.
+
+        This method fetches detailed information about a single message group.
+        특정 그룹 ID로 메시지 그룹 정보를 조회합니다.
+
+        Args:
+            group_id: The unique identifier (그룹 ID) of the message group to retrieve.
+
+        Returns:
+            GroupMessageResponse: The response from the API containing the message group details.
+        """
         response = default_fetcher(
             self.auth_info,
             request={
@@ -150,6 +226,18 @@ def get_group(self, group_id: str) -> GroupMessageResponse:
         return GroupMessageResponse.model_validate(response)
 
     def get_group_messages(self, group_id: str) -> GetGroupMessagesResponse:
+        """Retrieve all messages within a specific group (그룹 내 메시지 목록 조회).
+
+        This method fetches all messages that belong to the specified message group.
+        특정 메시지 그룹에 속한 모든 메시지를 조회합니다.
+
+        Args:
+            group_id: The unique identifier (그룹 ID) of the message group whose messages should be retrieved.
+
+        Returns:
+            GetGroupMessagesResponse: The response from the API containing the list of messages
+                                    in the group and other metadata.
+        """
         response = default_fetcher(
             self.auth_info,
             request={
@@ -162,6 +250,21 @@ def get_group_messages(self, group_id: str) -> GetGroupMessagesResponse:
     def get_messages(
         self, query: Optional[GetMessagesRequest] = None
     ) -> GetMessagesResponse:
+        """Retrieve messages based on query parameters (메시지 목록 조회).
+
+        This method fetches messages that match the specified query parameters.
+        If no query is provided, it returns messages based on default parameters.
+        조건에 맞는 메시지 목록을 조회합니다.
+
+        Args:
+            query: Optional query parameters to filter the messages.
+                  Can include criteria for message status (상태), date range (기간), 
+                  recipient (수신번호), sender (발신번호), etc.
+
+        Returns:
+            GetMessagesResponse: The response from the API containing the list of messages
+                               and other metadata.
+        """
         request = GetMessagesRequest()
         if query is not None:
             request = request.model_copy(update=query.model_dump(exclude_unset=True))
@@ -182,6 +285,15 @@ def get_messages(
         return GetMessagesResponse.model_validate(response)
 
     def get_balance(self) -> GetBalanceResponse:
+        """Retrieve the account balance information (잔액 조회).
+
+        This method fetches the current balance and point information for the account.
+        계정의 현재 잔액과 포인트 정보를 조회합니다.
+
+        Returns:
+            GetBalanceResponse: The response from the API containing the account balance details
+                               including cash balance (잔액) and point balance (포인트).
+        """
         response = default_fetcher(
             self.auth_info,
             request={