karakeep-python-api 0.1.0__tar.gz → 0.1.2__tar.gz

{karakeep_python_api-0.1.0/karakeep_python_api.egg-info → karakeep_python_api-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 0.1.0
+Version: 0.1.2
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3
@@ -81,7 +81,7 @@ The following table lists the public methods available in the `KarakeepAPI` clas
 | `search_bookmarks`               |   ✅   | Tested as part of create/delete flow.        |
 | `get_a_single_bookmark`          |   ✅   | Tested as part of create/delete flow.        |
 | `delete_a_bookmark`              |   ✅   | Tested as part of create/delete flow.        |
-| `update_a_bookmark`              |   ❌   |                                              |
+| `update_a_bookmark`              |   ✅   | Tested for title updates.                    |
 | `summarize_a_bookmark`           |   ❌   |                                              |
 | `attach_tags_to_a_bookmark`      |   ❌   |                                              |
 | `detach_tags_from_a_bookmark`    |   ❌   |                                              |
@@ -137,6 +137,7 @@ The client can be configured using the following environment variables:
 *   `KARAKEEP_PYTHON_API_VERIFY_SSL`: Set to `false` to disable SSL certificate verification (default: `true`).
 *   `KARAKEEP_PYTHON_API_VERBOSE`: Set to `true` to enable verbose debug logging for the client and CLI (default: `false`).
 *   `KARAKEEP_PYTHON_API_DISABLE_RESPONSE_VALIDATION`: Set to `true` to disable Pydantic validation of API responses. The client will return raw dictionary/list data instead of Pydantic models (default: `false`).
+*   `KARAKEEP_PYTHON_API_ENSURE_ASCII`: Set to `true` to escape non-ASCII characters in the JSON output (default: `false`, which means Unicode characters are kept).
 
 ### Command Line Interface (CLI)
 
@@ -174,6 +175,9 @@ python -m karakeep_python_api get-all-lists | jq '.[0]'
 # Create a new bookmark from a link (body provided as JSON string)
 python -m karakeep_python_api create-a-new-bookmark --data '{"type": "link", "url": "https://example.com"}'
 
+# Get all tags and ensure ASCII output (e.g., for compatibility with systems that don't handle Unicode well)
+python -m karakeep_python_api --ascii get-all-tags
+
 # Dump the raw OpenAPI spec used by the client
 python -m karakeep_python_api --dump-openapi-specification
 ```

{karakeep_python_api-0.1.0 → karakeep_python_api-0.1.2}/README.md

@@ -46,7 +46,7 @@ The following table lists the public methods available in the `KarakeepAPI` clas
 | `search_bookmarks`               |   ✅   | Tested as part of create/delete flow.        |
 | `get_a_single_bookmark`          |   ✅   | Tested as part of create/delete flow.        |
 | `delete_a_bookmark`              |   ✅   | Tested as part of create/delete flow.        |
-| `update_a_bookmark`              |   ❌   |                                              |
+| `update_a_bookmark`              |   ✅   | Tested for title updates.                    |
 | `summarize_a_bookmark`           |   ❌   |                                              |
 | `attach_tags_to_a_bookmark`      |   ❌   |                                              |
 | `detach_tags_from_a_bookmark`    |   ❌   |                                              |
@@ -102,6 +102,7 @@ The client can be configured using the following environment variables:
 *   `KARAKEEP_PYTHON_API_VERIFY_SSL`: Set to `false` to disable SSL certificate verification (default: `true`).
 *   `KARAKEEP_PYTHON_API_VERBOSE`: Set to `true` to enable verbose debug logging for the client and CLI (default: `false`).
 *   `KARAKEEP_PYTHON_API_DISABLE_RESPONSE_VALIDATION`: Set to `true` to disable Pydantic validation of API responses. The client will return raw dictionary/list data instead of Pydantic models (default: `false`).
+*   `KARAKEEP_PYTHON_API_ENSURE_ASCII`: Set to `true` to escape non-ASCII characters in the JSON output (default: `false`, which means Unicode characters are kept).
 
 ### Command Line Interface (CLI)
 
@@ -139,6 +140,9 @@ python -m karakeep_python_api get-all-lists | jq '.[0]'
 # Create a new bookmark from a link (body provided as JSON string)
 python -m karakeep_python_api create-a-new-bookmark --data '{"type": "link", "url": "https://example.com"}'
 
+# Get all tags and ensure ASCII output (e.g., for compatibility with systems that don't handle Unicode well)
+python -m karakeep_python_api --ascii get-all-tags
+
 # Dump the raw OpenAPI spec used by the client
 python -m karakeep_python_api --dump-openapi-specification
 ```

{karakeep_python_api-0.1.0 → karakeep_python_api-0.1.2}/karakeep_python_api/__main__.py

@@ -1,8 +1,10 @@
+from textwrap import dedent
 import inspect
 import json
 import sys
 import os
 import functools
+import re  # Import re module
 import click
 import traceback  # Moved import to top
 from typing import Any, List, Dict, Optional, Callable, Union, get_origin, get_args, Literal
@@ -79,6 +81,14 @@ shared_options = [
         envvar="KARAKEEP_PYTHON_API_DISABLE_RESPONSE_VALIDATION",
         help="Disable Pydantic validation of API responses (returns raw data).",
     ),
+    click.option(
+        "--ascii",
+        "ensure_ascii", # Use 'ensure_ascii' as the destination variable name
+        is_flag=True,
+        default=False, # Default is False, meaning ensure_ascii=False by default
+        envvar="KARAKEEP_PYTHON_API_ENSURE_ASCII",
+        help="Escape non-ASCII characters in the JSON output (default: keep Unicode).",
+    ),
 ]
 
 
@@ -126,9 +136,9 @@ def print_openapi_spec(ctx, param, value):
     is_eager=True,  # Process this option before others
     help="Dump the OpenAPI specification JSON to stdout and exit.",
 )
-@add_options(shared_options)  # Apply shared options to the group
+@add_options(shared_options)  # Apply shared options to the group (ensure_ascii is now included)
 @click.pass_context
-def cli(ctx, base_url, api_key, verify_ssl, verbose, disable_response_validation):
+def cli(ctx, base_url, api_key, verify_ssl, verbose, disable_response_validation, ensure_ascii):
     """
     Karakeep Python API Command Line Interface.
 
@@ -162,6 +172,7 @@ def cli(ctx, base_url, api_key, verify_ssl, verbose, disable_response_validation
     ctx.obj["DISABLE_RESPONSE_VALIDATION"] = (
         disable_response_validation  # Store the flag
     )
+    ctx.obj["ENSURE_ASCII"] = ensure_ascii # Store the ensure_ascii flag
 
     # --- Configure Logger ---
     log_level = "DEBUG" if verbose else "INFO"
@@ -198,6 +209,7 @@ def create_click_command(
             verify_ssl = ctx.obj["VERIFY_SSL"]
             verbose = ctx.obj["VERBOSE"]
             disable_validation = ctx.obj["DISABLE_RESPONSE_VALIDATION"]  # Retrieve flag
+            ensure_ascii_output = ctx.obj["ENSURE_ASCII"] # Retrieve ensure_ascii flag
 
             if not api_key:
                 click.echo(
@@ -238,9 +250,32 @@ def create_click_command(
                     k: v for k, v in call_args.items() if k in valid_arg_names
                 }
 
-                # Note: No special '--data' handling needed anymore for create_a_new_bookmark
-                # Type conversion for basic types (str, int, bool) is handled by Click.
-                # List/Dict parameters still expect JSON strings if used elsewhere.
+                # --- JSON Parsing for Dict/List Parameters ---
+                # Iterate through the expected parameters from the signature
+                for param_name, param_sig in signature.parameters.items():
+                    if param_name in call_args:
+                        param_value = call_args[param_name]
+                        param_annotation = param_sig.annotation
+                        origin = getattr(param_annotation, "__origin__", None)
+
+                        # Check if the annotation is dict/list or typing.Dict/List
+                        # and if the received value is a string (needs parsing)
+                        if (
+                            (param_annotation in (dict, list) or origin in (dict, list, Dict, List))
+                            and isinstance(param_value, str)
+                        ):
+                            try:
+                                # Attempt to parse the JSON string
+                                call_args[param_name] = json.loads(param_value)
+                                logger.debug(f"Parsed JSON string for parameter '{param_name}'.")
+                            except json.JSONDecodeError as json_err:
+                                # Handle invalid JSON input from the user
+                                click.echo(
+                                    f"Error: Invalid JSON provided for parameter '{param_name.replace('_', '-')}': {json_err}",
+                                    err=True,
+                                )
+                                click.echo(f"Provided value: {param_value}", err=True)
+                                ctx.exit(1)
 
                 # Call the API method
                 try:
@@ -262,9 +297,10 @@ def create_click_command(
                 # Serialize and print the result
                 if result is not None:
                     output_data = serialize_output(result)
+                    # Use ensure_ascii_output flag to control JSON encoding
                     click.echo(
-                        json.dumps(output_data, indent=2)
-                    )  # Keep this for stdout result
+                        json.dumps(output_data, indent=2, ensure_ascii=ensure_ascii_output)
+                    )
                 else:
                     # Handle None result (e.g., 204 No Content) gracefully
                     # Verbose check is implicitly handled by logger level
@@ -302,35 +338,45 @@ def create_click_command(
     click_params = []
     # Use the docstring from the original method (captured by functools.update_wrapper)
     docstring = api_method.__doc__ or f"Execute the {api_method_name} API operation."
+    docstring = dedent(docstring)
     docstring_lines = docstring.split("\n")
-    help_text = docstring_lines[0].strip()  # First line as short help
-    full_help = docstring  # Full docstring as help
+    help_text = " ".join(docstring.split("\n\n")[0].splitlines()).strip()  # First lines as short help
+    # Full docstring as help
+    full_help = docstring
+
+    # tweak the whitespaces in the full help:
+    # full_help = full_help.replace("\n", "\n\n").replace("\n                ", " ")
+    full_help = full_help.replace("\n               ", " ")
+    full_help = full_help.replace("\n", "\n\n")
 
     # Extract parameter descriptions from the Args section of the docstring
     param_descriptions = {}
     in_args_section = False
     args_section_lines = []
+    assert "Returns:" in docstring
+    assert "Raises:" in docstring
     for line in docstring_lines:
-        stripped_line = line.strip()  # Corrected indentation
-        if stripped_line == "Args:":  # Corrected indentation
-            in_args_section = True  # Corrected indentation
+        stripped_line = line.strip()
+        if stripped_line == "Args:":
+            in_args_section = True
         elif (
             stripped_line == "Returns:" or stripped_line == "Raises:"
-        ):  # Corrected indentation
-            in_args_section = False  # Stop capturing when Returns/Raises section starts # Corrected indentation
-        elif in_args_section and stripped_line:  # Corrected indentation
-            args_section_lines.append(stripped_line)  # Corrected indentation
-            # Try parsing the parameter name and description
-            parts = stripped_line.split(":", 1)  # Corrected indentation
-            if len(parts) == 2:  # Corrected indentation
-                # Extract name, assuming format "name (type): description"
-                name_part = parts[0].split(" ")[0]  # Corrected indentation
-                # Clean potential trailing parenthesis from type hint parsing
-                name_part = name_part.rstrip(")")  # Corrected indentation
-                param_descriptions[name_part] = parts[
-                    1
-                ].strip()  # Corrected indentation
+        ):
+            in_args_section = False  # Stop capturing when Returns/Raises section starts
+        elif in_args_section and stripped_line:
+            args_section_lines.append(stripped_line)
+            # Use regex to capture 'param_name: description' structure, allowing leading whitespace
+            # Pattern: ^\s+ (parameter_name): \s* (description) $
+            match = re.match(r"^\s+([a-zA-Z_][a-zA-Z0-9_]*):\s+(.*)$", line)
+            if match and match.group(1) != "Example":
+                param_name = match.group(1)
+                description = match.group(2).strip()
+                param_descriptions[param_name] = description
+                logger.trace(f"Parsed docstring param: '{param_name}' -> '{description}'")
+            else:
+                param_descriptions[param_name] += " " + stripped_line
 
+    # Removed breakpoint() that was added for debugging
     # Add parameters from signature to Click command
     for param in params:  # Use the filtered list from signature inspection
         param_name_cli = param.name.replace("_", "-")  # Use kebab-case for CLI options

{karakeep_python_api-0.1.0 → karakeep_python_api-0.1.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.1.0"
+    VERSION: str = "0.1.2"
 
     def __init__(
         self,
@@ -209,7 +209,7 @@ class KarakeepAPI:
         self.strict_response_parsing = (
             strict_response_parsing  # Currently unused but kept
         )
-        self.last_request_time: float = 0.0  # Initialize timestamp for rate limiting
+        self.last_request_time: float = time.monotonic()  # Initialize timestamp for rate limiting
 
         # --- Response Validation Setting ---
         # Argument takes precedence over environment variable
@@ -463,7 +463,7 @@ class KarakeepAPI:
                         logger.warning(
                             f"Error encounterd during requests. Trial={trial}/{max_trial}. Retrying after a small wait.\nError: {e}"
                         )
-                        time.sleep(trial * 2)
+                        time.sleep(trial * 3)
                     else:
                         raise
 
@@ -590,7 +590,7 @@ class KarakeepAPI:
             ) from e
 
     @optional_typecheck
-    def _enforce_rate_limit(self, min_interval_sec: float = 1.0) -> None:
+    def _enforce_rate_limit(self, min_interval_sec: float = 2.0) -> None:
         """
         Ensures a minimum time interval between consecutive API calls.
 
@@ -855,6 +855,7 @@ class KarakeepAPI:
         """
         Delete a bookmark by its ID. Corresponds to DELETE /bookmarks/{bookmarkId}.
 
+        Args:
             bookmark_id: The ID (string) of the bookmark to delete.
 
         Returns:
@@ -901,6 +902,7 @@ class KarakeepAPI:
         Summarize a bookmark by its ID. Corresponds to POST /bookmarks/{bookmarkId}/summarize.
         This triggers the summarization process and returns the updated bookmark record (partially).
 
+        Args:
             bookmark_id: The ID (string) of the bookmark to summarize.
 
         Returns:
@@ -924,6 +926,7 @@ class KarakeepAPI:
         """
         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).
@@ -950,6 +953,7 @@ class KarakeepAPI:
         """
         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).
@@ -976,6 +980,7 @@ class KarakeepAPI:
         """
         Get all highlights associated with a specific bookmark. Corresponds to GET /bookmarks/{bookmarkId}/highlights.
 
+        Args:
             bookmark_id: The ID (string) of the bookmark.
 
         Returns:
@@ -1023,6 +1028,7 @@ class KarakeepAPI:
         """
         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"}`
@@ -1054,6 +1060,7 @@ class KarakeepAPI:
         Replace an existing asset associated with a bookmark with a new one.
         Corresponds to PUT /bookmarks/{bookmarkId}/assets/{assetId}.
 
+        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).
@@ -1074,6 +1081,7 @@ class KarakeepAPI:
         """
         Detach an asset from a bookmark. Corresponds to DELETE /bookmarks/{bookmarkId}/assets/{assetId}.
 
+        Args:
             bookmark_id: The ID (string) of the bookmark.
             asset_id: The ID (string) of the asset to detach.
 
@@ -1092,6 +1100,7 @@ class KarakeepAPI:
         """
         Get all lists for the current user. Corresponds to GET /lists.
 
+        Returns:
             List[datatypes.ListModel]: A list of list objects.
             If response validation is disabled, returns the raw API response (dict/list).
 
@@ -1135,6 +1144,7 @@ class KarakeepAPI:
         """
         Create a new list (manual or smart). Corresponds to POST /lists.
 
+        Args:
             list_data: Dictionary containing the data for the new list. Requires "name" (string) and "icon" (string).
                        Optional fields include "description", "parentId", "type" ('manual' or 'smart'), "query".
                        See the OpenAPI spec for details. Example: `{"name": "My List", "icon": "📚"}`
@@ -1163,6 +1173,7 @@ class KarakeepAPI:
         """
         Get a single list by its ID. Corresponds to GET /lists/{listId}.
 
+        Args:
             list_id: The ID (string) of the list to retrieve.
 
         Returns:
@@ -1188,6 +1199,7 @@ class KarakeepAPI:
         """
         Delete a list by its ID. Corresponds to DELETE /lists/{listId}.
 
+        Args:
             list_id: The ID (string) of the list to delete.
 
         Returns:
@@ -1208,6 +1220,7 @@ class KarakeepAPI:
         Update a list by its ID. Corresponds to PATCH /lists/{listId}.
         Allows updating fields like "name", "description", "icon", "parentId", "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.
@@ -1241,6 +1254,7 @@ class KarakeepAPI:
         """
         Get the bookmarks contained within a specific list. Corresponds to GET /lists/{listId}/bookmarks.
 
+        Args:
             list_id: The ID (string) of the list.
             limit: Maximum number of bookmarks to return (optional).
             cursor: Pagination cursor for the next page (optional).
@@ -1274,6 +1288,7 @@ class KarakeepAPI:
         """
         Add a bookmark to a specific list. Corresponds to PUT /lists/{listId}/bookmarks/{bookmarkId}.
 
+        Args:
             list_id: The ID (string) of the list.
             bookmark_id: The ID (string) of the bookmark to add.
 
@@ -1292,6 +1307,7 @@ class KarakeepAPI:
         """
         Remove a bookmark from a specific list. Corresponds to DELETE /lists/{listId}/bookmarks/{bookmarkId}.
 
+        Args:
             list_id: The ID (string) of the list.
             bookmark_id: The ID (string) of the bookmark to remove.
 
@@ -1310,6 +1326,7 @@ class KarakeepAPI:
         """
         Get all tags for the current user. Corresponds to GET /tags.
 
+        Returns:
             List[datatypes.Tag1]: A list of tag objects, including bookmark counts.
             If response validation is disabled, returns the raw API response (dict/list).
 
@@ -1351,6 +1368,7 @@ class KarakeepAPI:
         """
         Get a single tag by its ID. Corresponds to GET /tags/{tagId}.
 
+        Args:
             tag_id: The ID (string) of the tag to retrieve.
 
         Returns:
@@ -1376,6 +1394,7 @@ class KarakeepAPI:
         """
         Delete a tag by its ID. Corresponds to DELETE /tags/{tagId}.
 
+        Args:
             tag_id: The ID (string) of the tag to delete.
 
         Returns:
@@ -1396,6 +1415,7 @@ class KarakeepAPI:
         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"}`
@@ -1429,6 +1449,7 @@ class KarakeepAPI:
         """
         Get the bookmarks associated with a specific tag. Corresponds to GET /tags/{tagId}/bookmarks.
 
+        Args:
             tag_id: The ID (string) of the tag.
             limit: Maximum number of bookmarks to return (optional).
             cursor: Pagination cursor for the next page (optional).
@@ -1493,6 +1514,7 @@ class KarakeepAPI:
         """
         Create a new highlight on a bookmark. Corresponds to POST /highlights.
 
+        Args:
             highlight_data: Dictionary containing the data for the new highlight. Requires "bookmarkId" (string),
                             "startOffset" (number), "endOffset" (number). Optional fields include "color", "text", "note".
                             See the OpenAPI spec for details. Example: `{"bookmarkId": "...", "startOffset": 10, "endOffset": 25}`
@@ -1521,6 +1543,7 @@ class KarakeepAPI:
         """
         Get a single highlight by its ID. Corresponds to GET /highlights/{highlightId}.
 
+        Args:
             highlight_id: The ID (string) of the highlight to retrieve.
 
         Returns:
@@ -1549,6 +1572,7 @@ class KarakeepAPI:
         Delete a highlight by its ID. Corresponds to DELETE /highlights/{highlightId}.
         Note: Unlike most DELETE endpoints, this returns the deleted highlight object on success (status 200).
 
+        Args:
             highlight_id: The ID (string) of the highlight to delete.
 
         Returns:
@@ -1577,6 +1601,7 @@ class KarakeepAPI:
         Update a highlight by its ID. Currently only supports updating the "color".
         Corresponds to PATCH /highlights/{highlightId}.
 
+        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"}`
@@ -1604,6 +1629,7 @@ class KarakeepAPI:
         """
         Get information about the current authenticated user. Corresponds to GET /users/me.
 
+        Returns:
             dict: A dictionary containing user information ('id', 'name', 'email').
                   Validation is not performed on this response type by default.
 
@@ -1619,6 +1645,7 @@ class KarakeepAPI:
         """
         Get statistics about the current authenticated user's data. Corresponds to GET /users/me/stats.
 
+        Returns:
             dict: A dictionary containing user statistics ('numBookmarks', 'numFavorites', 'numArchived', etc.).
                   Validation is not performed on this response type by default.
 

{karakeep_python_api-0.1.0 → karakeep_python_api-0.1.2/karakeep_python_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 0.1.0
+Version: 0.1.2
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3
@@ -81,7 +81,7 @@ The following table lists the public methods available in the `KarakeepAPI` clas
 | `search_bookmarks`               |   ✅   | Tested as part of create/delete flow.        |
 | `get_a_single_bookmark`          |   ✅   | Tested as part of create/delete flow.        |
 | `delete_a_bookmark`              |   ✅   | Tested as part of create/delete flow.        |
-| `update_a_bookmark`              |   ❌   |                                              |
+| `update_a_bookmark`              |   ✅   | Tested for title updates.                    |
 | `summarize_a_bookmark`           |   ❌   |                                              |
 | `attach_tags_to_a_bookmark`      |   ❌   |                                              |
 | `detach_tags_from_a_bookmark`    |   ❌   |                                              |
@@ -137,6 +137,7 @@ The client can be configured using the following environment variables:
 *   `KARAKEEP_PYTHON_API_VERIFY_SSL`: Set to `false` to disable SSL certificate verification (default: `true`).
 *   `KARAKEEP_PYTHON_API_VERBOSE`: Set to `true` to enable verbose debug logging for the client and CLI (default: `false`).
 *   `KARAKEEP_PYTHON_API_DISABLE_RESPONSE_VALIDATION`: Set to `true` to disable Pydantic validation of API responses. The client will return raw dictionary/list data instead of Pydantic models (default: `false`).
+*   `KARAKEEP_PYTHON_API_ENSURE_ASCII`: Set to `true` to escape non-ASCII characters in the JSON output (default: `false`, which means Unicode characters are kept).
 
 ### Command Line Interface (CLI)
 
@@ -174,6 +175,9 @@ python -m karakeep_python_api get-all-lists | jq '.[0]'
 # Create a new bookmark from a link (body provided as JSON string)
 python -m karakeep_python_api create-a-new-bookmark --data '{"type": "link", "url": "https://example.com"}'
 
+# Get all tags and ensure ASCII output (e.g., for compatibility with systems that don't handle Unicode well)
+python -m karakeep_python_api --ascii get-all-tags
+
 # Dump the raw OpenAPI spec used by the client
 python -m karakeep_python_api --dump-openapi-specification
 ```

{karakeep_python_api-0.1.0 → karakeep_python_api-0.1.2}/setup.py

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

@@ -4,6 +4,7 @@ import subprocess
 import random
 import string
 import time
+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
@@ -484,6 +485,104 @@ def test_create_and_delete_bookmark(karakeep_client: KarakeepAPI):
             )
 
 
+def test_update_bookmark_title(karakeep_client: KarakeepAPI):
+    """Test updating a bookmark's title via API and CLI."""
+    created_bookmark_id = None
+    # Generate a unique suffix for the initial title to avoid collisions
+    timestamp = int(time.time())
+    random_suffix = "".join(random.choices(string.ascii_lowercase + string.digits, k=6))
+    original_title = f"Initial Test Title {timestamp}-{random_suffix}"
+    test_url = "https://en.wikipedia.org/wiki/PageForBookmarkUpdateTest" # A distinct URL for this test
+    
+    target_api_title = "this is a test title"
+    target_cli_title = "this is a test title (CLI)"
+
+    try:
+        # 1. Create a bookmark with an initial title
+        print(f"\nAttempting to create bookmark for URL: {test_url} with original title: '{original_title}'")
+        created_bookmark = karakeep_client.create_a_new_bookmark(
+            type="link", url=test_url, title=original_title
+        )
+        assert isinstance(created_bookmark, datatypes.Bookmark), "Response should be a Bookmark model"
+        created_bookmark_id = created_bookmark.id
+        assert created_bookmark.id, "Created bookmark must have an ID"
+        assert created_bookmark.title == original_title, f"Initial title '{created_bookmark.title}' does not match expected '{original_title}'"
+        print(f"✓ Successfully created bookmark ID: {created_bookmark_id}, Title: '{created_bookmark.title}'")
+
+        # 2. Update the bookmark's title using the API client
+        print(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}'"
+        print(f"✓ API call to update_a_bookmark successful. Partial response title: '{updated_bookmark_partial.get('title')}'")
+
+        # 3. Verify the API update by fetching the bookmark again
+        print(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}'"
+        print(f"✓ Successfully verified bookmark title updated by API to: '{retrieved_bookmark_after_api_update.title}'")
+
+        # 4. Test CLI equivalent for updating the bookmark's title
+        print(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,
+                shell=True,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            print("✓ CLI update command executed successfully.")
+
+            # 5. Verify CLI update by fetching the bookmark again
+            print(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}'"
+            print(f"✓ Successfully verified bookmark title updated by CLI to: '{retrieved_bookmark_after_cli_update.title}'")
+
+        except subprocess.CalledProcessError as e:
+            print(f"  CLI update command failed with exit code {e.returncode}")
+            print(f"  Command: {cli_update_command}")
+            print(f"  Stdout: {e.stdout}")
+            print(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}")
+
+    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}")
+    finally:
+        # 6. Delete the bookmark (ensure cleanup)
+        if created_bookmark_id:
+            print(f"\nAttempting to delete bookmark ID: {created_bookmark_id} during cleanup.")
+            try:
+                karakeep_client.delete_a_bookmark(bookmark_id=created_bookmark_id)
+                print(f"✓ Successfully deleted bookmark ID: {created_bookmark_id}")
+            except Exception as e:
+                # Log cleanup failure but don't obscure original test failure if any
+                print(f"Error during cleanup: Failed to delete bookmark {created_bookmark_id}: {e}")
+                # Depending on test policy, you might re-raise or just log
+                # pytest.fail(f"Failed to delete bookmark {created_bookmark_id} during cleanup: {e}")
+
+
 # --- Test User Info/Stats Endpoints ---
 
 def test_get_current_user_stats(karakeep_client: KarakeepAPI):