feat(client): add stemming dictionary support

- add new `stemming` module with dictionary management functionality
- add `StemmingDictionaries` class for crud operations on dictionaries
- add corresponding types and tests for stemming operations
- update `Client` class to expose stemming functionality

Author: tharropoulos

setup.cfg

@@ -20,11 +20,12 @@ max-complexity = 6
 
 # # Excluding some directories:
 exclude = .git,__pycache__,venv,.eggs,*.egg
-ignore = Q000, WPS602, WPS432, WPS305, WPS221, WPS230, WPS234, WPS433, WPS440, W503, WPS331, WPS306, WPS237, WPS202, RST301, RST306, WPS214, WPS235, WPS226, WPS337, WPS320, F821, WPS201
+ignore = Q000, WPS602, WPS432, WPS305, WPS221, WPS230, WPS234, WPS433, WPS440, W503, WPS331, WPS306, WPS237, WPS202, RST301, RST306, WPS214, WPS235, WPS226, WPS337, WPS320, F821, WPS201, E704, D102
 per-file-ignores = 
   tests/*.py: S101, WPS226, WPS118, WPS202, WPS204, WPS218, WPS211, WPS604, WPS431, WPS210, WPS201, WPS437
   src/typesense/types/*.py: B950, WPS215, WPS111, WPS462, WPS322, WPS428, WPS114, WPS110, WPS202 
-  src/typesense/documents.py: WPS320, E704, D102, WPS428, WPS220
+  src/typesense/documents.py: WPS320, WPS428, WPS220
+  src/typesense/stemming_dictionaries.py: WPS320, WPS428, WPS220
   src/typesense/api_call.py: WPS110, WPS211
   src/typesense/request_handler.py: WPS110, WPS211
 

src/typesense/client.py

@@ -45,6 +45,7 @@
 from typesense.keys import Keys
 from typesense.multi_search import MultiSearch
 from typesense.operations import Operations
+from typesense.stemming import Stemming
 from typesense.stopwords import Stopwords
 
 TDoc = typing.TypeVar("TDoc", bound=DocumentSchema)
@@ -56,7 +57,7 @@ class Client:
 
     This class serves as the entry point for all Typesense operations. It initializes
     and provides access to various components of the Typesense SDK, such as collections,
-    multi-search, keys, aliases, analytics, operations, debug, stopwords,
+    multi-search, keys, aliases, analytics, stemming, operations, debug, stopwords,
     and conversation models.
 
     Attributes:
@@ -67,6 +68,7 @@ class Client:
         keys (Keys): Instance for managing API keys.
         aliases (Aliases): Instance for managing collection aliases.
         analytics (Analytics): Instance for analytics operations.
+        stemming (Stemming): Instance for stemming dictionary operations.
         operations (Operations): Instance for various Typesense operations.
         debug (Debug): Instance for debug operations.
         stopwords (Stopwords): Instance for managing stopwords.
@@ -96,6 +98,7 @@ def __init__(self, config_dict: ConfigDict) -> None:
         self.keys = Keys(self.api_call)
         self.aliases = Aliases(self.api_call)
         self.analytics = Analytics(self.api_call)
+        self.stemming = Stemming(self.api_call)
         self.operations = Operations(self.api_call)
         self.debug = Debug(self.api_call)
         self.stopwords = Stopwords(self.api_call)

src/typesense/stemming.py

@@ -0,0 +1,50 @@
+"""
+Module for managing stemming dictionaries in Typesense.
+
+This module provides a class for managing stemming dictionaries in Typesense,
+including creating, updating, and retrieving them.
+
+Classes:
+    - Stemming: Handles operations related to stemming dictionaries.
+
+Attributes:
+    - StemmingDictionaries: The StemmingDictionaries object for managing stemming dictionaries.
+
+Methods:
+    - __init__: Initializes the Stemming object.
+
+The Stemming class interacts with the Typesense API to manage stemming dictionary operations.
+It provides access to the StemmingDictionaries object for managing stemming dictionaries.
+
+For more information on stemming dictionaries, refer to the Stemming
+[documentation](https://typesense.org/docs/28.0/api/stemming.html)
+
+This module uses type hinting and is compatible with Python 3.11+ as well as earlier
+versions through the use of the typing_extensions library.
+"""
+
+from typesense.api_call import ApiCall
+from typesense.stemming_dictionaries import StemmingDictionaries
+
+
+class Stemming(object):
+    """
+    Class for managing stemming dictionaries in Typesense.
+
+    This class provides methods to interact with stemming dictionaries, including
+    creating, updating, and retrieving them.
+
+    Attributes:
+        dictionaries (StemmingDictionaries): The StemmingDictionaries object for managing
+            stemming dictionaries.
+    """
+
+    def __init__(self, api_call: ApiCall):
+        """
+        Initialize the Stemming object.
+
+        Args:
+            api_call (ApiCall): The API call object for making requests.
+        """
+        self.api_call = api_call
+        self.dictionaries = StemmingDictionaries(api_call)

src/typesense/stemming_dictionaries.py

@@ -0,0 +1,187 @@
+"""
+Module for interacting with the stemming dictionaries endpoint of the Typesense API.
+
+This module provides a class for managing stemming dictionaries in Typesense, including creating
+and updating them.
+
+Classes:
+    - StemmingDictionaries: Handles operations related to stemming dictionaries.
+
+Methods:
+    - __init__: Initializes the StemmingDictionaries object.
+    - __getitem__: Retrieves or creates a StemmingDictionary object for a given dictionary_id.
+    - upsert: Creates or updates a stemming dictionary.
+    - _upsert_list: Creates or updates a list of stemming dictionaries.
+    - _dump_to_jsonl: Dumps a list of StemmingDictionaryCreateSchema objects to a JSONL string.
+    - _parse_response: Parses the response from the upsert operation.
+    - _upsert_raw: Performs the raw upsert operation.
+    - _endpoint_path: Constructs the API endpoint path for this specific stemming dictionary.
+
+The StemmingDictionaries class interacts with the Typesense API to manage stemming dictionary
+operations.
+It provides methods to create, update, and retrieve stemming dictionaries, as well as
+access individual StemmingDictionary objects.
+
+For more information on stemming dictionaries,
+refer to the Stemming [documentation](https://typesense.org/docs/28.0/api/stemming.html)
+"""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+import json
+
+from typesense.api_call import ApiCall
+from typesense.stemming_dictionary import StemmingDictionary
+from typesense.types.stemming import (
+    StemmingDictionariesRetrieveSchema,
+    StemmingDictionaryCreateSchema,
+)
+
+
+class StemmingDictionaries:
+    """
+    Class for managing stemming dictionaries in Typesense.
+
+    This class provides methods to interact with stemming dictionaries, including
+    creating, updating, and retrieving them.
+
+    Attributes:
+        api_call (ApiCall): The API call object for making requests.
+        stemming_dictionaries (Dict[str, StemmingDictionary]): A dictionary of
+            StemmingDictionary objects.
+    """
+
+    resource_path: typing.Final[str] = "/stemming/dictionaries"
+
+    def __init__(self, api_call: ApiCall):
+        """
+        Initialize the StemmingDictionaries object.
+
+        Args:
+            api_call (ApiCall): The API call object for making requests.
+        """
+        self.api_call = api_call
+        self.stemming_dictionaries: typing.Dict[str, StemmingDictionary] = {}
+
+    def __getitem__(self, dictionary_id: str) -> StemmingDictionary:
+        """
+        Get or create an StemmingDictionary object for a given rule_id.
+
+        Args:
+            rule_id (str): The ID of the analytics rule.
+
+        Returns:
+            StemmingDictionary: The StemmingDictionary object for the given ID.
+        """
+        if not self.stemming_dictionaries.get(dictionary_id):
+            self.stemming_dictionaries[dictionary_id] = StemmingDictionary(
+                self.api_call,
+                dictionary_id,
+            )
+        return self.stemming_dictionaries[dictionary_id]
+
+    def retrieve(self) -> StemmingDictionariesRetrieveSchema:
+        """
+        Retrieve the list of stemming dictionaries.
+
+        Returns:
+            StemmingDictionariesRetrieveSchema: The list of stemming dictionaries.
+        """
+        response: StemmingDictionariesRetrieveSchema = self.api_call.get(
+            self._endpoint_path(),
+            entity_type=StemmingDictionariesRetrieveSchema,
+        )
+        return response
+
+    @typing.overload
+    def upsert(
+        self,
+        dictionary_id: str,
+        word_root_combinations: typing.Union[str, bytes],
+    ) -> str: ...
+
+    @typing.overload
+    def upsert(
+        self,
+        dictionary_id: str,
+        word_root_combinations: typing.List[StemmingDictionaryCreateSchema],
+    ) -> typing.List[StemmingDictionaryCreateSchema]: ...
+
+    def upsert(
+        self,
+        dictionary_id: str,
+        word_root_combinations: typing.Union[
+            typing.List[StemmingDictionaryCreateSchema],
+            str,
+            bytes,
+        ],
+    ) -> typing.Union[str, typing.List[StemmingDictionaryCreateSchema]]:
+        if isinstance(word_root_combinations, (str, bytes)):
+            return self._upsert_raw(dictionary_id, word_root_combinations)
+
+        return self._upsert_list(dictionary_id, word_root_combinations)
+
+    def _upsert_list(
+        self,
+        dictionary_id: str,
+        word_root_combinations: typing.List[StemmingDictionaryCreateSchema],
+    ) -> typing.List[StemmingDictionaryCreateSchema]:
+        word_combos_in_jsonl = self._dump_to_jsonl(word_root_combinations)
+        response = self._upsert_raw(dictionary_id, word_combos_in_jsonl)
+        return self._parse_response(response)
+
+    def _dump_to_jsonl(
+        self,
+        word_root_combinations: typing.List[StemmingDictionaryCreateSchema],
+    ) -> str:
+        word_root_strs = [json.dumps(combo) for combo in word_root_combinations]
+
+        return "\n".join(word_root_strs)
+
+    def _parse_response(
+        self,
+        response: str,
+    ) -> typing.List[StemmingDictionaryCreateSchema]:
+        object_list: typing.List[StemmingDictionaryCreateSchema] = []
+
+        for line in response.split("\n"):
+            try:
+                decoded = json.loads(line)
+            except json.JSONDecodeError:
+                raise ValueError(f"Failed to parse JSON from response: {line}")
+            object_list.append(decoded)
+        return object_list
+
+    def _upsert_raw(
+        self,
+        dictionary_id: str,
+        word_root_combinations: typing.Union[bytes, str],
+    ) -> str:
+        response: str = self.api_call.post(
+            self._endpoint_path("import"),
+            body=word_root_combinations,
+            as_json=False,
+            entity_type=str,
+            params={"id": dictionary_id},
+        )
+        return response
+
+    def _endpoint_path(self, action: typing.Union[str, None] = None) -> str:
+        """
+        Construct the API endpoint path for this specific stemming dictionary.
+
+        Args:
+            action (str, optional): The action to perform on the stemming dictionary.
+                Defaults to None.
+
+        Returns:
+            str: The constructed endpoint path.
+        """
+        if action:
+            return f"{StemmingDictionaries.resource_path}/{action}"
+        return StemmingDictionaries.resource_path

src/typesense/stemming_dictionary.py

@@ -0,0 +1,75 @@
+"""
+Module for managing individual stemming dictionaries in Typesense.
+
+This module provides a class for managing individual stemming dictionaries in Typesense,
+including retrieving them.
+
+Classes:
+    - StemmingDictionary: Handles operations related to individual stemming dictionaries.
+
+Methods:
+    - __init__: Initializes the StemmingDictionary object.
+    - retrieve: Retrieves this specific stemming dictionary.
+
+The StemmingDictionary class interacts with the Typesense API to manage operations on a
+specific stemming dictionary. It provides methods to retrieve the dictionary details.
+
+For more information on stemming dictionaries, refer to the Stemming
+[documentation](https://typesense.org/docs/28.0/api/stemming.html)
+
+This module uses type hinting and is compatible with Python 3.11+ as well as earlier
+versions through the use of the typing_extensions library.
+"""
+
+from typesense.api_call import ApiCall
+from typesense.types.stemming import StemmingDictionarySchema
+
+
+class StemmingDictionary:
+    """
+    Class for managing individual stemming dictionaries in Typesense.
+
+    This class provides methods to interact with a specific stemming dictionary,
+    including retrieving it.
+
+    Attributes:
+        api_call (ApiCall): The API call object for making requests.
+        dict_id (str): The ID of the stemming dictionary.
+    """
+
+    def __init__(self, api_call: ApiCall, dict_id: str):
+        """
+        Initialize the StemmingDictionary object.
+
+        Args:
+            api_call (ApiCall): The API call object for making requests.
+            dict_id (str): The ID of the stemming dictionary.
+        """
+        self.api_call = api_call
+        self.dict_id = dict_id
+
+    def retrieve(self) -> StemmingDictionarySchema:
+        """
+        Retrieve this specific stemming dictionary.
+
+        Returns:
+            StemmingDictionarySchema: The schema containing the stemming dictionary details.
+        """
+        response: StemmingDictionarySchema = self.api_call.get(
+            self._endpoint_path,
+            entity_type=StemmingDictionarySchema,
+            as_json=True,
+        )
+        return response
+
+    @property
+    def _endpoint_path(self) -> str:
+        """
+        Construct the API endpoint path for this specific analytics rule.
+
+        Returns:
+            str: The constructed endpoint path.
+        """
+        from typesense.stemming_dictionaries import StemmingDictionaries
+
+        return "/".join([StemmingDictionaries.resource_path, self.dict_id])