#MPT-12328 Single result result

Author: albertsola

mpt_api_client/http/models.py

@@ -0,0 +1,105 @@
+import math
+from dataclasses import dataclass, field
+from typing import Any, Self, TypeVar
+
+from box import Box
+from httpx import Response
+
+ExpectedType = TypeVar("ExpectedType")
+
+
+def ensure_class_instance(
+    instance: dict[str, Any] | ExpectedType | None, expected_class: type[ExpectedType]
+) -> ExpectedType | None:
+    """
+    Ensures that the given value is an instance of the specified class.
+
+    If `value` is a dict, it instantiates `cls` with the dict as keyword arguments.
+    If `value` is already an instance of `cls` or None, it returns `value` as is.
+
+    Args:
+        instance: None, a dict, or an instance of `cls`.
+        expected_class: The class to instantiate if `value` is a dict.
+
+    Returns:
+        An instance of `cls` or None.
+    """
+    if isinstance(instance, dict):
+        return expected_class(**instance)
+    return instance
+
+
+@dataclass
+class Pagination:
+    """Provides pagination information."""
+
+    limit: int = 0
+    offset: int = 0
+    total: int = 0
+
+    def has_next(self) -> bool:
+        """Returns True if there is a next page."""
+        return self.offset + self.limit < self.total
+
+    def num_page(self) -> int:
+        """Returns the current page number."""
+        if self.limit == 0:
+            return 0
+        return (self.offset // self.limit) + 1
+
+    def total_pages(self) -> int:
+        """Returns the total number of pages."""
+        if self.limit == 0:
+            return 0
+        return math.ceil(self.total / self.limit)
+
+    def next_offset(self) -> int:
+        """Returns the next offset as an integer for the next page."""
+        return self.offset + self.limit
+
+
+@dataclass
+class Meta:
+    """Provides meta information about the pagination, ignored fields and the response."""
+
+    pagination: Pagination = field(default_factory=Pagination)
+    ignored: list[str] = field(default_factory=list)
+    response: Response | None = None
+
+    def __post_init__(self) -> None:
+        """Setups pagination and ignored fields."""
+        self.pagination = ensure_class_instance(self.pagination, Pagination) or Pagination()
+        self.ignored = self.ignored or []
+
+
+class GenericResource(Box):
+    """Provides a base resource to interact with api data using fluent interfaces."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.__post_init__()
+
+    def __post_init__(self) -> None:
+        """Initializes meta information."""
+        meta = self.get("$meta", None)  # type: ignore[no-untyped-call]
+        if meta:
+            self._meta = Meta(**meta)
+
+    @classmethod
+    def from_response(cls, response: Response) -> Self:
+        """Creates a resource from a response.
+
+        Expected a Response with json data with two keys: data and $meta.
+        """
+        response_data = response.json().get("data")
+        if not isinstance(response_data, dict):
+            raise TypeError("Response data must be a dict.")
+
+        meta_data = response.json().get("$meta")
+        if not isinstance(meta_data, dict):
+            raise TypeError("Response $meta must be a dict.")
+        meta = Meta(**meta_data)
+        meta.response = response
+        resource = cls(response_data)
+        resource._meta = meta
+        return resource

pyproject.toml

@@ -20,7 +20,8 @@ classifiers = [
     "Topic :: Utilities",
 ]
 dependencies = [
-    "httpx==0.28.*"
+    "httpx==0.28.*",
+    "python-box>=7.3.2",
 ]
 
 [dependency-groups]
@@ -166,13 +167,16 @@ pydocstyle.convention = "google"
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*.py" = [
+  "D101", # do not require docstrings in public classes
+  "D102", # do not require docstrincs in public method
   "D103", # missing docstring in public function
   "PLR2004", # allow magic numbers in tests
   "S101", # asserts
   "S105", # hardcoded passwords
   "S404", # subprocess calls are for tests
   "S603", # do not require `shell=True`
   "S607", # partial executable paths
+  "SLF001", # Allow private property/method access
 ]
 
 [tool.mypy]

setup.cfg

@@ -26,4 +26,21 @@ extend-exclude =
 select = WPS, E999
 
 per-file-ignores =
-  tests/*: WPS432
+  tests/*:
+    # Allow private property/method access
+    SLF001
+
+    # Allow unused variables
+    WPS122
+
+    # Allow >7 methods
+    WPS214
+
+    # Allow string literal overuse
+    WPS226
+
+    # Allow magic strings
+    WPS432
+
+    # Allow noqa overuse
+    WPS402

tests/http/models/test_genric_resource.py

@@ -0,0 +1,110 @@
+import re
+
+import pytest
+from httpx import Response
+
+from mpt_api_client.http.models import GenericResource, Meta
+
+
+@pytest.fixture
+def meta_data():
+    return {"pagination": {"limit": 10, "offset": 20, "total": 100}, "ignored": ["one"]}  # noqa: WPS226
+
+
+class TestGenericResource:  # noqa: WPS214
+    def test_generic_resource_empty(self):
+        resource = GenericResource()
+        with pytest.raises(AttributeError):
+            _ = resource._meta
+
+    def test_initialization_with_data(self):
+        resource = GenericResource(name="test", value=123)
+
+        assert resource.name == "test"
+        assert resource.value == 123
+
+    def test_init(self, meta_data):
+        resource = {"$meta": meta_data, "key": "value"}  # noqa: WPS445 WPS517
+        init_one = GenericResource(resource)
+        init_two = GenericResource(**resource)
+        assert init_one == init_two
+
+    def test_generic_resource_meta_property_with_data(self, meta_data):
+        resource = GenericResource({"$meta": meta_data})
+        assert resource._meta == Meta(**meta_data)
+
+    def test_generic_resource_box_functionality(self):
+        resource = GenericResource(id=1, name="test_resource", nested={"key": "value"})
+
+        assert resource.id == 1
+        assert resource.name == "test_resource"
+        assert resource.nested.key == "value"
+
+    def test_with_both_meta_and_response(self, meta_data):
+        response = Response(200, json={})
+        meta_data["response"] = response
+        meta_object = Meta(**meta_data)
+
+        resource = GenericResource(
+            data="test_data",
+            **{"$meta": meta_data},  # noqa: WPS445 WPS517
+        )
+
+        assert resource.data == "test_data"
+        assert resource._meta == meta_object
+
+    def test_dynamic_attribute_access(self):
+        resource = GenericResource()
+
+        resource.dynamic_field = "dynamic_value"
+        resource.nested_object = {"inner": "data"}
+
+        assert resource.dynamic_field == "dynamic_value"
+        assert resource.nested_object.inner == "data"
+
+
+class TestGenericResourceFromResponse:
+    @pytest.fixture
+    def meta_data_single(self):
+        return {"ignored": ["one"]}  # noqa: WPS226
+
+    @pytest.fixture
+    def meta_data_two_resources(self):
+        return {"pagination": {"limit": 10, "offset": 0, "total": 2}, "ignored": ["one"]}  # noqa: WPS226
+
+    @pytest.fixture
+    def meta_data_multiple(self):
+        return {"ignored": ["one", "two"]}  # noqa: WPS226
+
+    @pytest.fixture
+    def single_resource_data(self):
+        return {"id": 1, "name": "test"}
+
+    @pytest.fixture
+    def single_resource_response(self, single_resource_data, meta_data_single):
+        return Response(200, json={"data": single_resource_data, "$meta": meta_data_single})
+
+    @pytest.fixture
+    def multiple_resource_response(self, single_resource_data, meta_data_two_resources):
+        return Response(
+            200,
+            json={
+                "data": [single_resource_data, single_resource_data],
+                "$meta": meta_data_two_resources,
+            },
+        )
+
+    def test_malformed_meta_response(self):
+        with pytest.raises(TypeError, match=re.escape("Response $meta must be a dict.")):
+            _resource = GenericResource.from_response(Response(200, json={"data": {}, "$meta": 4}))
+
+    def test_single_resource(self, single_resource_response):
+        resource = GenericResource.from_response(single_resource_response)
+        assert resource.id == 1
+        assert resource.name == "test"
+        assert isinstance(resource._meta, Meta)
+        assert resource._meta.response == single_resource_response
+
+    def test_two_resources(self, multiple_resource_response, single_resource_data):
+        with pytest.raises(TypeError, match=r"Response data must be a dict."):
+            _resource = GenericResource.from_response(multiple_resource_response)

tests/http/models/test_meta.py

@@ -0,0 +1,44 @@
+from mpt_api_client.http.models import Meta, Pagination
+
+
+class TestMeta:
+    def test_meta_initialization_empty(self):
+        meta = Meta()
+
+        assert meta.pagination == Pagination(limit=0, offset=0, total=0)
+
+    def test_meta_initialization_with_pagination_none(self):
+        meta = Meta(pagination=None)
+
+        assert meta.pagination == Pagination(limit=0, offset=0, total=0)
+
+    def test_meta_with_pagination_object(self):
+        pagination = Pagination(limit=10, offset=0, total=100)
+        meta = Meta(pagination=pagination)
+
+        assert meta.pagination == Pagination(limit=10, offset=0, total=100)
+
+    def test_meta_with_pagination_dict(self):
+        meta = Meta(pagination={"limit": 20, "offset": 40, "total": 200})
+
+        assert isinstance(meta.pagination, Pagination)
+        assert meta.pagination.limit == 20
+        assert meta.pagination.offset == 40
+        assert meta.pagination.total == 200
+
+    def test_meta_set_pagination_after_init(self):
+        meta = Meta()
+        pagination = Pagination(limit=15, offset=30, total=150)
+
+        meta.pagination = pagination
+
+        assert meta.pagination == pagination
+
+    def test_meta_access_pagination_methods(self):
+        resource_data = {"pagination": {"limit": 25, "offset": 50, "total": 300}}
+        meta = Meta(**resource_data)
+        assert isinstance(meta.pagination, Pagination)
+        assert meta.pagination.has_next() is True
+        assert meta.pagination.num_page() == 3
+        assert meta.pagination.total_pages() == 12
+        assert meta.pagination.next_offset() == 75