feat(metrics): add async support for metrics operations

- add AsyncMetrics class for async metrics retrieval
- add async tests for metrics functionality
- add async fixtures for testing async metrics operations

Author: tharropoulos

src/typesense/async_metrics.py

@@ -0,0 +1,69 @@
+"""
+This module provides async functionality for retrieving metrics from the Typesense API.
+
+It contains the AsyncMetrics class, which handles async API operations for retrieving
+system and Typesense metrics such as CPU, memory, disk, and network usage.
+
+Classes:
+    MetricsResponse: Type definition for metrics response (imported from typesense.metrics).
+    AsyncMetrics: Manages async retrieval of metrics from the Typesense API.
+
+Dependencies:
+    - typesense.async_api_call: Provides the AsyncApiCall class for making async API requests.
+    - typesense.metrics: Provides MetricsResponse type definitions.
+
+Note: This module uses conditional imports to support both Python 3.11+ and earlier versions.
+"""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+from typesense.async_api_call import AsyncApiCall
+from typesense.metrics import MetricsResponse
+
+
+class AsyncMetrics:
+    """
+    Manages async metrics retrieval from the Typesense API.
+
+    This class provides async methods to retrieve system and Typesense metrics
+    such as CPU, memory, disk, and network usage.
+
+    Attributes:
+        resource_path (str): The base path for metrics endpoint.
+        api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+    """
+
+    resource_path: typing.Final[str] = "/metrics.json"
+
+    def __init__(self, api_call: AsyncApiCall):
+        """
+        Initialize the AsyncMetrics instance.
+
+        Args:
+            api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+        """
+        self.api_call = api_call
+
+    async def retrieve(self) -> MetricsResponse:
+        """
+        Retrieve metrics from the Typesense API.
+
+        Returns:
+            MetricsResponse: A dictionary containing system and Typesense metrics.
+
+        Example:
+            >>> metrics = AsyncMetrics(async_api_call)
+            >>> response = await metrics.retrieve()
+            >>> print(response["system_cpu_active_percentage"])
+        """
+        response: MetricsResponse = await self.api_call.get(
+            AsyncMetrics.resource_path,
+            as_json=True,
+            entity_type=MetricsResponse,
+        )
+        return response

tests/fixtures/metrics_fixtures.py

@@ -3,10 +3,24 @@
 import pytest
 
 from typesense.api_call import ApiCall
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_metrics import AsyncMetrics
 from typesense.metrics import Metrics
 
 
 @pytest.fixture(scope="function", name="actual_metrics")
 def actual_debug_fixture(actual_api_call: ApiCall) -> Metrics:
     """Return a Debug object using a real API."""
     return Metrics(actual_api_call)
+
+
+@pytest.fixture(scope="function", name="actual_async_metrics")
+def actual_async_metrics_fixture(actual_async_api_call: AsyncApiCall) -> AsyncMetrics:
+    """Return a AsyncMetrics object using a real API."""
+    return AsyncMetrics(actual_async_api_call)
+
+
+@pytest.fixture(scope="function", name="fake_async_metrics")
+def fake_async_metrics_fixture(fake_async_api_call: AsyncApiCall) -> AsyncMetrics:
+    """Return a AsyncMetrics object with test values."""
+    return AsyncMetrics(fake_async_api_call)

tests/metrics_test.py

@@ -1,12 +1,51 @@
-"""Tests for the Debug class."""
+"""Tests for the Metrics class."""
 
 from __future__ import annotations
 
+from tests.utils.object_assertions import (
+    assert_match_object,
+    assert_object_lists_match,
+)
+from typesense.api_call import ApiCall
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_metrics import AsyncMetrics
 from typesense.metrics import Metrics
 
 
+def test_init(fake_api_call: ApiCall) -> None:
+    """Test that the Metrics object is initialized correctly."""
+    metrics = Metrics(fake_api_call)
+
+    assert_match_object(metrics.api_call, fake_api_call)
+    assert_object_lists_match(
+        metrics.api_call.node_manager.nodes,
+        fake_api_call.node_manager.nodes,
+    )
+    assert_match_object(
+        metrics.api_call.config.nearest_node,
+        fake_api_call.config.nearest_node,
+    )
+    assert metrics.resource_path == "/metrics.json"  # noqa: WPS437
+
+
+def test_init_async(fake_async_api_call: AsyncApiCall) -> None:
+    """Test that the AsyncMetrics object is initialized correctly."""
+    metrics = AsyncMetrics(fake_async_api_call)
+
+    assert_match_object(metrics.api_call, fake_async_api_call)
+    assert_object_lists_match(
+        metrics.api_call.node_manager.nodes,
+        fake_async_api_call.node_manager.nodes,
+    )
+    assert_match_object(
+        metrics.api_call.config.nearest_node,
+        fake_async_api_call.config.nearest_node,
+    )
+    assert metrics.resource_path == "/metrics.json"  # noqa: WPS437
+
+
 def test_actual_retrieve(actual_metrics: Metrics) -> None:
-    """Test that the Debug object can retrieve a debug on Typesense server and verify response structure."""
+    """Test that the Metrics object can retrieve metrics on Typesense server and verify response structure."""
     response = actual_metrics.retrieve()
 
     assert "system_cpu_active_percentage" in response
@@ -24,3 +63,24 @@ def test_actual_retrieve(actual_metrics: Metrics) -> None:
     assert "typesense_memory_metadata_bytes" in response
     assert "typesense_memory_resident_bytes" in response
     assert "typesense_memory_retained_bytes" in response
+
+
+async def test_actual_retrieve_async(actual_async_metrics: AsyncMetrics) -> None:
+    """Test that the AsyncMetrics object can retrieve metrics on Typesense server and verify response structure."""
+    response = await actual_async_metrics.retrieve()
+
+    assert "system_cpu_active_percentage" in response
+    assert "system_disk_total_bytes" in response
+    assert "system_disk_used_bytes" in response
+    assert "system_memory_total_bytes" in response
+    assert "system_memory_used_bytes" in response
+    assert "system_network_received_bytes" in response
+    assert "system_network_sent_bytes" in response
+    assert "typesense_memory_active_bytes" in response
+    assert "typesense_memory_allocated_bytes" in response
+    assert "typesense_memory_fragmentation_ratio" in response
+
+    assert "typesense_memory_mapped_bytes" in response
+    assert "typesense_memory_metadata_bytes" in response
+    assert "typesense_memory_resident_bytes" in response
+    assert "typesense_memory_retained_bytes" in response