refactor(collection): format collection classes based on linting rules

Author: tharropoulos

src/typesense/collection.py

@@ -1,4 +1,22 @@
-from __future__ import annotations
+"""
+This module provides functionality for managing individual collections in the Typesense API.
+
+It contains the Collection class, which allows for retrieving, updating, and deleting
+collections, as well as managing documents, overrides, and synonyms within a collection.
+
+Classes:
+    Collection: Manages operations on a single collection in the Typesense API.
+
+Dependencies:
+    - typesense.api_call: Provides the ApiCall class for making API requests.
+    - typesense.documents: Provides the Documents class for managing documents.
+    - typesense.overrides: Provides the Overrides class for managing overrides.
+    - typesense.synonyms: Provides the Synonyms class for managing synonyms.
+    - typesense.types.collection: Provides CollectionSchema and CollectionUpdateSchema types.
+    - typesense.types.document: Provides DocumentSchema type.
+
+Note: This module uses conditional imports to support both Python 3.11+ and earlier versions.
+"""
 
 import sys
 
@@ -10,48 +28,108 @@
     import typing_extensions as typing
 
 from typesense.api_call import ApiCall
+from typesense.documents import Documents
+from typesense.overrides import Overrides
+from typesense.synonyms import Synonyms
 from typesense.types.document import DocumentSchema
 
-from .documents import Documents
-from .overrides import Overrides
-from .synonyms import Synonyms
-
 TDoc = typing.TypeVar("TDoc", bound=DocumentSchema)
 
 
 class Collection(typing.Generic[TDoc]):
+    """
+    Manages operations on a single collection in the Typesense API.
+
+    This class provides methods to retrieve, update, and delete a collection,
+    as well as access to documents, overrides, and synonyms within the collection.
+    It is generic over the document type TDoc, which should be a subtype of DocumentSchema.
+
+    Attributes:
+        name (str): The name of the collection.
+        api_call (ApiCall): The ApiCall instance for making API requests.
+        documents (Documents[TDoc]): Instance for managing documents in this collection.
+        overrides (Overrides): Instance for managing overrides in this collection.
+        synonyms (Synonyms): Instance for managing synonyms in this collection.
+    """
+
     def __init__(self, api_call: ApiCall, name: str):
+        """
+        Initialize the Collection instance.
+
+        Args:
+            api_call (ApiCall): The ApiCall instance for making API requests.
+            name (str): The name of the collection.
+        """
         self.name = name
         self.api_call = api_call
-        self.documents = Documents[TDoc](api_call, name)
+        self.documents: Documents[TDoc] = Documents(api_call, name)
         self.overrides = Overrides(api_call, name)
         self.synonyms = Synonyms(api_call, name)
 
-    @property
-    def _endpoint_path(self) -> str:
-        from typesense.collections import Collections
-
-        return f"{Collections.RESOURCE_PATH}/{self.name}"
-
     def retrieve(self) -> CollectionSchema:
+        """
+        Retrieve the schema of this collection from Typesense.
+
+        Returns:
+            CollectionSchema: The schema of the collection.
+        """
         response: CollectionSchema = self.api_call.get(
-            endpoint=self._endpoint_path, entity_type=CollectionSchema, as_json=True
+            endpoint=self._endpoint_path,
+            entity_type=CollectionSchema,
+            as_json=True,
         )
         return response
 
     def update(self, schema_change: CollectionUpdateSchema) -> CollectionUpdateSchema:
+        """
+        Update the schema of this collection in Typesense.
+
+        Args:
+            schema_change (CollectionUpdateSchema):
+                The changes to apply to the collection schema.
+
+        Returns:
+            CollectionUpdateSchema: The updated schema of the collection.
+        """
         response: CollectionUpdateSchema = self.api_call.patch(
             endpoint=self._endpoint_path,
             body=schema_change,
             entity_type=CollectionUpdateSchema,
         )
         return response
 
-    # There's currently no parameters passed to Collection deletions, but ensuring future compatibility
     def delete(
         self,
-        params: typing.Union[typing.Dict[str, typing.Union[str, bool]], None] = None,
+        delete_parameters: typing.Union[
+            typing.Dict[str, typing.Union[str, bool]],
+            None,
+        ] = None,
     ) -> CollectionSchema:
-        return self.api_call.delete(
-            self._endpoint_path, entity_type=CollectionSchema, params=params
+        """
+        Delete this collection from Typesense.
+
+        Args:
+            delete_parameters (Union[Dict[str, Union[str, bool]], None], optional):
+                Additional parameters for the delete operation. Defaults to None.
+
+        Returns:
+            CollectionSchema: The schema of the deleted collection.
+        """
+        response: CollectionSchema = self.api_call.delete(
+            self._endpoint_path,
+            entity_type=CollectionSchema,
+            params=delete_parameters,
         )
+        return response
+
+    @property
+    def _endpoint_path(self) -> str:
+        """
+        Get the API endpoint path for this collection.
+
+        Returns:
+            str: The full endpoint path for the collection.
+        """
+        from typesense.collections import Collections
+
+        return "/".join([Collections.resource_path, self.name])

src/typesense/collections.py

@@ -1,49 +1,135 @@
-from __future__ import annotations
+"""
+This module provides functionality for managing collections in the Typesense API.
+
+It contains the Collections class, which allows for creating, retrieving, and
+accessing individual collections.
+
+Classes:
+    Collections: Manages collections in the Typesense API.
+
+Dependencies:
+    - typesense.api_call: Provides the ApiCall class for making API requests.
+    - typesense.collection: Provides the Collection class for individual collection operations.
+    - typesense.types.collection: Provides CollectionCreateSchema and CollectionSchema types.
+    - typesense.types.document: Provides DocumentSchema type.
+
+Note: This module uses conditional imports to support both Python 3.11+ and earlier versions.
+"""
 
 import sys
-from email.policy import default
-from typing import TYPE_CHECKING
 
 if sys.version_info >= (3, 11):
     import typing
 else:
     import typing_extensions as typing
 
 from typesense.api_call import ApiCall
+from typesense.collection import Collection
 from typesense.types.collection import CollectionCreateSchema, CollectionSchema
 from typesense.types.document import DocumentSchema
 
-from .collection import Collection
-
 TDoc = typing.TypeVar("TDoc", bound=DocumentSchema)
 
 
 class Collections(typing.Generic[TDoc]):
-    RESOURCE_PATH = "/collections"
+    """
+    Manages collections in the Typesense API.
+
+    This class provides methods to create, retrieve, and access individual collections.
+    It is generic over the document type TDoc, which should be a subtype of DocumentSchema.
+
+    Attributes:
+        resource_path (str): The API endpoint path for collections operations.
+        api_call (ApiCall): The ApiCall instance for making API requests.
+        collections (Dict[str, Collection[TDoc]]):
+           A dictionary of Collection instances, keyed by collection name.
+    """
+
+    resource_path: typing.Final[str] = "/collections"
 
     def __init__(self, api_call: ApiCall):
+        """
+        Initialize the Collections instance.
+
+        Args:
+            api_call (ApiCall): The ApiCall instance for making API requests.
+        """
         self.api_call = api_call
         self.collections: typing.Dict[str, Collection[TDoc]] = {}
 
     def __getitem__(self, collection_name: str) -> Collection[TDoc]:
+        """
+        Get or create a Collection instance for a given collection name.
+
+        This method allows accessing collections using dictionary-like syntax.
+        If the Collection instance doesn't exist, it creates a new one.
+
+        Args:
+            collection_name (str): The name of the collection to access.
+
+        Returns:
+            Collection[TDoc]: The Collection instance for the specified collection name.
+
+        Example:
+            >>> collections = Collections(api_call)
+            >>> fruits_collection = collections['fruits']
+        """
         if not self.collections.get(collection_name):
             self.collections[collection_name] = Collection(
-                self.api_call, collection_name
+                self.api_call,
+                collection_name,
             )
         return self.collections[collection_name]
 
     def create(self, schema: CollectionCreateSchema) -> CollectionSchema:
+        """
+        Create a new collection in Typesense.
+
+        Args:
+            schema (CollectionCreateSchema):
+               The schema defining the structure of the new collection.
+
+        Returns:
+            CollectionSchema:
+                The schema of the created collection, as returned by the API.
+
+        Example:
+            >>> collections = Collections(api_call)
+            >>> schema = {
+            ...     "name": "companies",
+            ...     "fields": [
+            ...         {"name": "company_name", "type": "string" },
+            ...         {"name": "num_employees", "type": "int32" },
+            ...         {"name": "country", "type": "string", "facet": True }
+            ...     ],
+            ...     "default_sorting_field": "num_employees"
+            ... }
+            >>> created_schema = collections.create(schema)
+        """
         call: CollectionSchema = self.api_call.post(
-            endpoint=Collections.RESOURCE_PATH,
+            endpoint=Collections.resource_path,
             entity_type=CollectionSchema,
             as_json=True,
             body=schema,
         )
         return call
 
     def retrieve(self) -> typing.List[CollectionSchema]:
+        """
+        Retrieve all collections from Typesense.
+
+        Returns:
+            List[CollectionSchema]:
+               A list of schemas for all collections in the Typesense instance.
+
+        Example:
+            >>> collections = Collections(api_call)
+            >>> all_collections = collections.retrieve()
+            >>> for collection in all_collections:
+            ...     print(collection['name'])
+        """
         call: typing.List[CollectionSchema] = self.api_call.get(
-            endpoint=Collections.RESOURCE_PATH,
+            endpoint=Collections.resource_path,
             as_json=True,
             entity_type=typing.List[CollectionSchema],
         )

src/typesense/document.py

@@ -127,7 +127,7 @@ def _endpoint_path(self) -> str:
 
         return "/".join(
             [
-                Collections.RESOURCE_PATH,
+                Collections.resource_path,
                 self.collection_name,
                 Documents.resource_path,
                 self.document_id,

src/typesense/documents.py

@@ -396,7 +396,7 @@ def _endpoint_path(self, action: typing.Union[str, None] = None) -> str:
         action = action or ""
         return "/".join(
             [
-                Collections.RESOURCE_PATH,
+                Collections.resource_path,
                 self.collection_name,
                 self.resource_path,
                 action,

src/typesense/override.py

@@ -95,7 +95,7 @@ def _endpoint_path(self) -> str:
 
         return "/".join(
             [
-                Collections.RESOURCE_PATH,
+                Collections.resource_path,
                 self.collection_name,
                 Overrides.resource_path,
                 self.override_id,

src/typesense/overrides.py

@@ -141,7 +141,7 @@ def _endpoint_path(self, override_id: typing.Union[str, None] = None) -> str:
 
         return "/".join(
             [
-                Collections.RESOURCE_PATH,
+                Collections.resource_path,
                 self.collection_name,
                 Overrides.resource_path,
                 override_id,

src/typesense/synonym.py

@@ -89,7 +89,7 @@ def _endpoint_path(self) -> str:
 
         return "/".join(
             [
-                Collections.RESOURCE_PATH,
+                Collections.resource_path,
                 self.collection_name,
                 Synonyms.resource_path,
                 self.synonym_id,