python-kanka 2.4.1__tar.gz → 2.5.0__tar.gz

{python_kanka-2.4.1 → python_kanka-2.5.0}/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.4.0
+current_version = 2.5.0
 commit = True
 tag = True
 tag_name = v{new_version}

{python_kanka-2.4.1 → python_kanka-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-kanka
-Version: 2.4.1
+Version: 2.5.0
 Summary: Python client for the Kanka API
 Project-URL: Homepage, https://github.com/ervwalter/python-kanka
 Project-URL: Documentation, https://github.com/ervwalter/python-kanka#readme

{python_kanka-2.4.1 → python_kanka-2.5.0}/docs/api-reference.md

@@ -90,12 +90,21 @@ Get a single entity by its universal `entity_id`. Returns a raw dictionary.
 #### entities
 
 ```python
-entities(**filters) → list[dict[str, Any]]
+entities(page: int = 1, limit: int = 15, **filters) → list[dict[str, Any]]
 ```
 
 Query the generic `/entities` endpoint. Returns raw dictionaries.
 
-**Filters:** `types` (list[str]), `name` (str), `tags` (list[int]), `is_private` (bool), `created_by` (int), `updated_by` (int)
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | `int` | `1` | Page number |
+| `limit` | `int` | `15` | Results per page |
+| `types` | `list[str]` | — | Filter by entity types |
+| `name` | `str` | — | Filter by name |
+| `tags` | `list[int]` | — | Filter by tag IDs |
+| `is_private` | `bool` | — | Filter by privacy |
+| `created_by` | `int` | — | Filter by creator ID |
+| `updated_by` | `int` | — | Filter by updater ID |
 
 #### gallery
 
@@ -137,6 +146,9 @@ Delete a gallery image by UUID.
 
 | Property | Type | Description |
 |----------|------|-------------|
+| `last_entities_meta` | `dict` | Pagination metadata from last `entities()` |
+| `last_entities_links` | `dict` | Pagination links from last `entities()` |
+| `entities_has_next_page` | `bool` | Whether next page exists for `entities()` |
 | `last_search_meta` | `dict` | Pagination metadata from last `search()` |
 | `last_search_links` | `dict` | Pagination links from last `search()` |
 | `last_gallery_meta` | `dict` | Pagination metadata from last `gallery()` |

{python_kanka-2.4.1 → python_kanka-2.5.0}/docs/pagination.md

@@ -83,6 +83,14 @@ Each list endpoint stores its own pagination state:
 | `manager.last_assets_meta` | Metadata from last `list_assets()` |
 | `manager.last_assets_links` | Links from last `list_assets()` |
 
+### Entities
+
+| Property | Description |
+|----------|-------------|
+| `client.last_entities_meta` | Metadata from last `entities()` |
+| `client.last_entities_links` | Links from last `entities()` |
+| `client.entities_has_next_page` | `True` if next page exists |
+
 ### Gallery
 
 | Property | Description |

{python_kanka-2.4.1 → python_kanka-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-kanka"
-version = "2.4.1"
+version = "2.5.0"
 description = "Python client for the Kanka API"
 readme = "README.md"
 requires-python = ">=3.12"

{python_kanka-2.4.1 → python_kanka-2.5.0}/src/kanka/_version.py

@@ -1,3 +1,3 @@
 """Version information for python-kanka."""
 
-__version__ = "2.4.1"
+__version__ = "2.5.0"

{python_kanka-2.4.1 → python_kanka-2.5.0}/src/kanka/client.py

@@ -321,19 +321,29 @@ class KankaClient:
         response = self._request("GET", f"entities/{entity_id}")
         return response["data"]  # type: ignore[no-any-return]
 
-    def entities(self, **filters) -> list[dict[str, Any]]:
+    def entities(
+        self, page: int = 1, limit: int = 15, **filters
+    ) -> list[dict[str, Any]]:
         """Access the /entities endpoint with filters.
 
         This endpoint provides a unified way to query entities across all types
         with various filtering options.
 
         Args:
+            page: Page number (default: 1)
+            limit: Number of results per page (default: 15)
             **filters: Filter parameters like types, name, is_private, tags
 
         Returns:
             List of entity data
+
+        Note:
+            Pagination information is available after calling entities():
+            - client.last_entities_meta: Contains total count, current page, etc.
+            - client.last_entities_links: Contains URLs for first, last, prev, next
+            - client.entities_has_next_page: True if more pages are available
         """
-        params: dict[str, int | str] = {}
+        params: dict[str, int | str] = {"page": page, "limit": limit}
 
         # Handle special filters
         if "types" in filters and isinstance(filters["types"], list):
@@ -355,6 +365,8 @@ class KankaClient:
                     params[key] = filters[key]
 
         response = self._request("GET", "entities", params=params)
+        self._last_entities_meta = response.get("meta", {})
+        self._last_entities_links = response.get("links", {})
         return response["data"]  # type: ignore[no-any-return]
 
     def _parse_rate_limit_headers(self, response) -> float | None:
@@ -692,3 +704,27 @@ class KankaClient:
             Dict[str, Any]: Links for pagination including first, last, prev, next URLs
         """
         return getattr(self, "_last_search_links", {})
+
+    @property
+    def last_entities_meta(self) -> dict[str, Any]:
+        """Get metadata from the last entities() call.
+
+        Returns:
+            Dict[str, Any]: Pagination metadata including current_page, from, to,
+                           last_page, per_page, total
+        """
+        return getattr(self, "_last_entities_meta", {})
+
+    @property
+    def last_entities_links(self) -> dict[str, Any]:
+        """Get pagination links from the last entities() call.
+
+        Returns:
+            Dict[str, Any]: Links for pagination including first, last, prev, next URLs
+        """
+        return getattr(self, "_last_entities_links", {})
+
+    @property
+    def entities_has_next_page(self) -> bool:
+        """Check if more pages are available from the last entities() call."""
+        return bool(getattr(self, "_last_entities_links", {}).get("next"))

{python_kanka-2.4.1 → python_kanka-2.5.0}/tests/test_client.py

@@ -151,7 +151,7 @@ class TestKankaClient:
         mock_session.request.assert_called_with(
             "GET",
             "https://api.kanka.io/1.0/campaigns/123/entities",
-            params={"types": "character,location"},
+            params={"page": 1, "limit": 15, "types": "character,location"},
         )
 
         assert len(results) == 2
@@ -181,6 +181,8 @@ class TestKankaClient:
             "GET",
             "https://api.kanka.io/1.0/campaigns/123/entities",
             params={
+                "page": 1,
+                "limit": 15,
                 "types": "character",
                 "tags": "1,2,3",
                 "name": "test",
@@ -189,6 +191,80 @@ class TestKankaClient:
             },
         )
 
+    @patch("requests.Session")
+    def test_entities_pagination(self, mock_session_class):
+        """Test entities endpoint pagination parameters and metadata."""
+        mock_session = MagicMock()
+        mock_session_class.return_value = mock_session
+
+        meta = {
+            "total": 50,
+            "current_page": 2,
+            "per_page": 15,
+            "last_page": 4,
+            "from": 16,
+            "to": 30,
+        }
+        links = {
+            "first": "https://api.kanka.io/1.0/campaigns/123/entities?page=1",
+            "last": "https://api.kanka.io/1.0/campaigns/123/entities?page=4",
+            "prev": "https://api.kanka.io/1.0/campaigns/123/entities?page=1",
+            "next": "https://api.kanka.io/1.0/campaigns/123/entities?page=3",
+        }
+        mock_response = MockResponse(
+            create_api_response(
+                [{"id": 1, "name": "Test", "type": "character"}],
+                meta=meta,
+                links=links,
+            ),
+            status_code=200,
+        )
+        mock_session.request.return_value = mock_response
+
+        client = KankaClient(token="test_token", campaign_id=123)
+        results = client.entities(page=2, limit=15, types=["character"])
+
+        mock_session.request.assert_called_with(
+            "GET",
+            "https://api.kanka.io/1.0/campaigns/123/entities",
+            params={"page": 2, "limit": 15, "types": "character"},
+        )
+
+        assert len(results) == 1
+        assert client.last_entities_meta["total"] == 50
+        assert client.last_entities_meta["current_page"] == 2
+        assert client.last_entities_links["next"] is not None
+        assert client.entities_has_next_page is True
+
+    @patch("requests.Session")
+    def test_entities_no_next_page(self, mock_session_class):
+        """Test entities_has_next_page is False on last page."""
+        mock_session = MagicMock()
+        mock_session_class.return_value = mock_session
+
+        mock_response = MockResponse(
+            create_api_response([{"id": 1, "name": "Test", "type": "character"}]),
+            status_code=200,
+        )
+        mock_session.request.return_value = mock_response
+
+        client = KankaClient(token="test_token", campaign_id=123)
+        client.entities()
+
+        assert client.entities_has_next_page is False
+
+    @patch("requests.Session")
+    def test_entities_pagination_defaults(self, mock_session_class):
+        """Test entities pagination properties before any call."""
+        mock_session = MagicMock()
+        mock_session_class.return_value = mock_session
+
+        client = KankaClient(token="test_token", campaign_id=123)
+
+        assert client.last_entities_meta == {}
+        assert client.last_entities_links == {}
+        assert client.entities_has_next_page is False
+
     @patch("requests.Session")
     def test_request_error_handling(self, mock_session_class):
         """Test error handling in _request method."""

{python_kanka-2.4.1 → python_kanka-2.5.0}/uv.lock

@@ -853,7 +853,7 @@ wheels = [
 
 [[package]]
 name = "python-kanka"
-version = "2.4.0"
+version = "2.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },