karakeep-python-api 0.2.2__tar.gz → 1.0.0__tar.gz

{karakeep_python_api-0.2.2/karakeep_python_api.egg-info → karakeep_python_api-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 0.2.2
+Version: 1.0.0
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3
@@ -52,6 +52,7 @@ A community-developed Python client for the [Karakeep](https://karakeep.app/) AP
   - [Environment Variables](#environment-variables)
   - [Command Line Interface (CLI)](#command-line-interface-cli)
   - [Python Library](#python-library)
+- [Community Scripts](#community-scripts)
 - [Development](#development)
 - [License](#license)
 
@@ -239,11 +240,17 @@ except Exception as e:
 
 ```
 
-### Usage Examples
+## Community Scripts
 
 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. Includes systemd service and timer files for automated periodic execution. | [`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 Highlights Importer** | Imports highlights from Omnivore export data to Karakeep, with intelligent position detection and bookmark matching. Supports dry-run mode for testing. | [`README.md`](./examples/omnivore_highlights_importer/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.2 → karakeep_python_api-1.0.0}/README.md

@@ -17,6 +17,7 @@ A community-developed Python client for the [Karakeep](https://karakeep.app/) AP
   - [Environment Variables](#environment-variables)
   - [Command Line Interface (CLI)](#command-line-interface-cli)
   - [Python Library](#python-library)
+- [Community Scripts](#community-scripts)
 - [Development](#development)
 - [License](#license)
 
@@ -204,11 +205,17 @@ except Exception as e:
 
 ```
 
-### Usage Examples
+## Community Scripts
 
 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. Includes systemd service and timer files for automated periodic execution. | [`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 Highlights Importer** | Imports highlights from Omnivore export data to Karakeep, with intelligent position detection and bookmark matching. Supports dry-run mode for testing. | [`README.md`](./examples/omnivore_highlights_importer/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.2 → karakeep_python_api-1.0.0}/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.2"
+    VERSION: str = "1.0.0"
 
     def __init__(
         self,
@@ -95,7 +95,9 @@ class KarakeepAPI:
         verify_ssl: bool = True,
         verbose: bool = False,
         disable_response_validation: Optional[bool] = None,
-        rate_limit: float = 0.0,  # Minimum interval between API calls in seconds
+        rate_limit: Union[
+            float, int
+        ] = 0.0,  # Minimum interval between API calls in seconds
     ):
         """
         Initialize the Karakeep API client.
@@ -905,15 +907,21 @@ class KarakeepAPI:
         return None  # Explicitly return None for 204
 
     @optional_typecheck
-    def update_a_bookmark(self, bookmark_id: str, update_data: dict) -> Dict[str, Any]:
+    def update_a_bookmark(
+        self,
+        bookmark_id: str,
+        update_data: Dict[str, Any],
+    ) -> Dict[str, Any]:
         """
         Update a bookmark by its ID. Corresponds to PATCH /bookmarks/{bookmarkId}.
-        Allows updating fields like 'archived', 'favourited', 'summary', 'note', 'title', etc.
+        Allows updating various bookmark fields including metadata, content, and status.
 
         Args:
             bookmark_id: The ID (string) of the bookmark to update.
-            update_data: A dictionary containing the fields to update (e.g., `{"archived": True}`).
-                         See the OpenAPI spec for allowed fields in the request body.
+            update_data: Dictionary containing the fields to update. Supported keys include:
+                        'title', 'archived', 'favourited', 'note', 'summary', 'createdAt',
+                        'url', 'description', 'author', 'publisher', 'datePublished',
+                        'dateModified', 'text', 'assetContent'.
 
         Returns:
             dict: A dictionary representing the updated bookmark (partial representation).
@@ -922,8 +930,13 @@ class KarakeepAPI:
                   Validation is not performed on this response type by default.
 
         Raises:
+            ValueError: If update_data is empty or no valid fields are provided to update.
             APIError: If the API request fails (e.g., 404 bookmark not found).
         """
+        # Ensure at least one field is being updated
+        if not update_data:
+            raise ValueError("update_data must contain at least one field to update.")
+
         endpoint = f"bookmarks/{bookmark_id}"
         response_data = self._call("PATCH", endpoint, data=update_data)
         # The response schema is a subset of Bookmark, return as dict as specified in spec
@@ -979,7 +992,9 @@ class KarakeepAPI:
         """
         # 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")
+            raise ValueError(
+                "At least one of 'tag_ids' or 'tag_names' must be provided"
+            )
 
         # Validate input types
         if tag_ids is not None and not isinstance(tag_ids, list):
@@ -997,7 +1012,9 @@ class KarakeepAPI:
         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")
+                    raise ValueError(
+                        f"Tag name at index {i} must be a non-empty string"
+                    )
 
         # Construct the tags_data dict in the format expected by the API
         tags_list = []
@@ -1050,7 +1067,9 @@ class KarakeepAPI:
         """
         # 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")
+            raise ValueError(
+                "At least one of 'tag_ids' or 'tag_names' must be provided"
+            )
 
         # Validate input types
         if tag_ids is not None and not isinstance(tag_ids, list):
@@ -1068,7 +1087,9 @@ class KarakeepAPI:
         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")
+                    raise ValueError(
+                        f"Tag name at index {i} must be a non-empty string"
+                    )
 
         # Construct the tags_data dict in the format expected by the API
         tags_list = []
@@ -1145,16 +1166,28 @@ class KarakeepAPI:
 
     @optional_typecheck
     def attach_asset(
-        self, bookmark_id: str, asset_data: dict
+        self,
+        bookmark_id: str,
+        asset_id: str,
+        asset_type: Literal[
+            "screenshot",
+            "assetScreenshot",
+            "bannerImage",
+            "fullPageArchive",
+            "video",
+            "bookmarkAsset",
+            "precrawledArchive",
+            "unknown",
+        ],
     ) -> Union[datatypes.Asset, Dict[str, Any], List[Any]]:
         """
         Attach a new asset to a bookmark. Corresponds to POST /bookmarks/{bookmarkId}/assets.
 
         Args:
             bookmark_id: The ID (string) of the bookmark.
-            asset_data: Dictionary specifying the asset to attach. Must contain "id" (string) and "assetType" (string enum).
-                        Example: `{"id": "asset_id_string", "assetType": "screenshot"}`
-                        See `datatypes.AssetType` enum for possible asset types.
+            asset_id: The ID (string) of the asset to attach.
+            asset_type: The type of asset being attached. Must be one of: "screenshot", "assetScreenshot",
+                        "bannerImage", "fullPageArchive", "video", "bookmarkAsset", "precrawledArchive", "unknown".
 
         Returns:
             datatypes.Asset: The attached asset object.
@@ -1164,6 +1197,9 @@ class KarakeepAPI:
             APIError: If the API request fails (e.g., 404 bookmark not found).
             pydantic.ValidationError: If response validation fails (and is not disabled).
         """
+        # Construct the asset data dict as expected by the API
+        asset_data = {"id": asset_id, "assetType": asset_type}
+
         endpoint = f"bookmarks/{bookmark_id}/assets"
         response_data = self._call("POST", endpoint, data=asset_data)
 
@@ -1175,9 +1211,7 @@ class KarakeepAPI:
             return datatypes.Asset.model_validate(response_data)
 
     @optional_typecheck
-    def replace_asset(
-        self, bookmark_id: str, asset_id: str, new_asset_data: dict
-    ) -> None:
+    def replace_asset(self, bookmark_id: str, asset_id: str, new_asset_id: str) -> None:
         """
         Replace an existing asset associated with a bookmark with a new one.
         Corresponds to PUT /bookmarks/{bookmarkId}/assets/{assetId}.
@@ -1185,8 +1219,7 @@ class KarakeepAPI:
         Args:
             bookmark_id: The ID (string) of the bookmark.
             asset_id: The ID (string) of the asset to be replaced.
-            new_asset_data: Dictionary specifying the new asset ID. Must contain "assetId" (string).
-                            Example: `{"assetId": "new_asset_id_string"}`
+            new_asset_id: The ID (string) of the new asset to replace with.
 
         Returns:
             None: Returns None upon successful replacement (204 No Content).
@@ -1194,6 +1227,9 @@ class KarakeepAPI:
         Raises:
             APIError: If the API request fails (e.g., 404 bookmark or asset not found).
         """
+        # Construct the request body as expected by the API
+        new_asset_data = {"assetId": new_asset_id}
+
         endpoint = f"bookmarks/{bookmark_id}/assets/{asset_id}"
         self._call("PUT", endpoint, data=new_asset_data)  # Expects 204 No Content
         return None  # Explicitly return None for 204
@@ -1367,25 +1403,52 @@ class KarakeepAPI:
 
     @optional_typecheck
     def update_a_list(
-        self, list_id: str, update_data: dict
+        self,
+        list_id: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        icon: Optional[str] = None,
+        parent_id: Optional[str] = None,
+        query: Optional[str] = None,
     ) -> Union[datatypes.ListModel, Dict[str, Any], List[Any]]:
         """
         Update a list by its ID. Corresponds to PATCH /lists/{listId}.
-        Allows updating fields like "name", "description", "icon", "parentId", "query".
+        Allows updating various list fields including name, description, icon, parent relationship, and query.
 
         Args:
             list_id: The ID (string) of the list to update.
-            update_data: A dictionary containing the fields to update (e.g., `{"name": "new name"}`).
-                         See the OpenAPI spec for allowed fields.
+            name: Optional new name for the list (1-40 characters).
+            description: Optional new description for the list (0-100 characters, can be None to clear).
+            icon: Optional new icon for the list.
+            parent_id: Optional new parent list ID (can be None to remove parent relationship).
+            query: Optional new query string for smart lists (minimum 1 character).
 
         Returns:
             datatypes.ListModel: The updated list object.
             If response validation is disabled, returns the raw API response (dict/list).
 
         Raises:
+            ValueError: If no fields are provided to update.
             APIError: If the API request fails (e.g., 404 list not found).
             pydantic.ValidationError: If response validation fails (and is not disabled).
         """
+        # Construct update_data from provided arguments, excluding None values that weren't explicitly passed
+        update_data = {}
+        if name is not None:
+            update_data["name"] = name
+        if description is not None:
+            update_data["description"] = description
+        if icon is not None:
+            update_data["icon"] = icon
+        if parent_id is not None:
+            update_data["parentId"] = parent_id
+        if query is not None:
+            update_data["query"] = query
+
+        # Ensure at least one field is being updated
+        if not update_data:
+            raise ValueError("At least one field must be provided to update.")
+
         endpoint = f"lists/{list_id}"
         response_data = self._call("PATCH", endpoint, data=update_data)
 
@@ -1594,23 +1657,28 @@ class KarakeepAPI:
         return None  # Explicitly return None for 204
 
     @optional_typecheck
-    def update_a_tag(self, tag_id: str, update_data: dict) -> Dict[str, Any]:
+    def update_a_tag(self, tag_id: str, update_data: Dict[str, Any]) -> Dict[str, Any]:
         """
         Update a tag by its ID. Currently only supports updating the "name".
         Corresponds to PATCH /tags/{tagId}.
 
         Args:
             tag_id: The ID (string) of the tag to update.
-            update_data: A dictionary containing the fields to update. Must include "name" (string).
-                         Example: `{"name": "new tag name"}`
+            update_data: Dictionary containing the fields to update. Supported keys include:
+                        'name' (string).
 
         Returns:
             dict: A dictionary containing the updated tag information with "id" and "name" fields.
                   Validation is not performed on this response type by default.
 
         Raises:
+            ValueError: If update_data is empty or no valid fields are provided to update.
             APIError: If the API request fails (e.g., 404 tag not found).
         """
+        # Ensure at least one field is being updated
+        if not update_data:
+            raise ValueError("update_data must contain at least one field to update.")
+
         endpoint = f"tags/{tag_id}"
         response_data = self._call("PATCH", endpoint, data=update_data)
         # Response schema is a simple dict with id and name, return as dict
@@ -1693,8 +1761,8 @@ class KarakeepAPI:
     def create_a_new_highlight(
         self,
         bookmark_id: str,
-        start_offset: float,
-        end_offset: float,
+        start_offset: Union[float, int],
+        end_offset: Union[float, int],
         color: Optional[Literal["yellow", "red", "green", "blue"]] = "yellow",
         text: Optional[str] = None,
         note: Optional[str] = None,
@@ -1796,7 +1864,9 @@ class KarakeepAPI:
 
     @optional_typecheck
     def update_a_highlight(
-        self, highlight_id: str, update_data: dict
+        self,
+        highlight_id: str,
+        color: Optional[Literal["yellow", "red", "green", "blue"]] = None,
     ) -> Union[datatypes.Highlight, Dict[str, Any], List[Any]]:
         """
         Update a highlight by its ID. Currently only supports updating the "color".
@@ -1804,17 +1874,26 @@ class KarakeepAPI:
 
         Args:
             highlight_id: The ID (string) of the highlight to update.
-            update_data: A dictionary containing the fields to update. Must include "color" (string enum).
-                         See `datatypes.Color` enum. Example: `{"color": "red"}`
+            color: Optional new color for the highlight ("yellow", "red", "green", "blue").
 
         Returns:
             datatypes.Highlight: The updated highlight object.
             If response validation is disabled, returns the raw API response (dict/list).
 
         Raises:
+            ValueError: If no fields are provided to update.
             APIError: If the API request fails (e.g., 404 highlight not found).
             pydantic.ValidationError: If response validation fails (and is not disabled).
         """
+        # Construct update_data from provided arguments, excluding None values
+        update_data = {}
+        if color is not None:
+            update_data["color"] = color
+
+        # Ensure at least one field is being updated
+        if not update_data:
+            raise ValueError("At least one field must be provided to update.")
+
         endpoint = f"highlights/{highlight_id}"
         response_data = self._call("PATCH", endpoint, data=update_data)
 

{karakeep_python_api-0.2.2 → karakeep_python_api-1.0.0/karakeep_python_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 0.2.2
+Version: 1.0.0
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3
@@ -52,6 +52,7 @@ A community-developed Python client for the [Karakeep](https://karakeep.app/) AP
   - [Environment Variables](#environment-variables)
   - [Command Line Interface (CLI)](#command-line-interface-cli)
   - [Python Library](#python-library)
+- [Community Scripts](#community-scripts)
 - [Development](#development)
 - [License](#license)
 
@@ -239,11 +240,17 @@ except Exception as e:
 
 ```
 
-### Usage Examples
+## Community Scripts
 
 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. Includes systemd service and timer files for automated periodic execution. | [`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 Highlights Importer** | Imports highlights from Omnivore export data to Karakeep, with intelligent position detection and bookmark matching. Supports dry-run mode for testing. | [`README.md`](./examples/omnivore_highlights_importer/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.2 → karakeep_python_api-1.0.0}/setup.py

@@ -7,7 +7,7 @@ with open("README.md", "r") as readme:
 
 setup(
     name="karakeep_python_api",
-    version="0.2.2",
+    version="1.0.0",
     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.2 → karakeep_python_api-1.0.0}/tests/test_karakeep_api.py

@@ -6,7 +6,7 @@ import random
 import string
 import time
 import beartype  # to trigger the runtime typechecking
-import json # Added for CLI test payload generation
+import json  # Added for CLI test payload generation
 
 # Import API, errors, and datatypes from the main package
 from karakeep_python_api import KarakeepAPI, APIError, AuthenticationError, datatypes
@@ -30,12 +30,16 @@ def test_get_all_bookmarks_paginated(karakeep_client: KarakeepAPI):
 
         # If there's a next cursor, get the next page
         if page1.nextCursor:
-            logger.info(f"  Attempting to fetch next page with cursor: {page1.nextCursor}")
+            logger.info(
+                f"  Attempting to fetch next page with cursor: {page1.nextCursor}"
+            )
             page2 = karakeep_client.get_all_bookmarks(limit=2, cursor=page1.nextCursor)
             assert isinstance(page2, datatypes.PaginatedBookmarks)
             assert isinstance(page2.bookmarks, list)
             assert len(page2.bookmarks) <= 2
-            logger.info(f"✓ Retrieved second page with {len(page2.bookmarks)} bookmarks.")
+            logger.info(
+                f"✓ Retrieved second page with {len(page2.bookmarks)} bookmarks."
+            )
             # Ensure bookmarks are different from page 1 (simple check)
             if page1.bookmarks and page2.bookmarks:
                 assert (
@@ -163,12 +167,16 @@ def test_get_all_highlights_paginated(karakeep_client: KarakeepAPI):
 
         # If there's a next cursor, get the next page
         if page1.nextCursor:
-            logger.info(f"  Attempting to fetch next page with cursor: {page1.nextCursor}")
+            logger.info(
+                f"  Attempting to fetch next page with cursor: {page1.nextCursor}"
+            )
             page2 = karakeep_client.get_all_highlights(limit=3, cursor=page1.nextCursor)
             assert isinstance(page2, datatypes.PaginatedHighlights)
             assert isinstance(page2.highlights, list)
             assert len(page2.highlights) <= 3
-            logger.info(f"✓ Retrieved second page with {len(page2.highlights)} highlights.")
+            logger.info(
+                f"✓ Retrieved second page with {len(page2.highlights)} highlights."
+            )
             # Ensure highlights are different from page 1 (simple check)
             if page1.highlights and page2.highlights:
                 assert (
@@ -257,11 +265,15 @@ def test_create_and_delete_list(karakeep_client: KarakeepAPI):
     try:
         # 1. Generate a unique list name
         timestamp = int(time.time())
-        random_suffix = "".join(random.choices(string.ascii_lowercase + string.digits, k=6))
+        random_suffix = "".join(
+            random.choices(string.ascii_lowercase + string.digits, k=6)
+        )
         list_name = f"Test List {timestamp}-{random_suffix}"
         list_icon = "🧪"  # Test tube icon
 
-        logger.info(f"\nAttempting to create list: Name='{list_name}', Icon='{list_icon}'")
+        logger.info(
+            f"\nAttempting to create list: Name='{list_name}', Icon='{list_icon}'"
+        )
 
         # 2. Get initial list count (optional, for comparison)
         initial_lists = karakeep_client.get_all_lists()
@@ -270,9 +282,7 @@ def test_create_and_delete_list(karakeep_client: KarakeepAPI):
 
         # 3. Create the new list
         created_list = karakeep_client.create_a_new_list(
-            name=list_name,
-            icon=list_icon,
-            list_type="manual"
+            name=list_name, icon=list_icon, list_type="manual"
         )
         assert isinstance(
             created_list, datatypes.ListModel
@@ -294,7 +304,6 @@ def test_create_and_delete_list(karakeep_client: KarakeepAPI):
         logger.info(f"  List count after creation: {len(current_lists_after_create)}")
         logger.info(f"✓ Verified list {created_list_id} is present in get_all_lists.")
 
-
         # 5. Verify the list exists by getting it directly (redundant but good check)
         retrieved_list = karakeep_client.get_a_single_list(list_id=created_list_id)
         assert isinstance(retrieved_list, datatypes.ListModel)
@@ -304,7 +313,9 @@ def test_create_and_delete_list(karakeep_client: KarakeepAPI):
     except (APIError, AuthenticationError) as e:
         pytest.fail(f"API error during list creation/verification: {e}")
     except Exception as e:
-        pytest.fail(f"An unexpected error occurred during list creation/verification: {e}")
+        pytest.fail(
+            f"An unexpected error occurred during list creation/verification: {e}"
+        )
     finally:
         # 6. Delete the list (ensure cleanup even if assertions fail)
         if created_list_id:
@@ -342,21 +353,27 @@ def test_create_and_delete_list(karakeep_client: KarakeepAPI):
             except Exception as e:
                 pytest.fail(f"An unexpected error occurred during list deletion: {e}")
         else:
-            logger.info("\nSkipping deletion because list creation failed or ID was not obtained.")
+            logger.info(
+                "\nSkipping deletion because list creation failed or ID was not obtained."
+            )
 
 
-def test_create_and_delete_bookmark(karakeep_client: KarakeepAPI, managed_bookmark: datatypes.Bookmark):
+def test_create_and_delete_bookmark(
+    karakeep_client: KarakeepAPI, managed_bookmark: datatypes.Bookmark
+):
     """
     Test verifying a created bookmark (via fixture) and searching for it.
     The fixture handles creation and deletion.
     """
     created_bookmark_id = managed_bookmark.id
-    test_url = managed_bookmark.content.url # Get URL from fixture
-    original_title = managed_bookmark.title # Get title from fixture
+    test_url = managed_bookmark.content.url  # Get URL from fixture
+    original_title = managed_bookmark.title  # Get title from fixture
 
     try:
         # 1. Bookmark is already created by the 'managed_bookmark' fixture.
-        logger.info(f"\nUsing managed bookmark ID: {created_bookmark_id}, URL: '{test_url}', Title: '{original_title}'")
+        logger.info(
+            f"\nUsing managed bookmark ID: {created_bookmark_id}, URL: '{test_url}', Title: '{original_title}'"
+        )
 
         # 2. Verify the bookmark exists by getting it directly
         retrieved_bookmark = karakeep_client.get_a_single_bookmark(
@@ -368,14 +385,13 @@ def test_create_and_delete_bookmark(karakeep_client: KarakeepAPI, managed_bookma
         assert retrieved_bookmark.title == original_title
         logger.info(f"✓ Successfully retrieved the managed bookmark by ID.")
 
-
         # 3. Search for the created bookmark
         # Use a search query that is likely to match the fixture's title
         # The fixture title is "Managed Fixture Bookmark {timestamp}-{random_suffix}"
         # A simple search for "Managed Fixture Bookmark" should work.
         # If the title is very dynamic, searching by URL might be more robust if supported,
         # or by a known part of the title.
-        
+
         # waiting a bit for the indexation just in case
         time.sleep(30)
 
@@ -388,27 +404,38 @@ def test_create_and_delete_bookmark(karakeep_client: KarakeepAPI, managed_bookma
             '"fixture"',
         ]
         for trial, search_query_component in enumerate(search_queries):
-            logger.info(f"\nAttempting to search for bookmark with query based on title: '{search_query_component}'. Retrying multiple times because search is nondeterministic.")
-            search_results = karakeep_client.search_bookmarks(q=search_query_component, limit=100, include_content=False)
+            logger.info(
+                f"\nAttempting to search for bookmark with query based on title: '{search_query_component}'. Retrying multiple times because search is nondeterministic."
+            )
+            search_results = karakeep_client.search_bookmarks(
+                q=search_query_component, limit=100, include_content=False
+            )
             assert isinstance(
                 search_results, datatypes.PaginatedBookmarks
             ), "Search response should be PaginatedBookmarks model"
             assert isinstance(
                 search_results.bookmarks, list
             ), "Search results bookmarks attribute should be a list"
-            
+
             titles_in_search = [b.title for b in search_results.bookmarks]
-            found_in_search = any(b.id == created_bookmark_id for b in search_results.bookmarks)
+            found_in_search = any(
+                b.id == created_bookmark_id for b in search_results.bookmarks
+            )
             if found_in_search:
                 break
             else:
                 time.sleep(3)
-        assert found_in_search, \
-        f"Managed bookmark {created_bookmark_id} (Title: '{original_title}') not found in {trial + 1} different search results for '{search_query_component}'. Titles were: '{titles_in_search}'."
-        logger.info(f"✓ Found managed bookmark in search results for '{search_query_component}'.")
+        assert (
+            found_in_search
+        ), f"Managed bookmark {created_bookmark_id} (Title: '{original_title}') not found in {trial + 1} different search results for '{search_query_component}'. Titles were: '{titles_in_search}'."
+        logger.info(
+            f"✓ Found managed bookmark in search results for '{search_query_component}'."
+        )
 
         # 4. Test CLI search equivalent
-        logger.info(f"\n  Running CLI equivalent: search-bookmarks --q '{search_query_component}' --limit 10 --include-content false")
+        logger.info(
+            f"\n  Running CLI equivalent: search-bookmarks --q '{search_query_component}' --limit 10 --include-content false"
+        )
         try:
             cli_search_command = f"python -m karakeep_python_api search-bookmarks --q '{search_query_component}' --limit 10 --include-content false"
             search_cli_output = subprocess.run(
@@ -418,16 +445,23 @@ def test_create_and_delete_bookmark(karakeep_client: KarakeepAPI, managed_bookma
                 capture_output=True,
                 text=True,
             )
-            assert created_bookmark_id in search_cli_output.stdout, \
-                f"Managed bookmark ID {created_bookmark_id} not found in CLI search output for '{search_query_component}'"
-            logger.info("✓ CLI search command executed successfully and contained the bookmark ID.")
+            assert (
+                created_bookmark_id in search_cli_output.stdout
+            ), f"Managed bookmark ID {created_bookmark_id} not found in CLI search output for '{search_query_component}'"
+            logger.info(
+                "✓ CLI search command executed successfully and contained the bookmark ID."
+            )
         except subprocess.CalledProcessError as e:
             logger.info(f"  CLI search command failed with exit code {e.returncode}")
             logger.info(f"  Stdout: {e.stdout}")
             logger.info(f"  Stderr: {e.stderr}")
-            pytest.fail(f"CLI command 'search-bookmarks --q \"{search_query_component}\"' failed: {e}")
+            pytest.fail(
+                f"CLI command 'search-bookmarks --q \"{search_query_component}\"' failed: {e}"
+            )
         except Exception as e:
-            pytest.fail(f"An unexpected error occurred running the CLI search command: {e}")
+            pytest.fail(
+                f"An unexpected error occurred running the CLI search command: {e}"
+            )
 
     except (APIError, AuthenticationError) as e:
         pytest.fail(f"API error during bookmark verification/search: {e}")
@@ -439,46 +473,64 @@ def test_create_and_delete_bookmark(karakeep_client: KarakeepAPI, managed_bookma
     # The fixture also handles verification of deletion.
 
 
-def test_update_bookmark_title(karakeep_client: KarakeepAPI, managed_bookmark: datatypes.Bookmark):
+def test_update_bookmark_title(
+    karakeep_client: KarakeepAPI, managed_bookmark: datatypes.Bookmark
+):
     """Test updating a bookmark's title via API and CLI, using a managed bookmark."""
     created_bookmark_id = managed_bookmark.id
-    original_title = managed_bookmark.title # Get the original title from the fixture
-    
+    original_title = managed_bookmark.title  # Get the original title from the fixture
+
     target_api_title = "this is a test title"
     target_cli_title = "this is a test title (CLI)"
 
     try:
         # The bookmark is already created by the 'managed_bookmark' fixture.
         # We have its ID in created_bookmark_id and its original title.
-        logger.info(f"\nUsing managed bookmark ID: {created_bookmark_id}, Original Title: '{original_title}'")
+        logger.info(
+            f"\nUsing managed bookmark ID: {created_bookmark_id}, Original Title: '{original_title}'"
+        )
 
         # 1. Update the bookmark's title using the API client
-        logger.info(f"\nAttempting to update bookmark ID {created_bookmark_id} title to: '{target_api_title}' via API")
+        logger.info(
+            f"\nAttempting to update bookmark ID {created_bookmark_id} title to: '{target_api_title}' via API"
+        )
         update_payload_api = {"title": target_api_title}
         updated_bookmark_partial = karakeep_client.update_a_bookmark(
             bookmark_id=created_bookmark_id, update_data=update_payload_api
         )
-        assert isinstance(updated_bookmark_partial, dict), "Update response should be a dict"
-        assert updated_bookmark_partial.get("title") == target_api_title, \
-            f"Partial response title '{updated_bookmark_partial.get('title')}' does not match target API title '{target_api_title}'"
-        logger.info(f"✓ API call to update_a_bookmark successful. Partial response title: '{updated_bookmark_partial.get('title')}'")
+        assert isinstance(
+            updated_bookmark_partial, dict
+        ), "Update response should be a dict"
+        assert (
+            updated_bookmark_partial.get("title") == target_api_title
+        ), f"Partial response title '{updated_bookmark_partial.get('title')}' does not match target API title '{target_api_title}'"
+        logger.info(
+            f"✓ API call to update_a_bookmark successful. Partial response title: '{updated_bookmark_partial.get('title')}'"
+        )
 
         # 2. Verify the API update by fetching the bookmark again
-        logger.info(f"\nFetching bookmark ID {created_bookmark_id} to verify API title update.")
+        logger.info(
+            f"\nFetching bookmark ID {created_bookmark_id} to verify API title update."
+        )
         retrieved_bookmark_after_api_update = karakeep_client.get_a_single_bookmark(
             bookmark_id=created_bookmark_id
         )
         assert isinstance(retrieved_bookmark_after_api_update, datatypes.Bookmark)
-        assert retrieved_bookmark_after_api_update.title == target_api_title, \
-            f"Retrieved bookmark title '{retrieved_bookmark_after_api_update.title}' does not match expected API-updated title '{target_api_title}'"
-        logger.info(f"✓ Successfully verified bookmark title updated by API to: '{retrieved_bookmark_after_api_update.title}'")
+        assert (
+            retrieved_bookmark_after_api_update.title == target_api_title
+        ), f"Retrieved bookmark title '{retrieved_bookmark_after_api_update.title}' does not match expected API-updated title '{target_api_title}'"
+        logger.info(
+            f"✓ Successfully verified bookmark title updated by API to: '{retrieved_bookmark_after_api_update.title}'"
+        )
 
         # 3. Test CLI equivalent for updating the bookmark's title
-        logger.info(f"\n  Running CLI equivalent to update title to: '{target_cli_title}'")
+        logger.info(
+            f"\n  Running CLI equivalent to update title to: '{target_cli_title}'"
+        )
         cli_update_payload_json = json.dumps({"title": target_cli_title})
         # Ensure the JSON string is properly quoted for the shell command
         cli_update_command = f"python -m karakeep_python_api update-a-bookmark --bookmark-id {created_bookmark_id} --update-data '{cli_update_payload_json}'"
-        
+
         try:
             subprocess.run(
                 cli_update_command,
@@ -490,14 +542,19 @@ def test_update_bookmark_title(karakeep_client: KarakeepAPI, managed_bookmark: d
             logger.info("✓ CLI update command executed successfully.")
 
             # 4. Verify CLI update by fetching the bookmark again
-            logger.info(f"\nFetching bookmark ID {created_bookmark_id} to verify CLI title update.")
+            logger.info(
+                f"\nFetching bookmark ID {created_bookmark_id} to verify CLI title update."
+            )
             retrieved_bookmark_after_cli_update = karakeep_client.get_a_single_bookmark(
                 bookmark_id=created_bookmark_id
             )
             assert isinstance(retrieved_bookmark_after_cli_update, datatypes.Bookmark)
-            assert retrieved_bookmark_after_cli_update.title == target_cli_title, \
-                f"Retrieved bookmark title '{retrieved_bookmark_after_cli_update.title}' after CLI update does not match expected '{target_cli_title}'"
-            logger.info(f"✓ Successfully verified bookmark title updated by CLI to: '{retrieved_bookmark_after_cli_update.title}'")
+            assert (
+                retrieved_bookmark_after_cli_update.title == target_cli_title
+            ), f"Retrieved bookmark title '{retrieved_bookmark_after_cli_update.title}' after CLI update does not match expected '{target_cli_title}'"
+            logger.info(
+                f"✓ Successfully verified bookmark title updated by CLI to: '{retrieved_bookmark_after_cli_update.title}'"
+            )
 
         except subprocess.CalledProcessError as e:
             logger.info(f"  CLI update command failed with exit code {e.returncode}")
@@ -506,16 +563,22 @@ def test_update_bookmark_title(karakeep_client: KarakeepAPI, managed_bookmark: d
             logger.info(f"  Stderr: {e.stderr}")
             pytest.fail(f"CLI command for update-a-bookmark failed: {e}")
         except Exception as e:
-            pytest.fail(f"An unexpected error occurred running the CLI update command: {e}")
+            pytest.fail(
+                f"An unexpected error occurred running the CLI update command: {e}"
+            )
 
     except (APIError, AuthenticationError) as e:
         pytest.fail(f"API error during bookmark title update test: {e}")
     except Exception as e:
-        pytest.fail(f"An unexpected error occurred during bookmark title update test: {e}")
+        pytest.fail(
+            f"An unexpected error occurred during bookmark title update test: {e}"
+        )
     # No finally block needed for deletion, as 'managed_bookmark' fixture handles it.
 
 
-def test_tag_lifecycle_on_bookmark(karakeep_client: KarakeepAPI, managed_bookmark: datatypes.Bookmark):
+def test_tag_lifecycle_on_bookmark(
+    karakeep_client: KarakeepAPI, managed_bookmark: datatypes.Bookmark
+):
     """
     Test attaching a tag to a bookmark, updating the tag, detaching it, and deleting it.
     Uses the managed_bookmark fixture.
@@ -529,18 +592,23 @@ 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}")
+        logger.info(
+            f"\nAttempting to attach tag '{initial_tag_name}' to bookmark {bookmark_id}"
+        )
         attach_response = karakeep_client.attach_tags_to_a_bookmark(
             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"
+        assert (
+            "attached" in attach_response and len(attach_response["attached"]) == 1
+        ), "Failed to attach tag or response format incorrect"
         tag_id_to_manage = attach_response["attached"][0]
         assert isinstance(tag_id_to_manage, str), "Attached tag ID should be a string"
         logger.info(f"✓ Tag '{initial_tag_name}' attached with ID: {tag_id_to_manage}")
 
         # 2. Update the tag's name
-        logger.info(f"\nAttempting to update tag {tag_id_to_manage} to name '{updated_tag_name}'")
+        logger.info(
+            f"\nAttempting to update tag {tag_id_to_manage} to name '{updated_tag_name}'"
+        )
         update_payload = {"name": updated_tag_name}
         updated_tag = karakeep_client.update_a_tag(
             tag_id=tag_id_to_manage, update_data=update_payload
@@ -549,24 +617,38 @@ def test_tag_lifecycle_on_bookmark(karakeep_client: KarakeepAPI, managed_bookmar
         # assert isinstance(updated_tag, datatypes.Tag), "Update tag response should be Tag model"
         # assert updated_tag.name == updated_tag_name, "Tag name was not updated as expected"
         # logger.info(f"✓ Tag {tag_id_to_manage} updated to name '{updated_tag.name}'")
-        assert updated_tag["name"] == updated_tag_name, "Tag name was not updated as expected"
+        assert (
+            updated_tag["name"] == updated_tag_name
+        ), "Tag name was not updated as expected"
         logger.info(f"✓ Tag {tag_id_to_manage} updated to name '{updated_tag['name']}'")
 
         # 3. Verify tag update by getting it directly
-        logger.info(f"\nFetching tag {tag_id_to_manage} to verify its name is '{updated_tag_name}'")
+        logger.info(
+            f"\nFetching tag {tag_id_to_manage} to verify its name is '{updated_tag_name}'"
+        )
         retrieved_tag = karakeep_client.get_a_single_tag(tag_id=tag_id_to_manage)
-        assert isinstance(retrieved_tag, datatypes.Tag), "Get single tag response should be Tag model"
-        assert retrieved_tag.name == updated_tag_name, "Retrieved tag name does not match updated name"
+        assert isinstance(
+            retrieved_tag, datatypes.Tag
+        ), "Get single tag response should be Tag model"
+        assert (
+            retrieved_tag.name == updated_tag_name
+        ), "Retrieved tag name does not match updated name"
         assert retrieved_tag.id == tag_id_to_manage, "Retrieved tag ID does not match"
-        logger.info(f"✓ Verified tag {tag_id_to_manage} has name '{retrieved_tag.name}'")
+        logger.info(
+            f"✓ Verified tag {tag_id_to_manage} has name '{retrieved_tag.name}'"
+        )
 
         # 4. Detach the tag from the bookmark
-        logger.info(f"\nAttempting to detach tag {tag_id_to_manage} from bookmark {bookmark_id}")
+        logger.info(
+            f"\nAttempting to detach tag {tag_id_to_manage} from bookmark {bookmark_id}"
+        )
         detach_response = karakeep_client.detach_tags_from_a_bookmark(
             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"
+        assert (
+            "detached" in detach_response
+            and tag_id_to_manage in detach_response["detached"]
+        ), "Failed to detach tag or response format incorrect"
         logger.info(f"✓ Tag {tag_id_to_manage} detached from bookmark {bookmark_id}")
 
     except (APIError, AuthenticationError) as e:
@@ -588,20 +670,30 @@ def test_tag_lifecycle_on_bookmark(karakeep_client: KarakeepAPI, managed_bookmar
                         f"Tag {tag_id_to_manage} should not exist after deletion, but get_a_single_tag succeeded."
                     )
                 except APIError as e:
-                    assert e.status_code == 404, \
-                        f"Expected 404 Not Found when getting deleted tag, but got status {e.status_code}"
-                    logger.info(f"✓ Confirmed tag {tag_id_to_manage} is deleted (received 404).")
+                    assert (
+                        e.status_code == 404
+                    ), f"Expected 404 Not Found when getting deleted tag, but got status {e.status_code}"
+                    logger.info(
+                        f"✓ Confirmed tag {tag_id_to_manage} is deleted (received 404)."
+                    )
             except (APIError, AuthenticationError) as e:
                 # Log error during cleanup but don't let it mask original test failure
-                logger.info(f"  API error during tag deletion (cleanup) for ID {tag_id_to_manage}: {e}")
+                logger.info(
+                    f"  API error during tag deletion (cleanup) for ID {tag_id_to_manage}: {e}"
+                )
             except Exception as e:
-                logger.info(f"  Unexpected error during tag deletion (cleanup) for ID {tag_id_to_manage}: {e}")
+                logger.info(
+                    f"  Unexpected error during tag deletion (cleanup) for ID {tag_id_to_manage}: {e}"
+                )
         else:
-            logger.info("\nSkipping tag deletion (cleanup) because tag_id was not obtained or test failed before creation.")
+            logger.info(
+                "\nSkipping tag deletion (cleanup) because tag_id was not obtained or test failed before creation."
+            )
 
 
 # --- Test User Info/Stats Endpoints ---
 
+
 def test_cli_get_bookmarks_count_with_jq(karakeep_client: KarakeepAPI):
     """Test that CLI get-all-bookmarks with --limit returns the expected number of items."""
     # Skip test if jq is not installed
@@ -609,15 +701,15 @@ def test_cli_get_bookmarks_count_with_jq(karakeep_client: KarakeepAPI):
         subprocess.run(["jq", "--version"], check=True, capture_output=True)
     except (subprocess.CalledProcessError, FileNotFoundError):
         pytest.skip("jq is not installed. This test requires jq for JSON processing.")
-    
+
     # Define the limit we want to test
     test_limit = 200
-    
+
     try:
         logger.info(f"\nRunning CLI command: get-all-bookmarks --limit={test_limit}")
         # Use a two-command pipe: Run the CLI command and pipe to jq to count array length
         cmd = f"python -m karakeep_python_api --verbose get-all-bookmarks --limit={test_limit} | jq 'length'"
-        
+
         # Execute the piped command
         result = subprocess.run(
             cmd,
@@ -626,30 +718,36 @@ def test_cli_get_bookmarks_count_with_jq(karakeep_client: KarakeepAPI):
             capture_output=True,
             text=True,
         )
-        
+
         # Parse the output (should be just a number)
         try:
             actual_count = int(result.stdout.strip())
             logger.info(f"✓ Command returned {actual_count} bookmarks")
-            
+
             # Check if we got exactly the requested number or fewer (if there aren't enough bookmarks)
-            assert actual_count <= test_limit, f"Expected at most {test_limit} bookmarks, got {actual_count}"
-            
+            assert (
+                actual_count <= test_limit
+            ), f"Expected at most {test_limit} bookmarks, got {actual_count}"
+
             # Check if we got any bookmarks at all (to ensure the test is meaningful)
             # This could fail if the account has no bookmarks
             assert actual_count > 0, "Expected at least some bookmarks to be returned"
-            
+
             # If the account has enough bookmarks, we should get exactly the limit
             # But we can't assert this because we don't know how many bookmarks exist
             if actual_count < test_limit:
-                logger.info(f"Note: Only {actual_count} bookmarks were returned, which is less than the requested limit of {test_limit}. This is acceptable if the account doesn't have {test_limit} bookmarks.")
+                logger.info(
+                    f"Note: Only {actual_count} bookmarks were returned, which is less than the requested limit of {test_limit}. This is acceptable if the account doesn't have {test_limit} bookmarks."
+                )
             else:
-                logger.info(f"✓ Command returned exactly the requested limit of {test_limit} bookmarks")
-                
+                logger.info(
+                    f"✓ Command returned exactly the requested limit of {test_limit} bookmarks"
+                )
+
         except ValueError:
             logger.error(f"Failed to parse jq output as integer: '{result.stdout}'")
             pytest.fail(f"jq output is not a valid integer: '{result.stdout}'")
-            
+
     except subprocess.CalledProcessError as e:
         logger.error(f"Command failed with exit code {e.returncode}")
         logger.error(f"Stdout: {e.stdout}")
@@ -691,7 +789,7 @@ def test_get_current_user_stats(karakeep_client: KarakeepAPI):
             "python -m karakeep_python_api get-current-user-stats",
             shell=True,
             check=True,
-            capture_output=True, # Capture output to avoid logger.infoing it during tests unless verbose
+            capture_output=True,  # Capture output to avoid logger.infoing it during tests unless verbose
             text=True,
         )
         logger.info("✓ CLI command executed successfully.")