python-kanka 2.4.1__py3-none-any.whl → 2.6.0__py3-none-any.whl

kanka/_version.py

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

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"))

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.
 

{python_kanka-2.4.1.dist-info → python_kanka-2.6.0.dist-info}/METADATA

@@ -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.dist-info → python_kanka-2.6.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
 kanka/__init__.py,sha256=S_Pl6xBtHOpUGr3eOEkq4QEMtByZx4kEWYoQfv3LLrQ,2102
-kanka/_version.py,sha256=LJp15KIx293LmYX1MeDE6Vp2LHSdIUmILx4kcqA0wcI,67
-kanka/client.py,sha256=AVLFcrLCwMfof-oTuUuzfNFe10k4Ai2JCkkncfv6YYY,23598
+kanka/_version.py,sha256=P6p0L1OUViSUGyScSsOQ9rEhgsRzs8E-Td230MFMta8,67
+kanka/client.py,sha256=obnGFpdXwPRQAbxeaL_UvAqsHiEL7h_bYqh1GROlBaY,26632
 kanka/exceptions.py,sha256=A4P7T7VO_Rp5IYldvFaecE3z4N7WYDgCDojYPu_yDzk,3871
-kanka/managers.py,sha256=QQN4HX8CDyx8zLvJ2Bvh8f-h7xGy8E7ClY4CnYMlK5E,34225
+kanka/managers.py,sha256=OExFz64XdVSCP3zOnn8D_eUonNZLhDL-gd9v0zgvj-w,35343
 kanka/py.typed,sha256=mZgbv7X8oKfyMzYIbodUlHrC15905jgP-ZbYviEIL18,86
 kanka/types.py,sha256=onIdSW-3rh6Bqv2VTvx6INFa7tkaQxqg6gJkiAh8YGA,262
 kanka/models/__init__.py,sha256=IFdzawDK_lhS50puRunnZZalh2S5DOPU96ASHeFITUw,1329
 kanka/models/base.py,sha256=GOt9I2eNb-R_2oD0fbU0LE3y9gWL0x3_2SQ9I5yuq3Y,4037
 kanka/models/common.py,sha256=0RF33RupotK0mWjvWc9oIdQZF7ko5FNc_GG5wUIZOOE,6682
 kanka/models/entities.py,sha256=-2ztBZn8-K8czQyd9vPnEtn4eS666v9firmk7UPDT5A,8885
-python_kanka-2.4.1.dist-info/METADATA,sha256=JNCuezpUMuIacUrIWkV2XIXc_Y3wPhkbI4ScoQccZ38,3249
-python_kanka-2.4.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-python_kanka-2.4.1.dist-info/licenses/LICENSE,sha256=37op2CRJ_dU2qGU-iJjczcP-ljtJjpKAgBdKFaiF2GY,1067
-python_kanka-2.4.1.dist-info/RECORD,,
+python_kanka-2.6.0.dist-info/METADATA,sha256=X10zzfn_ePoL9ZR4FFb0vk3oMjrm8Tn_7qSLCY_g3EM,3249
+python_kanka-2.6.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_kanka-2.6.0.dist-info/licenses/LICENSE,sha256=37op2CRJ_dU2qGU-iJjczcP-ljtJjpKAgBdKFaiF2GY,1067
+python_kanka-2.6.0.dist-info/RECORD,,

{python_kanka-2.4.1.dist-info → python_kanka-2.6.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.28.0
+Generator: hatchling 1.29.0
 Root-Is-Purelib: true
 Tag: py3-none-any