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

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

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

{karakeep_python_api-0.2.0 → karakeep_python_api-0.2.2}/karakeep_python_api/datatypes.py

@@ -1,50 +1,30 @@
-# generated by datamodel-codegen:
-#   filename:  openapi_reference.json
-#   timestamp: 2025-05-04T21:59:34+00:00
+"""
+The datatype file was originally generated by datamodel-codegen, then refactored and manually (or via LLMs) kept up to date with upstream
+"""
 
 from __future__ import annotations
 
 from enum import Enum
-from typing import List, Optional, Union
+from typing import List, Optional, Union, Literal
 
 from pydantic import BaseModel, Field, RootModel
 
 
-class AssetId(RootModel[str]):
-    root: str = Field(..., example="ieidlxygmwj87oxz5hxttoc8")
-
-
-class BookmarkId(RootModel[str]):
-    root: str = Field(..., example="ieidlxygmwj87oxz5hxttoc8")
-
-
-class ListId(RootModel[str]):
-    root: str = Field(..., example="ieidlxygmwj87oxz5hxttoc8")
-
-
-class HighlightId(RootModel[str]):
-    root: str = Field(..., example="ieidlxygmwj87oxz5hxttoc8")
-
-
-class TagId(RootModel[str]):
-    root: str = Field(..., example="ieidlxygmwj87oxz5hxttoc8")
-
-
-class TaggingStatus(str, Enum):
+class StatusTypes(str, Enum):
     success = "success"
     failure = "failure"
     pending = "pending"
 
 
-class AttachedBy(str, Enum):
-    ai = "ai"
-    human = "human"
+class NumBookmarksByAttachedType(BaseModel):
+    ai: Optional[float] = None
+    human: Optional[float] = None
 
 
 class TagShort(BaseModel):
     id: str
     name: str
-    attachedBy: AttachedBy
+    attachedBy: Literal["ai", "human"]
 
 
 class Tag(BaseModel):
@@ -58,8 +38,8 @@ class Type(str, Enum):
     link = "link"
 
 
-class Content(BaseModel):
-    type: Type
+class ContentTypeLink(BaseModel):
+    type: Literal["link"] = "link"
     url: str
     title: Optional[str] = None
     description: Optional[str] = None
@@ -78,36 +58,19 @@ class Content(BaseModel):
     dateModified: Optional[str] = None
 
 
-class TypeText(str, Enum):
-    text = "text"
-
-
-class TypeAsset(str, Enum):
-    asset = "asset"
-
-
-class TypeUnknown(str, Enum):
-    unknown = "unknown"
-
-
-class ContentUnknown(BaseModel):
-    type: TypeUnknown
-
-
-class AssetTypeAssetType(str, Enum):
-    image = "image"
-    pdf = "pdf"
+class ContentTypeUnknown(BaseModel):
+    type: Literal["unknown"] = "unknown"
 
 
 class ContentTypeText(BaseModel):
-    type: TypeText
+    type: Literal["text"] = "text"
     text: str
     sourceUrl: Optional[str] = None
 
 
 class ContentTypeAsset(BaseModel):
-    type: TypeAsset
-    assetType: AssetTypeAssetType
+    type: Literal["asset"] = "asset"
+    assetType: Literal["image", "pdf"]
     assetId: str
     fileName: Optional[str] = None
     sourceUrl: Optional[str] = None
@@ -115,20 +78,18 @@ class ContentTypeAsset(BaseModel):
     content: Optional[str] = None
 
 
-class AssetType(str, Enum):
-    screenshot = "screenshot"
-    assetScreenshot = "assetScreenshot"
-    bannerImage = "bannerImage"
-    fullPageArchive = "fullPageArchive"
-    video = "video"
-    bookmarkAsset = "bookmarkAsset"
-    precrawledArchive = "precrawledArchive"
-    unknown = "unknown"
-
-
 class Asset(BaseModel):
     id: str
-    assetType: AssetType
+    assetType: Literal[
+        "screenshot",
+        "assetScreenshot",
+        "bannerImage",
+        "fullPageArchive",
+        "video",
+        "bookmarkAsset",
+        "precrawledArchive",
+        "unknown",
+    ]
 
 
 class Bookmark(BaseModel):
@@ -138,12 +99,14 @@ class Bookmark(BaseModel):
     title: Optional[str] = None
     archived: bool
     favourited: bool
-    taggingStatus: TaggingStatus
-    summarizationStatus: Optional[TaggingStatus] = None
+    taggingStatus: Literal["success", "failure", "pending"]
+    summarizationStatus: Optional[Literal["success", "failure", "pending"]] = None
     note: Optional[str] = None
     summary: Optional[str] = None
     tags: List[TagShort]
-    content: Union[Content, ContentTypeText, ContentTypeAsset, ContentUnknown]
+    content: Union[
+        ContentTypeLink, ContentTypeText, ContentTypeAsset, ContentTypeUnknown
+    ]
     assets: List[Asset]
 
 
@@ -152,22 +115,11 @@ class PaginatedBookmarks(BaseModel):
     nextCursor: Optional[str]
 
 
-class Cursor(RootModel[str]):
-    root: str
-
-
-class Color(str, Enum):
-    yellow = "yellow"
-    red = "red"
-    green = "green"
-    blue = "blue"
-
-
 class Highlight(BaseModel):
     bookmarkId: str
     startOffset: float
     endOffset: float
-    color: Optional[Color] = "yellow"
+    color: Optional[Literal["yellow", "red", "green", "blue"]] = "yellow"
     text: Optional[str]
     note: Optional[str]
     id: str
@@ -175,26 +127,16 @@ class Highlight(BaseModel):
     createdAt: str
 
 
-class ListType(str, Enum):
-    manual = "manual"
-    smart = "smart"
-
-
 class ListModel(BaseModel):
     id: str
     name: str
     description: Optional[str] = None
     icon: str
     parentId: Optional[str]
-    type: Optional[ListType] = "manual"
+    type: Optional[Literal["manual", "smart"]] = "manual"
     query: Optional[str] = None
 
 
-class NumBookmarksByAttachedType(BaseModel):
-    ai: Optional[float] = None
-    human: Optional[float] = None
-
-
 class PaginatedHighlights(BaseModel):
     highlights: List[Highlight]
     nextCursor: Optional[str]

{karakeep_python_api-0.2.0 → karakeep_python_api-0.2.2}/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.0"
+    VERSION: str = "0.2.2"
 
     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.0 → karakeep_python_api-0.2.2/karakeep_python_api.egg-info}/PKG-INFO

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

{karakeep_python_api-0.2.0 → karakeep_python_api-0.2.2}/setup.py

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