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

{python_kanka-2.4.0 → 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.0 → python_kanka-2.5.0}/.gitignore

@@ -171,8 +171,7 @@ Thumbs.db
 tests/integration/.env
 tests/integration/*.log
 
-# Test output files
-*_test_output.txt
-*_output.txt
+# Test and debug output files
+*_output*.txt
 test_api_response.py
 claude-notes

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-kanka
-Version: 2.4.0
+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.0 → 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()` |
@@ -388,9 +400,11 @@ create_alias_asset(
 #### delete_asset
 
 ```python
-delete_asset(entity_or_id: T | int, asset_id: int) → bool
+delete_asset(entity_or_id: T | int, asset_id: int, *, delete_gallery_image: bool = False) → bool
 ```
 
+When `delete_gallery_image=True`, also deletes the underlying campaign gallery image to prevent orphaned images from accumulating. The gallery image UUID is extracted from the asset's CDN URL.
+
 ### Image Methods
 
 All image methods accept an entity object or an `entity_id` (integer).

{python_kanka-2.4.0 → python_kanka-2.5.0}/docs/assets-and-images.md

@@ -86,6 +86,9 @@ asset = client.characters.create_alias_asset(
 
 ```python
 client.characters.delete_asset(character, asset.id)
+
+# Also delete the underlying gallery image to prevent orphans:
+client.characters.delete_asset(character, asset.id, delete_gallery_image=True)
 ```
 
 ### EntityAsset Model Fields
@@ -204,8 +207,8 @@ The SDK uses a naming convention for assets it manages: `{name}:{sha256_first12}
 When you call `update()` or `update_post()` with `images`, the SDK compares file hashes:
 
 - **Unchanged files** (same SHA-256 hash) — reused without re-uploading
-- **Changed files** (different hash) — old asset deleted, new one uploaded
-- **Orphaned managed assets** (no longer referenced in `images` dict) — automatically cleaned up
+- **Changed files** (different hash) — old asset deleted (along with its gallery image), new one uploaded
+- **Orphaned managed assets** (no longer referenced in `images` dict) — automatically cleaned up (both entity asset and gallery image)
 - **Non-managed assets** (user-created assets without the hash suffix) — never touched
 
 ### Full Lifecycle Example

{python_kanka-2.4.0 → 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.0 → python_kanka-2.5.0}/pyproject.toml

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

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

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

{python_kanka-2.4.0 → 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.0 → python_kanka-2.5.0}/src/kanka/managers.py

@@ -1,10 +1,12 @@
 """Entity managers for Kanka API."""
 
+import contextlib
 import hashlib
 import re
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, List, TypeVar  # noqa: UP035
 
+from .exceptions import NotFoundError
 from .models.base import Entity, Post
 from .models.common import EntityAsset, EntityImageInfo
 
@@ -420,6 +422,22 @@ class EntityManager[T: Entity]:
             return m.group(1), m.group(2)
         return None
 
+    @staticmethod
+    def _extract_gallery_uuid(url: str | None) -> str | None:
+        """Extract gallery image UUID from a CDN URL.
+
+        The UUID is the filename stem in the URL path, e.g.
+        ``https://cdn-ugc.kanka.io/campaigns/123/a1b2-...-c3d4.webp``
+        yields ``a1b2-...-c3d4``.
+        """
+        if not url:
+            return None
+        m = re.search(
+            r"/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.\w+",
+            url,
+        )
+        return m.group(1) if m else None
+
     @staticmethod
     def _rewrite_image_srcs(html: str, url_map: dict[str, str]) -> str:
         """Rewrite <img src="key"> tags, replacing keys with CDN URLs."""
@@ -480,18 +498,22 @@ class EntityManager[T: Entity]:
         for placeholder, file_path in images.items():
             file_path = Path(file_path)
             file_hash = self._compute_file_hash(file_path)
-            used_names.add(placeholder)
+            # Truncate to match what _format_managed_asset_name stores
+            lookup_name = placeholder[:32]
+            used_names.add(lookup_name)
 
-            if placeholder in managed:
-                old_hash, old_asset = managed[placeholder]
+            if lookup_name in managed:
+                old_hash, old_asset = managed[lookup_name]
                 if old_hash == file_hash:
                     # Same file, reuse URL
                     if old_asset.url:
                         url_map[placeholder] = old_asset.url
                     continue
                 else:
-                    # Changed file, delete old and upload new
-                    self.delete_asset(entity_id, old_asset.id)
+                    # Changed file, delete old asset and its gallery image
+                    self.delete_asset(
+                        entity_id, old_asset.id, delete_gallery_image=True
+                    )
 
             managed_name = self._format_managed_asset_name(placeholder, file_hash)
             asset = self.create_file_asset(entity_id, file_path, name=managed_name)
@@ -501,7 +523,7 @@ class EntityManager[T: Entity]:
         # Orphan cleanup: delete managed assets not in current images dict
         for name_part, (_, old_asset) in managed.items():
             if name_part not in used_names:
-                self.delete_asset(entity_id, old_asset.id)
+                self.delete_asset(entity_id, old_asset.id, delete_gallery_image=True)
 
         if url_map:
             return self._rewrite_image_srcs(entry, url_map)
@@ -860,19 +882,39 @@ class EntityManager[T: Entity]:
         response = self.client._request("POST", endpoint, json=data)
         return EntityAsset(**response["data"])
 
-    def delete_asset(self, entity_or_id: T | int, asset_id: int) -> bool:
+    def delete_asset(
+        self,
+        entity_or_id: T | int,
+        asset_id: int,
+        *,
+        delete_gallery_image: bool = False,
+    ) -> bool:
         """Delete an asset from an entity.
 
         Args:
             entity_or_id: The entity or its entity_id
             asset_id: The asset ID
+            delete_gallery_image: If True, also delete the underlying gallery
+                image. This prevents orphaned images from accumulating in the
+                campaign gallery.
 
         Returns:
             True if successful
         """
         entity_id = self._extract_entity_id(entity_or_id)
+
+        gallery_uuid: str | None = None
+        if delete_gallery_image:
+            asset = self.get_asset(entity_id, asset_id)
+            gallery_uuid = self._extract_gallery_uuid(asset.url)
+
         url = f"entities/{entity_id}/entity_assets/{asset_id}"
         self.client._request("DELETE", url)
+
+        if gallery_uuid:
+            with contextlib.suppress(NotFoundError):
+                self.client.gallery_delete(gallery_uuid)
+
         return True
 
     @property

{python_kanka-2.4.0 → python_kanka-2.5.0}/tests/integration/test_entity_assets_integration.py

@@ -55,6 +55,22 @@ class TestEntityAssetIntegration(IntegrationTestBase):
             f"Delete character '{name}' (ID: {character_id})", cleanup
         )
 
+    def _register_gallery_cleanup(self, asset_url: str | None):
+        """Register gallery image cleanup from an asset's CDN URL."""
+        from kanka.exceptions import NotFoundError
+        from kanka.managers import EntityManager
+
+        gallery_uuid = EntityManager._extract_gallery_uuid(asset_url)
+        if not gallery_uuid:
+            return
+
+        def cleanup():
+            if self.client:
+                with contextlib.suppress(NotFoundError):
+                    self.client.gallery_delete(gallery_uuid)
+
+        self.register_cleanup(f"Delete gallery image '{gallery_uuid}'", cleanup)
+
     def test_create_file_asset(self):
         """Test creating a file asset on an entity."""
         character = self.client.characters.create(
@@ -68,6 +84,7 @@ class TestEntityAssetIntegration(IntegrationTestBase):
         asset = self.client.characters.create_file_asset(
             character, image_path, name="test-file-asset"
         )
+        self._register_gallery_cleanup(asset.url)
 
         self.assert_not_none(asset.id, "Asset ID should not be None")
         self.assert_equal(asset.type_id, 1, "File asset type_id should be 1")
@@ -131,6 +148,7 @@ class TestEntityAssetIntegration(IntegrationTestBase):
         file_asset = self.client.characters.create_file_asset(
             character, image_path, name="list-test-file"
         )
+        self._register_gallery_cleanup(file_asset.url)
 
         self.wait_for_api()
 
@@ -177,6 +195,7 @@ class TestEntityAssetIntegration(IntegrationTestBase):
         created = self.client.characters.create_file_asset(
             character, image_path, name="get-test-asset"
         )
+        self._register_gallery_cleanup(created.url)
 
         self.wait_for_api()
 
@@ -202,6 +221,7 @@ class TestEntityAssetIntegration(IntegrationTestBase):
             character, image_path, name="delete-test-asset"
         )
         asset_id = asset.id
+        self._register_gallery_cleanup(asset.url)
 
         self.wait_for_api()
 
@@ -220,6 +240,134 @@ class TestEntityAssetIntegration(IntegrationTestBase):
 
         print(f"  Deleted asset {asset_id}")
 
+    def test_delete_asset_with_gallery_cleanup(self):
+        """Test deleting an asset also deletes the gallery image."""
+        from kanka.managers import EntityManager
+
+        character = self.client.characters.create(
+            name=f"Integration Test Assets - DELETE ME - {datetime.now().isoformat()}"
+        )
+        self._register_character_cleanup(character.id, character.name)
+
+        self.wait_for_api()
+
+        image_path = self._create_test_image()
+        asset = self.client.characters.create_file_asset(
+            character, image_path, name="gallery-cleanup-test"
+        )
+        asset_id = asset.id
+        asset_url = asset.url
+        self.assert_not_none(asset_url, "Asset should have a CDN URL")
+
+        # Extract gallery UUID from the URL
+        gallery_uuid = EntityManager._extract_gallery_uuid(asset_url)
+        print(f"  Created asset {asset_id} with gallery UUID: {gallery_uuid}")
+
+        if gallery_uuid:
+            # Verify gallery image exists before deletion
+            self.wait_for_api()
+            gallery_image = self.client.gallery_get(gallery_uuid)
+            self.assert_not_none(
+                gallery_image, "Gallery image should exist before delete"
+            )
+            print(f"  Gallery image confirmed: {gallery_image.id}")
+
+        self.wait_for_api()
+
+        # Delete with gallery cleanup
+        result = self.client.characters.delete_asset(
+            character, asset_id, delete_gallery_image=True
+        )
+        self.assert_true(result, "delete_asset should return True")
+
+        self.wait_for_api()
+
+        # Verify the entity asset is gone
+        assets = self.client.characters.list_assets(character)
+        asset_ids = {a.id for a in assets}
+        self.assert_true(
+            asset_id not in asset_ids,
+            f"Deleted asset {asset_id} should not appear in list",
+        )
+
+        # Verify gallery image is also gone
+        if gallery_uuid:
+            from kanka.exceptions import NotFoundError
+
+            try:
+                self.client.gallery_get(gallery_uuid)
+                self.assert_true(False, "Gallery image should have been deleted")
+            except NotFoundError:
+                pass  # Expected
+
+        print(f"  Deleted asset {asset_id} and gallery image {gallery_uuid}")
+
+    def test_managed_image_update_cleans_gallery(self):
+        """Test that updating managed images cleans up gallery orphans."""
+        from kanka.managers import EntityManager
+
+        character = self.client.characters.create(
+            name=f"Integration Test Assets - DELETE ME - {datetime.now().isoformat()}"
+        )
+        self._register_character_cleanup(character.id, character.name)
+
+        self.wait_for_api()
+
+        # Create with an image
+        image_path_1 = self._create_test_image(prefix="managed_v1")
+        character = self.client.characters.update(
+            character,
+            entry='<p><img src="test.png" /> Hello</p>',
+            images={"test.png": image_path_1},
+        )
+
+        self.wait_for_api()
+
+        # Find the managed asset and its gallery UUID
+        assets = self.client.characters.list_assets(character)
+        managed = [a for a in assets if EntityManager._parse_managed_asset_name(a.name)]
+        self.assert_equal(len(managed), 1, "Should have 1 managed asset")
+        old_uuid = EntityManager._extract_gallery_uuid(managed[0].url)
+        print(f"  First image gallery UUID: {old_uuid}")
+
+        self.wait_for_api()
+
+        # Update with a different image (write different bytes)
+        image_path_2 = self._create_test_image(prefix="managed_v2")
+        # Write different content to ensure different hash
+        with open(image_path_2, "ab") as f:
+            f.write(b"extra bytes to change hash")
+
+        character = self.client.characters.update(
+            character,
+            entry='<p><img src="test.png" /> Updated</p>',
+            images={"test.png": image_path_2},
+        )
+
+        self.wait_for_api()
+
+        # Verify old gallery image is cleaned up
+        if old_uuid:
+            from kanka.exceptions import NotFoundError
+
+            try:
+                self.client.gallery_get(old_uuid)
+                self.assert_true(False, "Old gallery image should have been deleted")
+            except NotFoundError:
+                pass  # Expected
+
+        # Verify new asset exists
+        assets = self.client.characters.list_assets(character)
+        managed = [a for a in assets if EntityManager._parse_managed_asset_name(a.name)]
+        self.assert_equal(len(managed), 1, "Should still have 1 managed asset")
+        new_uuid = EntityManager._extract_gallery_uuid(managed[0].url)
+        self.assert_true(
+            new_uuid != old_uuid, "New gallery UUID should differ from old"
+        )
+
+        print(f"  New image gallery UUID: {new_uuid}")
+        print("  Old gallery image was properly cleaned up")
+
     def run_all_tests(self):
         """Run all entity asset integration tests."""
         tests = [
@@ -229,6 +377,14 @@ class TestEntityAssetIntegration(IntegrationTestBase):
             ("Entity Asset - List", self.test_list_assets),
             ("Entity Asset - Get", self.test_get_asset),
             ("Entity Asset - Delete", self.test_delete_asset),
+            (
+                "Entity Asset - Delete with Gallery Cleanup",
+                self.test_delete_asset_with_gallery_cleanup,
+            ),
+            (
+                "Entity Asset - Managed Image Update Cleans Gallery",
+                self.test_managed_image_update_cleans_gallery,
+            ),
         ]
 
         results = []

{python_kanka-2.4.0 → 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."""