karakeep-python-api 0.2.1__tar.gz → 0.2.3__tar.gz

{karakeep_python_api-0.2.1/karakeep_python_api.egg-info → karakeep_python_api-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 0.2.1
+Version: 0.2.3
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3
@@ -243,7 +243,12 @@ except Exception as e:
 
 Examples of the API being used can be found in the [`./examples`](./examples) folder. Don't hesitate to submit yours!
 
--   **Omnivore Archiving Status Updater**: A script to fix the archive status of bookmarks imported from Omnivore into Karakeep. See [`examples/omnivore_archiving_status_updater/README.md`](./examples/omnivore_archiving_status_updater/README.md) for details.
+| Example Script | Description | Documentation |
+|----------------|-------------|---------------|
+| **Add Time-to-Read Tags** | Automatically adds time-to-read tags (`0-5m`, `5-10m`, etc.) to bookmarks based on content length analysis. | [`README.md`](./examples/add_time_to_read_tag/README.md) |
+| **List to Tag Converter** | Converts a Karakeep list into tags by adding a specified tag to all bookmarks within that list. | [`README.md`](./examples/list_to_tag/README.md) |
+| **Omnivore Archiving Status Updater** | Fixes the archived status of bookmarks imported from Omnivore by reading export data and updating Karakeep accordingly. | [`README.md`](./examples/omnivore_archiving_status_updater/README.md) |
+| **Pocket Archiving Status Updater** | Fixes the archived status of bookmarks imported from Pocket by reading export data and updating Karakeep accordingly. | [`README.md`](./examples/pocket_archiving_status_updater/README.md) |
 
 ## Development
 

{karakeep_python_api-0.2.1 → karakeep_python_api-0.2.3}/README.md

@@ -208,7 +208,12 @@ except Exception as e:
 
 Examples of the API being used can be found in the [`./examples`](./examples) folder. Don't hesitate to submit yours!
 
--   **Omnivore Archiving Status Updater**: A script to fix the archive status of bookmarks imported from Omnivore into Karakeep. See [`examples/omnivore_archiving_status_updater/README.md`](./examples/omnivore_archiving_status_updater/README.md) for details.
+| Example Script | Description | Documentation |
+|----------------|-------------|---------------|
+| **Add Time-to-Read Tags** | Automatically adds time-to-read tags (`0-5m`, `5-10m`, etc.) to bookmarks based on content length analysis. | [`README.md`](./examples/add_time_to_read_tag/README.md) |
+| **List to Tag Converter** | Converts a Karakeep list into tags by adding a specified tag to all bookmarks within that list. | [`README.md`](./examples/list_to_tag/README.md) |
+| **Omnivore Archiving Status Updater** | Fixes the archived status of bookmarks imported from Omnivore by reading export data and updating Karakeep accordingly. | [`README.md`](./examples/omnivore_archiving_status_updater/README.md) |
+| **Pocket Archiving Status Updater** | Fixes the archived status of bookmarks imported from Pocket by reading export data and updating Karakeep accordingly. | [`README.md`](./examples/pocket_archiving_status_updater/README.md) |
 
 ## Development
 

{karakeep_python_api-0.2.1 → karakeep_python_api-0.2.3}/karakeep_python_api/karakeep_api.py

@@ -85,7 +85,7 @@ class KarakeepAPI:
     """
 
     # Version reflects the client library version, updated by bumpver
-    VERSION: str = "0.2.1"
+    VERSION: str = "0.2.3"
 
     def __init__(
         self,
@@ -955,16 +955,18 @@ class KarakeepAPI:
 
     @optional_typecheck
     def attach_tags_to_a_bookmark(
-        self, bookmark_id: str, tags_data: dict
+        self,
+        bookmark_id: str,
+        tag_ids: Optional[List[str]] = None,
+        tag_names: Optional[List[str]] = None,
     ) -> Dict[str, Any]:
         """
         Attach one or more tags to a bookmark. Corresponds to POST /bookmarks/{bookmarkId}/tags.
 
         Args:
             bookmark_id: The ID (string) of the bookmark.
-            tags_data: Dictionary specifying the tags to attach. Must contain a "tags" key
-                       which is a list of objects, each having *either* "tagId" (string) *or* "tagName" (string).
-                       Example: `{"tags": [{"tagId": "existing_tag_id"}, {"tagName": "new_or_existing_tag_name"}]}`
+            tag_ids: List of existing tag IDs to attach (optional).
+            tag_names: List of tag names to attach (will create tags if they don't exist) (optional).
 
         Returns:
             dict: A dictionary containing the list of attached tag IDs under the key "attached".
@@ -972,38 +974,49 @@ class KarakeepAPI:
                   Validation is not performed on this response type by default.
 
         Raises:
-            ValueError: If tags_data structure is invalid.
+            ValueError: If no tags are provided or if arguments are invalid.
             APIError: If the API request fails (e.g., 404 bookmark not found).
         """
-        # Validate the tags_data structure
-        if not isinstance(tags_data, dict):
-            raise ValueError("tags_data must be a dictionary")
+        # Validate that at least one tag source is provided
+        if not tag_ids and not tag_names:
+            raise ValueError("At least one of 'tag_ids' or 'tag_names' must be provided")
 
-        if "tags" not in tags_data:
-            raise ValueError("tags_data must contain a 'tags' key")
+        # Validate input types
+        if tag_ids is not None and not isinstance(tag_ids, list):
+            raise ValueError("'tag_ids' must be a list of strings")
 
-        tags_list = tags_data["tags"]
-        if not isinstance(tags_list, list):
-            raise ValueError("The 'tags' value must be a list")
+        if tag_names is not None and not isinstance(tag_names, list):
+            raise ValueError("'tag_names' must be a list of strings")
 
-        # Validate each tag object in the list
-        for i, tag in enumerate(tags_list):
-            if not isinstance(tag, dict):
-                raise ValueError(f"Tag at index {i} must be a dictionary")
+        # Validate individual elements
+        if tag_ids:
+            for i, tag_id in enumerate(tag_ids):
+                if not isinstance(tag_id, str) or not tag_id.strip():
+                    raise ValueError(f"Tag ID at index {i} must be a non-empty string")
 
-            has_tag_id = "tagId" in tag
-            has_tag_name = "tagName" in tag
+        if tag_names:
+            for i, tag_name in enumerate(tag_names):
+                if not isinstance(tag_name, str) or not tag_name.strip():
+                    raise ValueError(f"Tag name at index {i} must be a non-empty string")
 
-            if not has_tag_id and not has_tag_name:
-                raise ValueError(
-                    f"Tag at index {i} must contain either 'tagId' or 'tagName'"
-                )
+        # Construct the tags_data dict in the format expected by the API
+        tags_list = []
+
+        if tag_ids:
+            for tag_id in tag_ids:
+                tags_list.append({"tagId": tag_id.strip()})
+
+        if tag_names:
+            for tag_name in tag_names:
+                tags_list.append({"tagName": tag_name.strip()})
 
-            if has_tag_id and not isinstance(tag["tagId"], str):
-                raise ValueError(f"Tag at index {i}: 'tagId' must be a string")
+        tags_data = {"tags": tags_list}
 
-            if has_tag_name and not isinstance(tag["tagName"], str):
-                raise ValueError(f"Tag at index {i}: 'tagName' must be a string")
+        # Optional validation using Tag datatype if validation is enabled
+        if not self.disable_response_validation:
+            # Validate the constructed structure matches expected format
+            # This is primarily for development/debugging purposes
+            logger.debug("Validating constructed tags_data structure")
 
         endpoint = f"bookmarks/{bookmark_id}/tags"
         response_data = self._call("POST", endpoint, data=tags_data)
@@ -1013,16 +1026,18 @@ class KarakeepAPI:
 
     @optional_typecheck
     def detach_tags_from_a_bookmark(
-        self, bookmark_id: str, tags_data: dict
+        self,
+        bookmark_id: str,
+        tag_ids: Optional[List[str]] = None,
+        tag_names: Optional[List[str]] = None,
     ) -> Dict[str, Any]:
         """
         Detach one or more tags from a bookmark. Corresponds to DELETE /bookmarks/{bookmarkId}/tags.
 
         Args:
             bookmark_id: The ID (string) of the bookmark.
-            tags_data: Dictionary specifying the tags to detach. Must contain a "tags" key
-                       which is a list of objects, each having *either* "tagId" (string) *or* "tagName" (string).
-                       Example: `{"tags": [{"tagId": "tag_id_to_remove"}, {"tagName": "tag_name_to_remove"}]}`
+            tag_ids: List of existing tag IDs to detach (optional).
+            tag_names: List of tag names to detach (optional).
 
         Returns:
             dict: A dictionary containing the list of detached tag IDs under the key "detached".
@@ -1030,38 +1045,49 @@ class KarakeepAPI:
                   Validation is not performed on this response type by default.
 
         Raises:
-            ValueError: If tags_data structure is invalid.
+            ValueError: If no tags are provided or if arguments are invalid.
             APIError: If the API request fails (e.g., 404 bookmark not found).
         """
-        # Validate the tags_data structure
-        if not isinstance(tags_data, dict):
-            raise ValueError("tags_data must be a dictionary")
+        # Validate that at least one tag source is provided
+        if not tag_ids and not tag_names:
+            raise ValueError("At least one of 'tag_ids' or 'tag_names' must be provided")
 
-        if "tags" not in tags_data:
-            raise ValueError("tags_data must contain a 'tags' key")
+        # Validate input types
+        if tag_ids is not None and not isinstance(tag_ids, list):
+            raise ValueError("'tag_ids' must be a list of strings")
 
-        tags_list = tags_data["tags"]
-        if not isinstance(tags_list, list):
-            raise ValueError("The 'tags' value must be a list")
+        if tag_names is not None and not isinstance(tag_names, list):
+            raise ValueError("'tag_names' must be a list of strings")
 
-        # Validate each tag object in the list
-        for i, tag in enumerate(tags_list):
-            if not isinstance(tag, dict):
-                raise ValueError(f"Tag at index {i} must be a dictionary")
+        # Validate individual elements
+        if tag_ids:
+            for i, tag_id in enumerate(tag_ids):
+                if not isinstance(tag_id, str) or not tag_id.strip():
+                    raise ValueError(f"Tag ID at index {i} must be a non-empty string")
 
-            has_tag_id = "tagId" in tag
-            has_tag_name = "tagName" in tag
+        if tag_names:
+            for i, tag_name in enumerate(tag_names):
+                if not isinstance(tag_name, str) or not tag_name.strip():
+                    raise ValueError(f"Tag name at index {i} must be a non-empty string")
 
-            if not has_tag_id and not has_tag_name:
-                raise ValueError(
-                    f"Tag at index {i} must contain either 'tagId' or 'tagName'"
-                )
+        # Construct the tags_data dict in the format expected by the API
+        tags_list = []
+
+        if tag_ids:
+            for tag_id in tag_ids:
+                tags_list.append({"tagId": tag_id.strip()})
+
+        if tag_names:
+            for tag_name in tag_names:
+                tags_list.append({"tagName": tag_name.strip()})
 
-            if has_tag_id and not isinstance(tag["tagId"], str):
-                raise ValueError(f"Tag at index {i}: 'tagId' must be a string")
+        tags_data = {"tags": tags_list}
 
-            if has_tag_name and not isinstance(tag["tagName"], str):
-                raise ValueError(f"Tag at index {i}: 'tagName' must be a string")
+        # Optional validation using Tag datatype if validation is enabled
+        if not self.disable_response_validation:
+            # Validate the constructed structure matches expected format
+            # This is primarily for development/debugging purposes
+            logger.debug("Validating constructed tags_data structure")
 
         endpoint = f"bookmarks/{bookmark_id}/tags"
         response_data = self._call("DELETE", endpoint, data=tags_data)

{karakeep_python_api-0.2.1 → karakeep_python_api-0.2.3/karakeep_python_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 0.2.1
+Version: 0.2.3
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3
@@ -243,7 +243,12 @@ except Exception as e:
 
 Examples of the API being used can be found in the [`./examples`](./examples) folder. Don't hesitate to submit yours!
 
--   **Omnivore Archiving Status Updater**: A script to fix the archive status of bookmarks imported from Omnivore into Karakeep. See [`examples/omnivore_archiving_status_updater/README.md`](./examples/omnivore_archiving_status_updater/README.md) for details.
+| Example Script | Description | Documentation |
+|----------------|-------------|---------------|
+| **Add Time-to-Read Tags** | Automatically adds time-to-read tags (`0-5m`, `5-10m`, etc.) to bookmarks based on content length analysis. | [`README.md`](./examples/add_time_to_read_tag/README.md) |
+| **List to Tag Converter** | Converts a Karakeep list into tags by adding a specified tag to all bookmarks within that list. | [`README.md`](./examples/list_to_tag/README.md) |
+| **Omnivore Archiving Status Updater** | Fixes the archived status of bookmarks imported from Omnivore by reading export data and updating Karakeep accordingly. | [`README.md`](./examples/omnivore_archiving_status_updater/README.md) |
+| **Pocket Archiving Status Updater** | Fixes the archived status of bookmarks imported from Pocket by reading export data and updating Karakeep accordingly. | [`README.md`](./examples/pocket_archiving_status_updater/README.md) |
 
 ## Development
 

{karakeep_python_api-0.2.1 → karakeep_python_api-0.2.3}/setup.py

@@ -7,7 +7,7 @@ with open("README.md", "r") as readme:
 
 setup(
     name="karakeep_python_api",
-    version="0.2.1",
+    version="0.2.3",
     description="Community python client for the Karakeep API.",  # Simplified description
     long_description=long_description,
     long_description_content_type="text/markdown",

{karakeep_python_api-0.2.1 → karakeep_python_api-0.2.3}/tests/test_karakeep_api.py

@@ -530,9 +530,8 @@ def test_tag_lifecycle_on_bookmark(karakeep_client: KarakeepAPI, managed_bookmar
     try:
         # 1. Attach a new tag by name to the bookmark
         logger.info(f"\nAttempting to attach tag '{initial_tag_name}' to bookmark {bookmark_id}")
-        attach_payload = {"tags": [{"tagName": initial_tag_name}]}
         attach_response = karakeep_client.attach_tags_to_a_bookmark(
-            bookmark_id=bookmark_id, tags_data=attach_payload
+            bookmark_id=bookmark_id, tag_names=[initial_tag_name]
         )
         assert "attached" in attach_response and len(attach_response["attached"]) == 1, \
             "Failed to attach tag or response format incorrect"
@@ -563,9 +562,8 @@ def test_tag_lifecycle_on_bookmark(karakeep_client: KarakeepAPI, managed_bookmar
 
         # 4. Detach the tag from the bookmark
         logger.info(f"\nAttempting to detach tag {tag_id_to_manage} from bookmark {bookmark_id}")
-        detach_payload = {"tags": [{"tagId": tag_id_to_manage}]}
         detach_response = karakeep_client.detach_tags_from_a_bookmark(
-            bookmark_id=bookmark_id, tags_data=detach_payload
+            bookmark_id=bookmark_id, tag_ids=[tag_id_to_manage]
         )
         assert "detached" in detach_response and tag_id_to_manage in detach_response["detached"], \
             "Failed to detach tag or response format incorrect"