karakeep-python-api 0.2.2__py3-none-any.whl → 1.0.0__py3-none-any.whl

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.dist-info → karakeep_python_api-1.0.0.dist-info}/METADATA

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

@@ -1,11 +1,11 @@
 karakeep_python_api/__init__.py,sha256=qk3MeIIvnCNAyYzJrv8dMKVXvA4ejLU3mhB3xFzdLDY,606
 karakeep_python_api/__main__.py,sha256=UfL6R-S3rJB7PH3iqTicNq0cvtumnrG_FVyKK36bqdE,32327
 karakeep_python_api/datatypes.py,sha256=CScuMq5oT4YwvGH8Af_Oo60xGmC622d74f4WPUw7l8Q,3398
-karakeep_python_api/karakeep_api.py,sha256=Ft8FjCzRhDiAYwSMj6c1l2X_6EftJOIrvv_tYGOYMUc,81921
+karakeep_python_api/karakeep_api.py,sha256=Fpyc3A4Gph3czirIDztsvzbtnegmkDLmiJNDCdgTt04,84749
 karakeep_python_api/openapi_reference.json,sha256=Ku1cO_N4QPLQc7sK8L7FRt2T68QyPCwTGA7RK-046iU,80379
-karakeep_python_api-0.2.2.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-karakeep_python_api-0.2.2.dist-info/METADATA,sha256=b0THcqqdtYH1GfB16HIBhI0-7TSEJnlwXTAUUaTXClE,12967
-karakeep_python_api-0.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-karakeep_python_api-0.2.2.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
-karakeep_python_api-0.2.2.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
-karakeep_python_api-0.2.2.dist-info/RECORD,,
+karakeep_python_api-1.0.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+karakeep_python_api-1.0.0.dist-info/METADATA,sha256=joWnEpuTHNzpSr4U4EJ-Xb48YK8_YU-rrYHW9HWGsAg,14026
+karakeep_python_api-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+karakeep_python_api-1.0.0.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
+karakeep_python_api-1.0.0.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
+karakeep_python_api-1.0.0.dist-info/RECORD,,