Improving docstrings

Author: sanders41

.flake8

@@ -1,3 +1,2 @@
 [flake8]
-ignore = E203, E231, E501
-max-line-length = 100
+ignore = E203, E231, E501, D100, D101, D102, D103, D104, D105, D106, D107, D401

.pre-commit-config.yaml

@@ -28,4 +28,4 @@ repos:
     hooks:
     - id: flake8
       additional_dependencies: [flake8-print]
-      args: ["--max-line-length=100", "--ignore=E203,E231,E501"]
+      args: ["--ignore=E203,E231,E501,D100,D101,D102,D103,D104,D105,D106,D107,D401"]

async_search_client/_http_requests.py

@@ -9,10 +9,14 @@
     Response,
 )
 
-from async_search_client.errors import MeiliSearchApiError, MeiliSearchCommunicationError
+from async_search_client.errors import (
+    MeiliSearchApiError,
+    MeiliSearchCommunicationError,
+    MeiliSearchTimeoutError,
+)
 
 
-class HttpRequests:
+class _HttpRequests:
     def __init__(self, http_client: AsyncClient) -> None:
         self.http_client = http_client
 
@@ -36,7 +40,7 @@ async def _send_request(
         except ConnectError as err:
             raise MeiliSearchCommunicationError(str(err)) from err
         except ConnectTimeout as err:
-            raise MeiliSearchCommunicationError(str(err)) from err
+            raise MeiliSearchTimeoutError(str(err)) from err
         except HTTPError as err:
             raise MeiliSearchApiError(str(err), response) from err
 

async_search_client/client.py

@@ -5,18 +5,28 @@
 
 from httpx import AsyncClient
 
-from async_search_client._http_requests import HttpRequests
+from async_search_client._http_requests import _HttpRequests
 from async_search_client.errors import MeiliSearchApiError
 from async_search_client.index import Index
 from async_search_client.models import ClientStats, DumpInfo, Health, IndexInfo, Keys, Version
 
 
 class Client:
+    """The client to connect to the MeiliSearchApi."""
+
     def __init__(self, url: str, api_key: str = None, timeout: int = 5) -> None:
+        """Class initializer.
+
+        Args:
+            url: The url to the MeiliSearch API (ex: http://localhost:7700)
+            api_key: The optional API key for MeiliSearch. Defaults to None.
+            timeout: The amount of time in seconds that the client will wait for a response before
+                timing out. Defaults to 5.
+        """
         self._http_client = AsyncClient(
             base_url=url, timeout=timeout, headers=self._set_headers(api_key)
         )
-        self._http_requests = HttpRequests(self._http_client)
+        self._http_requests = _HttpRequests(self._http_client)
 
     async def __aenter__(self) -> Client:
         return self
@@ -30,20 +40,58 @@ async def __aexit__(
         await self.aclose()
 
     async def aclose(self) -> None:
-        """Closes the client. This only needs to be used if the client was not created with a
-        context manager
-        """
+        """Closes the client.
 
+        This only needs to be used if the client was not created with context manager.
+        """
         await self._http_client.aclose()
 
     async def create_dump(self) -> DumpInfo:
+        """Trigger the creation of a MeiliSearch dump.
+
+        Returns:
+            Information about the dump.
+            https://docs.meilisearch.com/reference/api/dump.html#create-a-dump
+
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         response = await self._http_requests.post("dumps")
         return DumpInfo(**response.json())
 
     async def create_index(self, uid: str, primary_key: Optional[str] = None) -> Index:
+        """Creates a new index.
+
+        Args:
+            uid: The index's unique identifier.
+            primary_key: The primary key of the documents. Defaults to None.
+
+        Returns:
+            An instance of Index containing the information of the newly created index.
+
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         return await Index.create(self._http_client, uid, primary_key)
 
     async def delete_index_if_exists(self, uid: str) -> bool:
+        """Deletes an index if it already exists.
+
+        Args:
+            uid: The index's unique identifier.
+
+        Returns:
+            True if an index was deleted for False if not.
+
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         try:
             url = f"indexes/{uid}"
             await self._http_requests.delete(url)
@@ -54,6 +102,16 @@ async def delete_index_if_exists(self, uid: str) -> bool:
             return False
 
     async def get_indexes(self) -> Optional[list[Index]]:
+        """Get all indexes.
+
+        Returns:
+            A list of all indexes.
+
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         response = await self._http_requests.get("indexes")
 
         if not response.json():
@@ -71,25 +129,88 @@ async def get_indexes(self) -> Optional[list[Index]]:
         ]
 
     async def get_index(self, uid: str) -> Index:
+        """Gets a single index based on the uid of the index.
+
+        Args:
+            uid: The index's unique identifier.
+
+        Returns:
+            An Index instance containing the information of the fetched index.
+
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         return await Index(self._http_client, uid).fetch_info()
 
     def index(self, uid: str) -> Index:
-        """Create a local reference to an index identified by UID, without doing an HTTP call.
+        """Create a local reference to an index identified by UID, without making an HTTP call.
+
         Because no network call is made this method is not awaitable.
-        """
 
+        Args:
+            uid: The index's unique identifier.
+
+        Returns:
+            An Index instance.
+
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         return Index(self._http_client, uid=uid)
 
     async def get_all_stats(self) -> ClientStats:
+        """Get stats for all indexes.
+
+        Returns:
+            Information about database size and all indexes.
+            https://docs.meilisearch.com/reference/api/stats.html
+
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         response = await self._http_requests.get("stats")
         return ClientStats(**response.json())
 
     async def get_dump_status(self, uid: str) -> DumpInfo:
+        """Retrieve the status of a MeiliSearch dump creation.
+
+        Args:
+            uid: The index's unique identifier.
+
+        Returns:
+            Information about the dump status.
+            https://docs.meilisearch.com/reference/api/dump.html#get-dump-status
+
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         url = f"dumps/{uid}/status"
         response = await self._http_requests.get(url)
         return DumpInfo(**response.json())
 
     async def get_or_create_index(self, uid: str, primary_key: Optional[str] = None) -> Index:
+        """Get an index, or create it if it doesn't exist.
+
+        Args:
+            uid: The index's unique identifier.
+            primary_key: The primary key of the documents. Defaults to None.
+
+        Returns:
+            An instance of Index containing the information of the retrieved or newly created index.
+
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.MeiliSearchTimeoutError: If the connection times out.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         try:
             index_instance = await self.get_index(uid)
         except MeiliSearchApiError as err:
@@ -99,10 +220,34 @@ async def get_or_create_index(self, uid: str, primary_key: Optional[str] = None)
         return index_instance
 
     async def get_keys(self) -> Keys:
+        """Gets the MeiliSearch public and private keys.
+
+        Returns:
+            The public and private keys.
+            https://docs.meilisearch.com/reference/api/keys.html#get-keys
+
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         response = await self._http_requests.get("keys")
         return Keys(**response.json())
 
     async def get_raw_index(self, uid: str) -> Optional[IndexInfo]:
+        """Gets the index and returns all the index information rather than an Index instance.
+
+        Args:
+            uid: The index's unique identifier.
+
+        Returns:
+            Index information rather than an Index instance.
+
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         response = await self._http_client.get(f"indexes/{uid}")
 
         if response.status_code == 404:
@@ -111,6 +256,18 @@ async def get_raw_index(self, uid: str) -> Optional[IndexInfo]:
         return IndexInfo(**response.json())
 
     async def get_raw_indexes(self) -> Optional[list[IndexInfo]]:
+        """Gets all the indexes.
+
+        Returns all the index information rather than an Index instance.
+
+        Returns:
+            A list of the Index information rather than an Index instances.
+
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         response = await self._http_requests.get("indexes")
 
         if not response.json():
@@ -119,14 +276,30 @@ async def get_raw_indexes(self) -> Optional[list[IndexInfo]]:
         return [IndexInfo(**x) for x in response.json()]
 
     async def get_version(self) -> Version:
-        """Get version MeiliSearch that is running"""
+        """Get the MeiliSearch version.
+
+        Returns:
+            Information about the version of MeiliSearch.
 
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         response = await self._http_requests.get("version")
         return Version(**response.json())
 
     async def health(self) -> Health:
-        """Get health of the MeiliSearch server"""
+        """Get health of the MeiliSearch server.
+
+        Returns:
+            The status of the MeiliSearch server.
 
+        Raises:
+            MeilisearchCommunicationError: If there was an error communicating with the server.
+            MeilisearchApiError: If the MeiliSearch API returned an error.
+            MeiliSearchTimeoutError: If the connection times out.
+        """
         response = await self._http_requests.get("health")
         return Health(**response.json())
 

async_search_client/errors.py

@@ -2,7 +2,7 @@
 
 
 class MeiliSearchError(Exception):
-    """Generic class for MeiliSearch error handling"""
+    """Generic class for MeiliSearch error handling."""
 
     def __init__(self, message: str) -> None:
         self.message = message
@@ -13,7 +13,7 @@ def __str__(self) -> str:
 
 
 class MeiliSearchApiError(MeiliSearchError):
-    """Error sent by MeiliSearch API"""
+    """Error sent by MeiliSearch API."""
 
     def __init__(self, error: str, response: Response) -> None:
         self.status_code = response.status_code
@@ -33,14 +33,14 @@ def __str__(self) -> str:
 
 
 class MeiliSearchCommunicationError(MeiliSearchError):
-    """Error when connecting to MeiliSearch"""
+    """Error when connecting to MeiliSearch."""
 
     def __str__(self) -> str:
         return f"MeiliSearchCommunicationError, {self.message}"
 
 
 class MeiliSearchTimeoutError(MeiliSearchError):
-    """Error when MeiliSearch operation takes longer than expected"""
+    """Error when MeiliSearch operation takes longer than expected."""
 
     def __str__(self) -> str:
         return f"MeiliSearchTimeoutError, {self.message}"