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

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

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

{python_kanka-2.4.1 → python_kanka-2.6.0}/.github/workflows/publish.yml

@@ -56,7 +56,7 @@ jobs:
         uv build
 
     - name: Upload artifacts
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@v6
       with:
         name: dist
         path: dist/
@@ -71,7 +71,7 @@ jobs:
 
     steps:
     - name: Download artifacts
-      uses: actions/download-artifact@v6
+      uses: actions/download-artifact@v7
       with:
         name: dist
         path: dist/

{python_kanka-2.4.1 → python_kanka-2.6.0}/CLAUDE.md

@@ -142,6 +142,46 @@ Integration tests are NOT pytest tests - they have custom runners:
    - **Available in Kanka API but not yet implemented**: Timeline, Item, Relation, DiceRoll, Conversation, AttributeTemplate, Bookmark, Ability, Map, Inventory
    - **Never existed/removed**: EntityNote, EntityEvent, Attribute, Species
 
+## Version Bumping
+
+This project uses `bump2version` for version management. The version is tracked in three files:
+- `pyproject.toml` — package version
+- `src/kanka/_version.py` — runtime version
+- `.bumpversion.cfg` — bump2version's own tracking (must stay in sync)
+
+**To bump the version:**
+
+```bash
+# Patch (bug fixes): 2.4.1 → 2.4.2
+uv run bump2version patch
+
+# Minor (new features): 2.4.1 → 2.5.0
+uv run bump2version minor
+
+# Major (breaking changes): 2.4.1 → 3.0.0
+uv run bump2version major
+```
+
+This automatically:
+1. Updates the version in `pyproject.toml`, `src/kanka/_version.py`, and `.bumpversion.cfg`
+2. Creates a commit with message `Bump version: X.Y.Z → A.B.C`
+3. Creates a git tag `vA.B.C`
+
+**After bumping, always run `uv sync`** to update `uv.lock`, then amend the lock file into the bump commit and retag:
+
+```bash
+uv sync
+git add uv.lock
+git commit --amend --no-edit
+git tag -d vA.B.C
+git tag vA.B.C
+```
+
+**Important notes:**
+- The working tree must be clean before running bump2version (use `--allow-dirty` only if `.bumpversion.cfg` is the dirty file due to a sync fix)
+- If `.bumpversion.cfg`'s `current_version` is out of sync with the actual version in `pyproject.toml`, fix it manually before bumping
+- Use `feat` commits → minor bump, `fix` commits → patch bump
+
 ## Development Preferences
 
 - When executing test scripts with long output, redirect to file for parsing
@@ -204,6 +244,7 @@ When testing against the real API:
 - `docs/assets-and-images.md` — Assets, images, automatic image management
 - `docs/gallery.md` — Campaign gallery
 - `docs/search-and-filtering.md` — Search and filtering
+- `docs/last-sync.md` — Incremental sync using lastSync/sync
 - `docs/pagination.md` — Pagination
 - `docs/error-handling.md` — Exception types and patterns
 - `docs/rate-limiting.md` — Rate limit configuration

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-kanka
-Version: 2.4.1
+Version: 2.6.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.6.0}/docs/README.md

@@ -12,6 +12,7 @@ A modern Python client for the [Kanka API](https://app.kanka.io/api-docs/1.0), t
 | [Entity Types Reference](entity-types-reference.md) | All 12 entity types with their specific fields |
 | [Posts](posts.md) | Attach notes and comments to any entity |
 | [Search and Filtering](search-and-filtering.md) | Global search, entities endpoint, list filters |
+| [Last Sync](last-sync.md) | Incremental sync using the lastSync/sync mechanism |
 | [Pagination](pagination.md) | Navigate large result sets |
 | [Assets and Images](assets-and-images.md) | File/link/alias assets, entity images, automatic image management |
 | [Campaign Gallery](gallery.md) | Campaign-level image storage |

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

@@ -90,12 +90,27 @@ 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,
+    last_sync: str | None = None,
+    **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 |
+| `last_sync` | `str \| None` | `None` | Only return entities modified after this ISO 8601 timestamp. See [Last Sync](last-sync.md). |
+| `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,8 +152,13 @@ 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_entities_sync` | `str \| None` | Sync timestamp from last `entities()` call. See [Last Sync](last-sync.md). |
 | `last_search_meta` | `dict` | Pagination metadata from last `search()` |
 | `last_search_links` | `dict` | Pagination links from last `search()` |
+| `last_search_sync` | `str \| None` | Sync timestamp from last `search()` call |
 | `last_gallery_meta` | `dict` | Pagination metadata from last `gallery()` |
 | `last_gallery_links` | `dict` | Pagination links from last `gallery()` |
 
@@ -191,6 +211,7 @@ list(
     page: int = 1,
     limit: int = 30,
     related: bool = False,
+    last_sync: str | None = None,
     **filters,
 ) → list[T]
 ```
@@ -202,6 +223,7 @@ List entities with optional filtering.
 | `page` | `int` | `1` | Page number |
 | `limit` | `int` | `30` | Results per page |
 | `related` | `bool` | `False` | Include posts and attributes |
+| `last_sync` | `str \| None` | `None` | Only return entities modified after this ISO 8601 timestamp. See [Last Sync](last-sync.md). |
 | `name` | `str` | — | Filter by name (partial match) |
 | `type` | `str` | — | Filter by entity type |
 | `types` | `list[str]` | — | Filter by multiple types |
@@ -211,7 +233,6 @@ List entities with optional filtering.
 | `updated_at` | `str` | — | Filter by update date |
 | `created_by` | `int` | — | Filter by creator ID |
 | `updated_by` | `int` | — | Filter by updater ID |
-| `lastSync` | `str` | — | Only entities modified after this ISO 8601 timestamp |
 
 **Returns:** List of entity model instances
 
@@ -426,6 +447,7 @@ delete_image(entity_or_id: T | int, is_header: bool = False) → bool
 | `pagination_meta` | `dict` | Metadata from last `list()` |
 | `pagination_links` | `dict` | Links from last `list()` |
 | `has_next_page` | `bool` | Whether next page exists |
+| `last_sync` | `str \| None` | Sync timestamp from last `list()` call. See [Last Sync](last-sync.md). |
 | `last_page_meta` | `dict` | Alias for `pagination_meta` |
 | `last_page_links` | `dict` | Alias for `pagination_links` |
 | `last_posts_meta` | `dict` | Metadata from last `list_posts()` |

{python_kanka-2.4.1 → python_kanka-2.6.0}/docs/entities.md

@@ -72,15 +72,17 @@ results = client.characters.list(
 )
 ```
 
-### The `lastSync` Filter
+### The `last_sync` Parameter
 
-Use the `lastSync` filter with an ISO 8601 timestamp to retrieve only entities modified after a specific time. This is useful for synchronization workflows:
+Use the `last_sync` parameter with an ISO 8601 timestamp to retrieve only entities modified after a specific time. This is useful for keeping a local cache in sync with Kanka without re-fetching everything. See [Last Sync](last-sync.md) for a complete guide including pagination, persistence, and important caveats.
 
 ```python
-from datetime import datetime, timedelta, timezone
+# Fetch all characters, capturing the sync timestamp
+characters = client.characters.list(page=1, limit=100)
+sync_timestamp = client.characters.last_sync
 
-last_sync = (datetime.now(timezone.utc) - timedelta(hours=24)).isoformat()
-updated = client.characters.list(lastSync=last_sync, related=True)
+# Later, fetch only characters that changed since then
+updated = client.characters.list(last_sync=sync_timestamp)
 ```
 
 ### Iterating All Pages

python_kanka-2.6.0/docs/last-sync.md

@@ -0,0 +1,132 @@
+# Last Sync
+
+The Kanka API provides a synchronization mechanism that lets you efficiently fetch only entities that have changed since your last request. This avoids repeatedly downloading your entire campaign and is essential for applications that need to keep a local cache or database in sync with Kanka.
+
+## How It Works
+
+Every list response from the Kanka API includes a top-level `sync` timestamp. This timestamp represents the exact moment the server processed your request. To get only entities that changed since then, pass that timestamp back as the `last_sync` parameter on your next request. The API returns only entities created or modified after that timestamp.
+
+The workflow is:
+
+1. **Initial fetch** — Call the API without `last_sync`. Capture the sync timestamp from the response.
+2. **Subsequent fetches** — Call the API with `last_sync` set to the previously captured value. Only modified entities are returned. Capture the new sync timestamp for next time.
+3. **Repeat** — Each call gives you a new sync timestamp to use on the next call.
+
+## Using last_sync with Entity Managers
+
+The `last_sync` parameter is a named parameter on all entity manager `list()` calls. After each call, the sync timestamp is available via the `last_sync` property.
+
+```python
+from kanka import KankaClient
+
+client = KankaClient(token="your-token", campaign_id=12345)
+
+# Initial fetch — get all characters
+characters = client.characters.list(page=1, limit=100)
+sync_timestamp = client.characters.last_sync
+print(f"Fetched {len(characters)} characters")
+print(f"Sync timestamp: {sync_timestamp}")
+
+# ... later, fetch only characters that changed ...
+updated = client.characters.list(last_sync=sync_timestamp)
+new_sync = client.characters.last_sync
+print(f"{len(updated)} characters changed since last sync")
+```
+
+## Using last_sync with the Generic Entities Endpoint
+
+The generic `client.entities()` endpoint also supports `last_sync` as a named parameter. This is useful when you want to sync all entity types at once rather than syncing each type separately. The sync timestamp is available via the `last_entities_sync` property.
+
+```python
+# Initial fetch — get all entities
+entities = client.entities(page=1, limit=100)
+sync_timestamp = client.last_entities_sync
+
+# ... later, fetch only entities that changed ...
+updated = client.entities(last_sync=sync_timestamp)
+new_sync = client.last_entities_sync
+print(f"{len(updated)} entities changed since last sync")
+```
+
+## Paginating with last_sync
+
+When your campaign has more entities than fit in a single page, you need to paginate through all pages on both the initial fetch and on subsequent syncs. Use the same `last_sync` value across all pages of a single sync operation, and capture the sync timestamp from the **first** page to use for the next sync.
+
+```python
+def sync_all_characters(client, last_sync=None):
+    """Fetch all characters, optionally only those changed since last_sync."""
+    all_characters = []
+    page = 1
+    next_sync = None
+
+    while True:
+        batch = client.characters.list(
+            page=page, limit=100, last_sync=last_sync
+        )
+        all_characters.extend(batch)
+
+        # Capture sync timestamp from the first page
+        if page == 1:
+            next_sync = client.characters.last_sync
+
+        if not client.characters.has_next_page:
+            break
+        page += 1
+
+    return all_characters, next_sync
+
+
+# Initial full sync
+characters, sync_timestamp = sync_all_characters(client)
+print(f"Full sync: {len(characters)} characters")
+
+# ... time passes, entities are modified in Kanka ...
+
+# Incremental sync — only fetches what changed
+changed, sync_timestamp = sync_all_characters(client, last_sync=sync_timestamp)
+print(f"Incremental sync: {len(changed)} characters changed")
+```
+
+## Persisting the Sync Timestamp
+
+For the sync pattern to work across application restarts, you need to persist the sync timestamp. How you store it depends on your application — a file, database, or configuration store all work:
+
+```python
+import json
+from pathlib import Path
+
+SYNC_FILE = Path("kanka_sync_state.json")
+
+
+def load_sync_state():
+    """Load the last sync timestamp from disk."""
+    if SYNC_FILE.exists():
+        return json.loads(SYNC_FILE.read_text())
+    return {}
+
+
+def save_sync_state(state):
+    """Save the sync timestamp to disk."""
+    SYNC_FILE.write_text(json.dumps(state, indent=2))
+
+
+# Load previous state
+state = load_sync_state()
+
+# Sync characters
+characters, new_sync = sync_all_characters(
+    client, last_sync=state.get("characters_sync")
+)
+state["characters_sync"] = new_sync
+
+# Save state for next run
+save_sync_state(state)
+```
+
+## Important Notes
+
+- **The sync timestamp is server-generated.** Always use the value from the API response rather than generating your own timestamp. This avoids clock skew issues between your machine and the Kanka server.
+- **`last_sync` filters by modification time.** It returns entities that were created or updated after the given timestamp. It does **not** tell you about deleted entities.
+- **Deleted entities are not included.** The `last_sync` response only contains entities that still exist. If you maintain a local cache, you may need a separate mechanism to detect deletions (e.g., periodically doing a full sync and comparing IDs).
+- **Use ISO 8601 format.** The sync value from the API is already in the correct format. If you construct a timestamp manually, use full ISO 8601 with timezone (e.g., `2026-02-25T01:35:39.768695Z`).
+- **Works with all filters.** You can combine `last_sync` with other filters like `type`, `name`, or `tags`. The API returns entities matching all filters that were also modified after the `last_sync` timestamp.

{python_kanka-2.4.1 → python_kanka-2.6.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.6.0}/docs/search-and-filtering.md

@@ -137,7 +137,7 @@ results = client.characters.list(
 | `updated_at` | `str` | Filter by update date (ISO format, supports `>=` prefix) |
 | `created_by` | `int` | Filter by creator user ID |
 | `updated_by` | `int` | Filter by last updater user ID |
-| `lastSync` | `str` | Only return entities modified after this ISO 8601 timestamp |
+| `last_sync` | `str` | Only return entities modified after this ISO 8601 timestamp |
 
 ### Filter Value Handling
 
@@ -147,14 +147,7 @@ results = client.characters.list(
 
 ### Sync Filter
 
-The `lastSync` filter is useful for synchronization workflows — it returns only entities that have been modified since the given timestamp:
-
-```python
-from datetime import datetime, timedelta, timezone
-
-last_sync = (datetime.now(timezone.utc) - timedelta(hours=24)).isoformat()
-updated_chars = client.characters.list(lastSync=last_sync, related=True)
-```
+The `last_sync` parameter returns only entities modified since a given timestamp. Each API response includes a sync timestamp (available via the `last_sync` property) that you should capture and reuse. See [Last Sync](last-sync.md) for a complete guide including the full sync workflow, pagination, persistence, and important caveats.
 
 ## Choosing the Right Approach
 

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

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

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

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

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

@@ -298,9 +298,10 @@ class KankaClient:
         params: dict[str, int | str] = {"page": page}
         response = self._request("GET", f"search/{term}", params=params)
 
-        # Store pagination metadata for access if needed
+        # Store pagination metadata and sync timestamp for access if needed
         self._last_search_meta = response.get("meta", {})
         self._last_search_links = response.get("links", {})
+        self._last_search_sync: str | None = response.get("sync")
 
         return [SearchResult(**item) for item in response["data"]]
 
@@ -321,19 +322,42 @@ 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,
+        last_sync: str | None = None,
+        **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)
+            last_sync: ISO 8601 timestamp; only return entities modified after
+                this time. Use the ``last_entities_sync`` property from a
+                previous call to implement incremental sync.
             **filters: Filter parameters like types, name, is_private, tags
 
         Returns:
             List of entity data
+
+        Note:
+            After calling entities(), the following properties are available:
+            - 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
+            - client.last_entities_sync: Server-generated sync timestamp for use
+              with the ``last_sync`` parameter on subsequent calls
         """
-        params: dict[str, int | str] = {}
+        params: dict[str, int | str] = {"page": page, "limit": limit}
+
+        # Add lastSync parameter for incremental sync
+        if last_sync is not None:
+            params["lastSync"] = last_sync
 
         # Handle special filters
         if "types" in filters and isinstance(filters["types"], list):
@@ -355,6 +379,9 @@ 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", {})
+        self._last_entities_sync: str | None = response.get("sync")
         return response["data"]  # type: ignore[no-any-return]
 
     def _parse_rate_limit_headers(self, response) -> float | None:
@@ -692,3 +719,49 @@ class KankaClient:
             Dict[str, Any]: Links for pagination including first, last, prev, next URLs
         """
         return getattr(self, "_last_search_links", {})
+
+    @property
+    def last_search_sync(self) -> str | None:
+        """Get the sync timestamp from the last search() call.
+
+        Returns:
+            The sync timestamp string, or None if search() has not been called.
+        """
+        return getattr(self, "_last_search_sync", None)
+
+    @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 last_entities_sync(self) -> str | None:
+        """Get the sync timestamp from the last entities() call.
+
+        This is a server-generated ISO 8601 timestamp representing when the
+        response was produced. Pass it as the ``last_sync`` parameter on a
+        subsequent ``entities()`` call to fetch only entities modified since then.
+
+        Returns:
+            The sync timestamp string, or None if entities() has not been called.
+        """
+        return getattr(self, "_last_entities_sync", None)
+
+    @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.6.0}/src/kanka/managers.py

@@ -80,7 +80,12 @@ class EntityManager[T: Entity]:
         return bool(self.pagination_links.get("next"))
 
     def list(
-        self, page: int = 1, limit: int = 30, related: bool = False, **filters
+        self,
+        page: int = 1,
+        limit: int = 30,
+        related: bool = False,
+        last_sync: str | None = None,
+        **filters,
     ) -> list[T]:
         """List entities with optional filters.
 
@@ -88,6 +93,9 @@ class EntityManager[T: Entity]:
             page: Page number (default: 1)
             limit: Number of results per page (default: 30)
             related: Include related data (posts, attributes, etc.)
+            last_sync: ISO 8601 timestamp; only return entities modified after
+                this time. Use the ``last_sync`` property from a previous call
+                to implement incremental sync.
             **filters: Additional filters supported by the API
 
         Supported filters:
@@ -104,10 +112,12 @@ class EntityManager[T: Entity]:
             List of entity instances
 
         Note:
-            Pagination information is available after calling list():
+            After calling list(), the following properties are available:
             - manager.pagination_meta: Contains total count, current page, etc.
             - manager.pagination_links: Contains URLs for first, last, prev, next
             - manager.has_next_page: True if more pages are available
+            - manager.last_sync: Server-generated sync timestamp for use with
+              the ``last_sync`` parameter on subsequent calls
 
         Examples:
             # Get all public characters
@@ -154,6 +164,10 @@ class EntityManager[T: Entity]:
         if related:
             params["related"] = 1
 
+        # Add lastSync parameter for incremental sync
+        if last_sync is not None:
+            params["lastSync"] = last_sync
+
         # Add filters
         for key, value in filters.items():
             if value is not None:
@@ -175,9 +189,10 @@ class EntityManager[T: Entity]:
 
         response = self.client._request("GET", self.endpoint, params=params)
 
-        # Store pagination metadata on the manager for access if needed
+        # Store pagination metadata and sync timestamp for access if needed
         self._last_meta = response.get("meta", {})
         self._last_links = response.get("links", {})
+        self._last_sync: str | None = response.get("sync")
 
         return [self.model(**item) for item in response["data"]]
 
@@ -379,6 +394,19 @@ class EntityManager[T: Entity]:
         """
         return getattr(self, "_last_links", {})
 
+    @property
+    def last_sync(self) -> str | None:
+        """Get the sync timestamp from the last list() call.
+
+        This is a server-generated ISO 8601 timestamp representing when the
+        response was produced. Pass it as the ``last_sync`` parameter on a
+        subsequent ``list()`` call to fetch only entities modified since then.
+
+        Returns:
+            The sync timestamp string, or None if list() has not been called.
+        """
+        return getattr(self, "_last_sync", None)
+
     def _extract_entity_id(self, entity_or_id: T | int) -> int:
         """Extract entity_id from an entity object or integer.