add: analytics API

Author: harisarang

examples/analytics_operations.py

@@ -12,12 +12,12 @@
 
 # Drop pre-existing rule if any
 try:
-    client.analytics.rules['top_queries'].delete()
+    client.analyticsV1.rules['top_queries'].delete()
 except Exception as e:
     pass
 
 # Create a new rule
-create_response = client.analytics.rules.create({
+create_response = client.analyticsV1.rules.create({
     "name": "top_queries",
     "type": "popular_queries",
     "params": {
@@ -33,10 +33,10 @@
 print(create_response)
 
 # Try to fetch it back
-print(client.analytics.rules['top_queries'].retrieve())
+print(client.analyticsV1.rules['top_queries'].retrieve())
 
 # Update the rule
-update_response = client.analytics.rules.upsert('top_queries', {
+update_response = client.analyticsV1.rules.upsert('top_queries', {
     "name": "top_queries",
     "type": "popular_queries",
     "params": {
@@ -52,7 +52,7 @@
 print(update_response)
 
 # List all rules
-print(client.analytics.rules.retrieve())
+print(client.analyticsV1.rules.retrieve())
 
 # Delete the rule
-print(client.analytics.rules['top_queries'].delete())
+print(client.analyticsV1.rules['top_queries'].delete())

src/typesense/analytics.py

@@ -1,42 +1,24 @@
-"""
-This module provides functionality for managing analytics in Typesense.
+"""Client for Typesense Analytics module."""
 
-Classes:
-    - Analytics: Handles operations related to analytics, including access to analytics rules.
+import sys
 
-Methods:
-    - __init__: Initializes the Analytics object.
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
 
-The Analytics class serves as an entry point for analytics-related operations in Typesense,
-currently providing access to AnalyticsRules.
-
-For more information on analytics, refer to the Analytics & Query Suggestion
-[documentation](https://typesense.org/docs/27.0/api/analytics-query-suggestions.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.analytics_rules import AnalyticsRules
 from typesense.api_call import ApiCall
+from typesense.analytics_events import AnalyticsEvents
+from typesense.analytics_rules import AnalyticsRules
 
 
-class Analytics(object):
-    """
-    Class for managing analytics in Typesense.
+class Analytics:
+    """Client for v30 Analytics endpoints."""
 
-    This class provides access to analytics-related functionalities,
-    currently including operations on analytics rules.
+    def __init__(self, api_call: ApiCall) -> None:
+        self.api_call = api_call
+        self.rules = AnalyticsRules(api_call)
+        self.events = AnalyticsEvents(api_call)
 
-    Attributes:
-        rules (AnalyticsRules): An instance of AnalyticsRules for managing analytics rules.
-    """
 
-    def __init__(self, api_call: ApiCall) -> None:
-        """
-        Initialize the Analytics object.
 
-        Args:
-            api_call (ApiCall): The API call object for making requests.
-        """
-        self.rules = AnalyticsRules(api_call)

src/typesense/analytics_events.py

@@ -0,0 +1,73 @@
+"""Client for Analytics events and status operations."""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+from typesense.api_call import ApiCall
+from typesense.types.analytics import (
+    AnalyticsEvent as AnalyticsEventSchema,
+    AnalyticsEventCreateResponse,
+    AnalyticsEventsResponse,
+    AnalyticsStatus,
+)
+
+
+class AnalyticsEvents:
+    events_path: typing.Final[str] = "/analytics/events"
+    flush_path: typing.Final[str] = "/analytics/flush"
+    status_path: typing.Final[str] = "/analytics/status"
+
+    def __init__(self, api_call: ApiCall) -> None:
+        self.api_call = api_call
+
+    def create(self, event: AnalyticsEventSchema) -> AnalyticsEventCreateResponse:
+        response: AnalyticsEventCreateResponse = self.api_call.post(
+            AnalyticsEvents.events_path,
+            body=event,
+            as_json=True,
+            entity_type=AnalyticsEventCreateResponse,
+        )
+        return response
+
+    def retrieve(
+        self,
+        *,
+        user_id: str,
+        name: str,
+        n: int,
+    ) -> AnalyticsEventsResponse:
+        params: typing.Dict[str, typing.Union[str, int]] = {
+            "user_id": user_id,
+            "name": name,
+            "n": n,
+        }
+        response: AnalyticsEventsResponse = self.api_call.get(
+            AnalyticsEvents.events_path,
+            params=params,
+            as_json=True,
+            entity_type=AnalyticsEventsResponse,
+        )
+        return response
+
+    def flush(self) -> AnalyticsEventCreateResponse:
+        response: AnalyticsEventCreateResponse = self.api_call.post(
+            AnalyticsEvents.flush_path,
+            body={},
+            as_json=True,
+            entity_type=AnalyticsEventCreateResponse,
+        )
+        return response
+
+    def status(self) -> AnalyticsStatus:
+        response: AnalyticsStatus = self.api_call.get(
+            AnalyticsEvents.status_path,
+            as_json=True,
+            entity_type=AnalyticsStatus,
+        )
+        return response
+
+

src/typesense/analytics_rule.py

@@ -1,24 +1,4 @@
-"""
-This module provides functionality for managing individual analytics rules in Typesense.
-
-Classes:
-    - AnalyticsRule: Handles operations related to a specific analytics rule.
-
-Methods:
-    - __init__: Initializes the AnalyticsRule object.
-    - _endpoint_path: Constructs the API endpoint path for this specific analytics rule.
-    - retrieve: Retrieves the details of this specific analytics rule.
-    - delete: Deletes this specific analytics rule.
-
-The AnalyticsRule class interacts with the Typesense API to manage operations on a
-specific analytics rule. It provides methods to retrieve and delete individual rules.
-
-For more information on analytics, refer to the Analytics & Query Suggestion
-[documentation](https://typesense.org/docs/27.0/api/analytics-query-suggestions.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.
-"""
+"""Per-rule client for Analytics rules operations."""
 
 import sys
 
@@ -28,77 +8,33 @@
     import typing_extensions as typing
 
 from typesense.api_call import ApiCall
-from typesense.types.analytics_rule import (
-    RuleDeleteSchema,
-    RuleSchemaForCounters,
-    RuleSchemaForQueries,
-)
+from typesense.types.analytics import AnalyticsRule
 
 
 class AnalyticsRule:
-    """
-    Class for managing individual analytics rules in Typesense.
-
-    This class provides methods to interact with a specific analytics rule,
-    including retrieving and deleting it.
-
-    Attributes:
-        api_call (ApiCall): The API call object for making requests.
-        rule_id (str): The ID of the analytics rule.
-    """
-
-    def __init__(self, api_call: ApiCall, rule_id: str):
-        """
-        Initialize the AnalyticsRule object.
-
-        Args:
-            api_call (ApiCall): The API call object for making requests.
-            rule_id (str): The ID of the analytics rule.
-        """
+    def __init__(self, api_call: ApiCall, rule_name: str) -> None:
         self.api_call = api_call
-        self.rule_id = rule_id
+        self.rule_name = rule_name
+
+    @property
+    def _endpoint_path(self) -> str:
+        from typesense.analytics_rules import AnalyticsRules
 
-    def retrieve(
-        self,
-    ) -> typing.Union[RuleSchemaForQueries, RuleSchemaForCounters]:
-        """
-        Retrieve this specific analytics rule.
+        return "/".join([AnalyticsRules.resource_path, self.rule_name])
 
-        Returns:
-            Union[RuleSchemaForQueries, RuleSchemaForCounters]:
-              The schema containing the rule details.
-        """
-        response: typing.Union[RuleSchemaForQueries, RuleSchemaForCounters] = (
-            self.api_call.get(
-                self._endpoint_path,
-                entity_type=typing.Union[RuleSchemaForQueries, RuleSchemaForCounters],
-                as_json=True,
-            )
+    def retrieve(self) -> AnalyticsRule:
+        response: AnalyticsRule = self.api_call.get(
+            self._endpoint_path,
+            as_json=True,
+            entity_type=AnalyticsRule,
         )
         return response
 
-    def delete(self) -> RuleDeleteSchema:
-        """
-        Delete this specific analytics rule.
-
-        Returns:
-            RuleDeleteSchema: The schema containing the deletion response.
-        """
-        response: RuleDeleteSchema = self.api_call.delete(
+    def delete(self) -> AnalyticsRule:
+        response: AnalyticsRule = self.api_call.delete(
             self._endpoint_path,
-            entity_type=RuleDeleteSchema,
+            entity_type=AnalyticsRule,
         )
-
         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.analytics_rules import AnalyticsRules
 
-        return "/".join([AnalyticsRules.resource_path, self.rule_id])

src/typesense/analytics_rule_v1.py

@@ -0,0 +1,106 @@
+"""
+This module provides functionality for managing individual analytics rules in Typesense (V1).
+
+Classes:
+    - AnalyticsRuleV1: Handles operations related to a specific analytics rule.
+
+Methods:
+    - __init__: Initializes the AnalyticsRuleV1 object.
+    - _endpoint_path: Constructs the API endpoint path for this specific analytics rule.
+    - retrieve: Retrieves the details of this specific analytics rule.
+    - delete: Deletes this specific analytics rule.
+
+The AnalyticsRuleV1 class interacts with the Typesense API to manage operations on a
+specific analytics rule. It provides methods to retrieve and delete individual rules.
+
+For more information on analytics, refer to the Analytics & Query Suggestion
+[documentation](https://typesense.org/docs/27.0/api/analytics-query-suggestions.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.
+"""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+from typesense.api_call import ApiCall
+from typesense.types.analytics_rule_v1 import (
+    RuleDeleteSchema,
+    RuleSchemaForCounters,
+    RuleSchemaForQueries,
+)
+
+
+class AnalyticsRuleV1:
+    """
+    Class for managing individual analytics rules in Typesense (V1).
+
+    This class provides methods to interact with a specific analytics rule,
+    including retrieving and deleting it.
+
+    Attributes:
+        api_call (ApiCall): The API call object for making requests.
+        rule_id (str): The ID of the analytics rule.
+    """
+
+    def __init__(self, api_call: ApiCall, rule_id: str):
+        """
+        Initialize the AnalyticsRuleV1 object.
+
+        Args:
+            api_call (ApiCall): The API call object for making requests.
+            rule_id (str): The ID of the analytics rule.
+        """
+        self.api_call = api_call
+        self.rule_id = rule_id
+
+    def retrieve(
+        self,
+    ) -> typing.Union[RuleSchemaForQueries, RuleSchemaForCounters]:
+        """
+        Retrieve this specific analytics rule.
+
+        Returns:
+            Union[RuleSchemaForQueries, RuleSchemaForCounters]:
+              The schema containing the rule details.
+        """
+        response: typing.Union[RuleSchemaForQueries, RuleSchemaForCounters] = (
+            self.api_call.get(
+                self._endpoint_path,
+                entity_type=typing.Union[RuleSchemaForQueries, RuleSchemaForCounters],
+                as_json=True,
+            )
+        )
+        return response
+
+    def delete(self) -> RuleDeleteSchema:
+        """
+        Delete this specific analytics rule.
+
+        Returns:
+            RuleDeleteSchema: The schema containing the deletion response.
+        """
+        response: RuleDeleteSchema = self.api_call.delete(
+            self._endpoint_path,
+            entity_type=RuleDeleteSchema,
+        )
+
+        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.analytics_rules_v1 import AnalyticsRulesV1
+
+        return "/".join([AnalyticsRulesV1.resource_path, self.rule_id])
+
+