karakeep-python-api 1.2.4__tar.gz → 1.3.1__tar.gz

{karakeep_python_api-1.2.4/karakeep_python_api.egg-info → karakeep_python_api-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 1.2.4
+Version: 1.3.1
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3

{karakeep_python_api-1.2.4 → karakeep_python_api-1.3.1}/karakeep_python_api/datatypes.py

@@ -17,8 +17,8 @@ class StatusTypes(str, Enum):
 
 
 class NumBookmarksByAttachedType(BaseModel):
-    ai: Optional[float] = None
-    human: Optional[float] = None
+    ai: Optional[int] = None
+    human: Optional[int] = None
 
 
 class TagShort(BaseModel):
@@ -30,7 +30,7 @@ class TagShort(BaseModel):
 class Tag(BaseModel):
     id: str
     name: str
-    numBookmarks: float
+    numBookmarks: int
     numBookmarksByAttachedType: NumBookmarksByAttachedType
 
 
@@ -112,6 +112,11 @@ class Bookmark(BaseModel):
     summarizationStatus: Optional[Literal["success", "failure", "pending"]] = None
     note: Optional[str] = None
     summary: Optional[str] = None
+    source: Optional[
+        Literal[
+            "api", "web", "cli", "mobile", "extension", "singlefile", "rss", "import"
+        ]
+    ] = None
     tags: List[TagShort]
     content: Union[
         ContentTypeLink, ContentTypeText, ContentTypeAsset, ContentTypeUnknown
@@ -121,7 +126,18 @@ class Bookmark(BaseModel):
 
 class PaginatedBookmarks(BaseModel):
     bookmarks: List[Bookmark]
-    nextCursor: Optional[str]
+    nextCursor: Optional[str] = ""
+
+
+class ListModel(BaseModel):
+    id: str
+    name: str
+    description: Optional[str] = None
+    icon: str
+    parentId: Optional[str]
+    type: Optional[Literal["manual", "smart"]] = "manual"
+    query: Optional[str] = None
+    public: bool
 
 
 class Highlight(BaseModel):
@@ -136,17 +152,11 @@ class Highlight(BaseModel):
     createdAt: str
 
 
-class ListModel(BaseModel):
-    id: str
-    name: str
-    description: Optional[str] = None
-    icon: str
-    parentId: Optional[str]
-    type: Optional[Literal["manual", "smart"]] = "manual"
-    query: Optional[str] = None
-    public: bool
-
-
 class PaginatedHighlights(BaseModel):
     highlights: List[Highlight]
-    nextCursor: Optional[str]
+    nextCursor: Optional[str] = ""
+
+
+class PaginatedTags(BaseModel):
+    tags: List[Tag]
+    nextCursor: Optional[str] = ""

{karakeep_python_api-1.2.4 → karakeep_python_api-1.3.1}/karakeep_python_api/karakeep_api.py

@@ -85,7 +85,7 @@ class KarakeepAPI:
     """
 
     # Version reflects the client library version, updated by bumpver
-    VERSION: str = "1.2.4"
+    VERSION: str = "1.3.1"
 
     def __init__(
         self,
@@ -758,6 +758,19 @@ class KarakeepAPI:
         summary: Optional[str] = None,
         createdAt: Optional[str] = None,  # ISO 8601 format string
         crawlPriority: Optional[Literal["low", "normal"]] = None,
+        importSessionId: Optional[str] = None,
+        source: Optional[
+            Literal[
+                "api",
+                "web",
+                "cli",
+                "mobile",
+                "extension",
+                "singlefile",
+                "rss",
+                "import",
+            ]
+        ] = None,
         # Link specific
         url: Optional[str] = None,
         precrawledArchiveId: Optional[str] = None,
@@ -783,6 +796,8 @@ class KarakeepAPI:
             summary: Optional summary content for the bookmark.
             createdAt: Optional creation timestamp override (ISO 8601 format string).
             crawlPriority: Optional either 'low' or 'normal'.
+            importSessionId: Optional import session ID for tracking imported bookmarks.
+            source: Optional source of the bookmark ("api", "web", "cli", "mobile", "extension", "singlefile", "rss", "import").
 
             --- Link Type Specific ---
             url: The URL for the link bookmark. Required if type='link'.
@@ -799,7 +814,9 @@ class KarakeepAPI:
             sourceUrl: Optional source URL where the asset originated.
 
         Returns:
-            datatypes.Bookmark: The created bookmark.
+            datatypes.Bookmark: The bookmark object.
+                               Returns with status 200 if the bookmark already exists,
+                               or status 201 if the bookmark was newly created.
             If response validation is disabled, returns the raw API response (dict/list).
 
         Raises:
@@ -825,6 +842,10 @@ class KarakeepAPI:
             request_body["createdAt"] = createdAt
         if crawlPriority is not None:
             request_body["crawlPriority"] = crawlPriority
+        if importSessionId is not None:
+            request_body["importSessionId"] = importSessionId
+        if source is not None:
+            request_body["source"] = source
 
         # Add type-specific fields and perform validation
         if type == "link":
@@ -911,7 +932,9 @@ class KarakeepAPI:
 
     @optional_typecheck
     def get_a_single_bookmark(
-        self, bookmark_id: str, include_content: bool = True  # Default from spec
+        self,
+        bookmark_id: str,
+        include_content: bool = True,  # Default from spec
     ) -> Union[datatypes.Bookmark, Dict[str, Any], List[Any]]:
         """
         Get a single bookmark by its ID. Corresponds to GET /bookmarks/{bookmarkId}.
@@ -1169,6 +1192,54 @@ class KarakeepAPI:
         # No Pydantic validation applied here as the spec defines a simple dict response
         return response_data
 
+    @optional_typecheck
+    def get_lists_of_a_bookmark(
+        self, bookmark_id: str
+    ) -> Union[List[datatypes.ListModel], Dict[str, Any], List[Any]]:
+        """
+        Get all lists associated with a specific bookmark. Corresponds to GET /bookmarks/{bookmarkId}/lists.
+
+        Args:
+            bookmark_id: The ID (string) of the bookmark.
+
+        Returns:
+            List[datatypes.ListModel]: A list of list objects associated with the bookmark.
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            APIError: If the API request fails (e.g., 404 bookmark not found).
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        endpoint = f"bookmarks/{bookmark_id}/lists"
+        response_data = self._call("GET", endpoint)
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            # Return raw data, which might be {"lists": [...]} or something else
+            return response_data
+        else:
+            # Response schema is {"lists": [ListModel]}, extract the list and validate
+            if (
+                isinstance(response_data, dict)
+                and "lists" in response_data
+                and isinstance(response_data["lists"], list)
+            ):
+                try:
+                    return [
+                        datatypes.ListModel.model_validate(lst)
+                        for lst in response_data["lists"]
+                    ]
+                except (
+                    Exception
+                ) as e:  # Catch validation errors during list comprehension
+                    logger.error(f"Validation failed for one or more lists: {e}")
+                    raise  # Re-raise the validation error
+            else:
+                # Raise error if format is unexpected and validation is enabled
+                raise APIError(
+                    f"Unexpected response format for get_lists_of_a_bookmark when validation is enabled: {response_data}"
+                )
+
     @optional_typecheck
     def get_highlights_of_a_bookmark(
         self, bookmark_id: str
@@ -1601,46 +1672,47 @@ class KarakeepAPI:
         return None  # Explicitly return None for 204
 
     @optional_typecheck
-    def get_all_tags(self) -> Union[List[datatypes.Tag], Dict[str, Any], List[Any]]:
+    def get_all_tags(
+        self,
+        name_contains: Optional[str] = None,
+        sort: Optional[Literal["name", "usage", "relevance"]] = None,
+        attached_by: Optional[Literal["ai", "human", "none"]] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Union[datatypes.PaginatedTags, Dict[str, Any], List[Any]]:
         """
         Get all tags for the current user. Corresponds to GET /tags.
 
+        Args:
+            name_contains: Filter tags by name substring (optional).
+            sort: Sort order for tags ("name", "usage", "relevance"). Default from API is "usage" (optional).
+            attached_by: Filter tags by how they were attached ("ai", "human", "none") (optional).
+            cursor: Pagination cursor for the next page (optional).
+            limit: Maximum number of tags to return (optional).
+
         Returns:
-            List[datatypes.Tag]: A list of tag objects, including bookmark counts.
+            datatypes.PaginatedTags: Paginated list of tags with nextCursor for pagination.
             If response validation is disabled, returns the raw API response (dict/list).
 
         Raises:
             APIError: If the API request fails.
             pydantic.ValidationError: If response validation fails (and is not disabled).
         """
-        response_data = self._call("GET", "tags")
+        params = {
+            "nameContains": name_contains,
+            "sort": sort,
+            "attachedBy": attached_by,
+            "cursor": cursor,
+            "limit": limit,
+        }
+        response_data = self._call("GET", "tags", params=params)
 
         if self.disable_response_validation:
             logger.debug("Skipping response validation as requested.")
-            # Return raw data, which might be {"tags": [...]} or something else
             return response_data
         else:
-            # Response schema is {"tags": [Tag]}, extract the list and validate
-            if (
-                isinstance(response_data, dict)
-                and "tags" in response_data
-                and isinstance(response_data["tags"], list)
-            ):
-                try:
-                    return [
-                        datatypes.Tag.model_validate(tag)
-                        for tag in response_data["tags"]
-                    ]
-                except (
-                    Exception
-                ) as e:  # Catch validation errors during list comprehension
-                    logger.error(f"Validation failed for one or more tags: {e}")
-                    raise  # Re-raise the validation error
-            else:
-                # Raise error if format is unexpected and validation is enabled
-                raise APIError(
-                    f"Unexpected response format for get_all_tags when validation is enabled: {response_data}"
-                )
+            # Response should match PaginatedTags schema
+            return datatypes.PaginatedTags.model_validate(response_data)
 
     @optional_typecheck
     def create_a_new_tag(self, name: str) -> Dict[str, Any]:

{karakeep_python_api-1.2.4 → karakeep_python_api-1.3.1}/karakeep_python_api/openapi_reference.json

@@ -94,6 +94,20 @@
             "type": "string",
             "nullable": true
           },
+          "source": {
+            "type": "string",
+            "nullable": true,
+            "enum": [
+              "api",
+              "web",
+              "cli",
+              "mobile",
+              "extension",
+              "singlefile",
+              "rss",
+              "import"
+            ]
+          },
           "tags": {
             "type": "array",
             "items": {
@@ -349,6 +363,50 @@
       "Cursor": {
         "type": "string"
       },
+      "List": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string",
+            "nullable": true
+          },
+          "icon": {
+            "type": "string"
+          },
+          "parentId": {
+            "type": "string",
+            "nullable": true
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "manual",
+              "smart"
+            ],
+            "default": "manual"
+          },
+          "query": {
+            "type": "string",
+            "nullable": true
+          },
+          "public": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "icon",
+          "parentId",
+          "public"
+        ]
+      },
       "Highlight": {
         "type": "object",
         "properties": {
@@ -400,50 +458,6 @@
           "createdAt"
         ]
       },
-      "List": {
-        "type": "object",
-        "properties": {
-          "id": {
-            "type": "string"
-          },
-          "name": {
-            "type": "string"
-          },
-          "description": {
-            "type": "string",
-            "nullable": true
-          },
-          "icon": {
-            "type": "string"
-          },
-          "parentId": {
-            "type": "string",
-            "nullable": true
-          },
-          "type": {
-            "type": "string",
-            "enum": [
-              "manual",
-              "smart"
-            ],
-            "default": "manual"
-          },
-          "query": {
-            "type": "string",
-            "nullable": true
-          },
-          "public": {
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "id",
-          "name",
-          "icon",
-          "parentId",
-          "public"
-        ]
-      },
       "Tag": {
         "type": "object",
         "properties": {
@@ -693,6 +707,22 @@
                           "low",
                           "normal"
                         ]
+                      },
+                      "importSessionId": {
+                        "type": "string"
+                      },
+                      "source": {
+                        "type": "string",
+                        "enum": [
+                          "api",
+                          "web",
+                          "cli",
+                          "mobile",
+                          "extension",
+                          "singlefile",
+                          "rss",
+                          "import"
+                        ]
                       }
                     }
                   },
@@ -781,8 +811,18 @@
           }
         },
         "responses": {
+          "200": {
+            "description": "The bookmark already exists",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Bookmark"
+                }
+              }
+            }
+          },
           "201": {
-            "description": "The created bookmark",
+            "description": "The bookmark got created",
             "content": {
               "application/json": {
                 "schema": {
@@ -1135,6 +1175,20 @@
                     "summary": {
                       "type": "string",
                       "nullable": true
+                    },
+                    "source": {
+                      "type": "string",
+                      "nullable": true,
+                      "enum": [
+                        "api",
+                        "web",
+                        "cli",
+                        "mobile",
+                        "extension",
+                        "singlefile",
+                        "rss",
+                        "import"
+                      ]
                     }
                   },
                   "required": [
@@ -1245,6 +1299,20 @@
                     "summary": {
                       "type": "string",
                       "nullable": true
+                    },
+                    "source": {
+                      "type": "string",
+                      "nullable": true,
+                      "enum": [
+                        "api",
+                        "web",
+                        "cli",
+                        "mobile",
+                        "extension",
+                        "singlefile",
+                        "rss",
+                        "import"
+                      ]
                     }
                   },
                   "required": [
@@ -1469,6 +1537,70 @@
         }
       }
     },
+    "/bookmarks/{bookmarkId}/lists": {
+      "get": {
+        "description": "Get lists of a bookmark",
+        "summary": "Get lists of a bookmark",
+        "tags": [
+          "Bookmarks"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/BookmarkId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The list of highlights",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "lists": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/List"
+                      }
+                    }
+                  },
+                  "required": [
+                    "lists"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Bookmark not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string"
+                    },
+                    "message": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/bookmarks/{bookmarkId}/highlights": {
       "get": {
         "description": "Get highlights of a bookmark",
@@ -2292,6 +2424,60 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "nameContains",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "name",
+                "usage",
+                "relevance"
+              ],
+              "default": "usage"
+            },
+            "required": false,
+            "name": "sort",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "ai",
+                "human",
+                "none"
+              ]
+            },
+            "required": false,
+            "name": "attachedBy",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "cursor",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "number",
+              "nullable": true
+            },
+            "required": false,
+            "name": "limit",
+            "in": "query"
+          }
+        ],
         "responses": {
           "200": {
             "description": "Object with all tags data.",
@@ -2305,10 +2491,15 @@
                       "items": {
                         "$ref": "#/components/schemas/Tag"
                       }
+                    },
+                    "nextCursor": {
+                      "type": "string",
+                      "nullable": true
                     }
                   },
                   "required": [
-                    "tags"
+                    "tags",
+                    "nextCursor"
                   ]
                 }
               }

{karakeep_python_api-1.2.4 → karakeep_python_api-1.3.1/karakeep_python_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 1.2.4
+Version: 1.3.1
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3

{karakeep_python_api-1.2.4 → karakeep_python_api-1.3.1}/setup.py

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

{karakeep_python_api-1.2.4 → karakeep_python_api-1.3.1}/tests/test_karakeep_api.py

@@ -21,9 +21,9 @@ def test_get_all_bookmarks_paginated(karakeep_client: KarakeepAPI):
     try:
         # Get the first page
         page1 = karakeep_client.get_all_bookmarks(limit=2)
-        assert isinstance(
-            page1, datatypes.PaginatedBookmarks
-        ), "Response should be PaginatedBookmarks model"
+        assert isinstance(page1, datatypes.PaginatedBookmarks), (
+            "Response should be PaginatedBookmarks model"
+        )
         assert isinstance(page1.bookmarks, list), "Bookmarks attribute should be a list"
         assert len(page1.bookmarks) <= 2, "Should return at most 'limit' bookmarks"
         logger.info(f"✓ Retrieved first page with {len(page1.bookmarks)} bookmarks.")
@@ -42,9 +42,9 @@ def test_get_all_bookmarks_paginated(karakeep_client: KarakeepAPI):
             )
             # Ensure bookmarks are different from page 1 (simple check)
             if page1.bookmarks and page2.bookmarks:
-                assert (
-                    page1.bookmarks[0].id != page2.bookmarks[0].id
-                ), "Bookmarks on page 1 and 2 should differ"
+                assert page1.bookmarks[0].id != page2.bookmarks[0].id, (
+                    "Bookmarks on page 1 and 2 should differ"
+                )
         else:
             logger.info("  No next cursor found, pagination test ends.")
 
@@ -83,9 +83,9 @@ def test_get_all_lists(karakeep_client: KarakeepAPI):
         lists = karakeep_client.get_all_lists()
         assert isinstance(lists, list), "Response should be a list"
         if lists:  # Only check elements if the list is not empty
-            assert all(
-                isinstance(item, datatypes.ListModel) for item in lists
-            ), "All items should be ListModel instances"
+            assert all(isinstance(item, datatypes.ListModel) for item in lists), (
+                "All items should be ListModel instances"
+            )
         logger.info(f"✓ Successfully retrieved {len(lists)} lists.")
     except (APIError, AuthenticationError) as e:
         pytest.fail(f"API error during list retrieval: {e}")
@@ -118,11 +118,15 @@ def test_get_all_tags(karakeep_client: KarakeepAPI):
     """Test retrieving all tags."""
     try:
         tags = karakeep_client.get_all_tags()
-        assert isinstance(tags, list), "Response should be a list"
+        assert isinstance(tags, datatypes.PaginatedTags), (
+            "Response should be of type PaginatedTags"
+        )
+        tags = tags.tags
+        assert isinstance(tags, list), "tags var should be of type list at this point"
         if tags:  # Only check elements if the list is not empty
-            assert all(
-                isinstance(item, datatypes.Tag) for item in tags
-            ), "All items should be Tag instances"
+            assert all(isinstance(item, datatypes.Tag) for item in tags), (
+                "All items should be Tag instances"
+            )
         logger.info(f"✓ Successfully retrieved {len(tags)} tags.")
     except (APIError, AuthenticationError) as e:
         pytest.fail(f"API error during tag retrieval: {e}")
@@ -156,12 +160,12 @@ def test_get_all_highlights_paginated(karakeep_client: KarakeepAPI):
     try:
         # Get the first page
         page1 = karakeep_client.get_all_highlights(limit=3)
-        assert isinstance(
-            page1, datatypes.PaginatedHighlights
-        ), "Response should be PaginatedHighlights model"
-        assert isinstance(
-            page1.highlights, list
-        ), "Highlights attribute should be a list"
+        assert isinstance(page1, datatypes.PaginatedHighlights), (
+            "Response should be PaginatedHighlights model"
+        )
+        assert isinstance(page1.highlights, list), (
+            "Highlights attribute should be a list"
+        )
         assert len(page1.highlights) <= 3, "Should return at most 'limit' highlights"
         logger.info(f"✓ Retrieved first page with {len(page1.highlights)} highlights.")
 
@@ -179,9 +183,9 @@ def test_get_all_highlights_paginated(karakeep_client: KarakeepAPI):
             )
             # Ensure highlights are different from page 1 (simple check)
             if page1.highlights and page2.highlights:
-                assert (
-                    page1.highlights[0].id != page2.highlights[0].id
-                ), "Highlights on page 1 and 2 should differ"
+                assert page1.highlights[0].id != page2.highlights[0].id, (
+                    "Highlights on page 1 and 2 should differ"
+                )
         else:
             logger.info("  No next cursor found, pagination test ends.")
 
@@ -224,9 +228,9 @@ def test_openapi_spec_accessible(karakeep_client: KarakeepAPI):
         assert spec is not None, "openapi_spec attribute should not be None"
         assert isinstance(spec, dict), "openapi_spec should be a dictionary"
         # Check for a top-level key expected in an OpenAPI spec
-        assert (
-            "openapi" in spec
-        ), "openapi_spec should contain the 'openapi' version key"
+        assert "openapi" in spec, (
+            "openapi_spec should contain the 'openapi' version key"
+        )
         logger.info(
             f"✓ Successfully accessed openapi_spec attribute. Version: {spec.get('openapi', 'N/A')}"
         )
@@ -284,9 +288,9 @@ def test_create_and_delete_list(karakeep_client: KarakeepAPI):
         created_list = karakeep_client.create_a_new_list(
             name=list_name, icon=list_icon, list_type="manual"
         )
-        assert isinstance(
-            created_list, datatypes.ListModel
-        ), "Response should be a ListModel"
+        assert isinstance(created_list, datatypes.ListModel), (
+            "Response should be a ListModel"
+        )
         assert created_list.name == list_name, "Created list name should match"
         assert created_list.icon == list_icon, "Created list icon should match"
         assert created_list.id, "Created list must have an ID"
@@ -295,12 +299,12 @@ def test_create_and_delete_list(karakeep_client: KarakeepAPI):
 
         # 4. Verify the list appears in get_all_lists
         current_lists_after_create = karakeep_client.get_all_lists()
-        assert (
-            len(current_lists_after_create) == initial_list_count + 1
-        ), "List count should increase by one after creation"
-        assert any(
-            lst.id == created_list_id for lst in current_lists_after_create
-        ), "Created list should be present in the list of all lists"
+        assert len(current_lists_after_create) == initial_list_count + 1, (
+            "List count should increase by one after creation"
+        )
+        assert any(lst.id == created_list_id for lst in current_lists_after_create), (
+            "Created list should be present in the list of all lists"
+        )
         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.")
 
@@ -331,21 +335,21 @@ def test_create_and_delete_list(karakeep_client: KarakeepAPI):
                         f"List with ID {created_list_id} should not exist after deletion, but get_a_single_list succeeded."
                     )
                 except APIError as e:
-                    assert (
-                        e.status_code == 404
-                    ), f"Expected 404 Not Found when getting deleted list, but got status {e.status_code}"
+                    assert e.status_code == 404, (
+                        f"Expected 404 Not Found when getting deleted list, but got status {e.status_code}"
+                    )
                     logger.info(
                         f"✓ Confirmed list {created_list_id} is deleted (received 404)."
                     )
 
                 # 8. Verify list count decreased (optional check)
                 final_lists = karakeep_client.get_all_lists()
-                assert (
-                    len(final_lists) == initial_list_count
-                ), "List count should return to initial count after deletion"
-                assert not any(
-                    lst.id == created_list_id for lst in final_lists
-                ), "Deleted list should not be present in the final list of all lists"
+                assert len(final_lists) == initial_list_count, (
+                    "List count should return to initial count after deletion"
+                )
+                assert not any(lst.id == created_list_id for lst in final_lists), (
+                    "Deleted list should not be present in the final list of all lists"
+                )
                 logger.info(f"  Final list count: {len(final_lists)}")
 
             except (APIError, AuthenticationError) as e:
@@ -410,12 +414,12 @@ def test_create_and_delete_bookmark(
             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"
+            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(
@@ -425,9 +429,9 @@ def test_create_and_delete_bookmark(
                 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}'."
+        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}'."
         )
@@ -445,9 +449,9 @@ def test_create_and_delete_bookmark(
                 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}'"
+            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."
             )
@@ -498,12 +502,12 @@ def test_update_bookmark_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}'"
+        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')}'"
         )
@@ -516,9 +520,9 @@ def test_update_bookmark_title(
             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}'"
+        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}'"
         )
@@ -549,9 +553,9 @@ def test_update_bookmark_title(
                 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}'"
+            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}'"
             )
@@ -617,9 +621,9 @@ def test_tag_lifecycle_on_bookmark(
         # 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
@@ -627,12 +631,12 @@ def test_tag_lifecycle_on_bookmark(
             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}'"
@@ -670,9 +674,9 @@ def test_tag_lifecycle_on_bookmark(
                         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}"
+                    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)."
                     )
@@ -725,9 +729,9 @@ def test_cli_get_bookmarks_count_with_jq(karakeep_client: KarakeepAPI):
             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
@@ -821,9 +825,9 @@ def test_asset_lifecycle_with_pdf(karakeep_client: KarakeepAPI):
         assert isinstance(uploaded_asset, datatypes.Asset)
         assert uploaded_asset.assetId, "Uploaded asset must have an ID"
         assert "pdf" in uploaded_asset.contentType.lower(), "Asset should be PDF type"
-        assert (
-            uploaded_asset.fileName == "PDF Bookmark Sample.pdf"
-        ), "Asset filename should match the original file"
+        assert uploaded_asset.fileName == "PDF Bookmark Sample.pdf", (
+            "Asset filename should match the original file"
+        )
         uploaded_asset_id = uploaded_asset.assetId
         logger.info(f"✓ PDF uploaded with asset ID: {uploaded_asset_id}")
 
@@ -848,15 +852,15 @@ def test_asset_lifecycle_with_pdf(karakeep_client: KarakeepAPI):
             bookmark_id=created_bookmark_id
         )
         assert isinstance(retrieved_bookmark, datatypes.Bookmark)
-        assert (
-            len(retrieved_bookmark.assets) > 0
-        ), "Bookmark should have at least one asset"
+        assert len(retrieved_bookmark.assets) > 0, (
+            "Bookmark should have at least one asset"
+        )
 
         # Check that our uploaded asset is among the bookmark's assets
         asset_ids = [asset.id for asset in retrieved_bookmark.assets]
-        assert (
-            uploaded_asset_id in asset_ids
-        ), f"Uploaded asset {uploaded_asset_id} should be attached to bookmark"
+        assert uploaded_asset_id in asset_ids, (
+            f"Uploaded asset {uploaded_asset_id} should be attached to bookmark"
+        )
         logger.info(f"✓ Verified bookmark contains the PDF asset {uploaded_asset_id}")
 
         # 4. Retrieve and verify the asset content