karakeep-python-api 0.1.6__tar.gz → 0.1.7__tar.gz

{karakeep_python_api-0.1.6/karakeep_python_api.egg-info → karakeep_python_api-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 0.1.6
+Version: 0.1.7
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3
@@ -57,7 +57,7 @@ A community-developed Python client for the [Karakeep](https://karakeep.app/) AP
 
 ## Overview
 
-This library provides a Python interface (both a class and a command-line tool) to interact with a Karakeep instance's API.
+This library provides a Python interface (both a class and a command-line tool) to interact with a Karakeep instance's API. The author also developed [freshrss_to_karakeep](https://github.com/thiswillbeyourgithub/freshrss_to_karakeep), a Python script that periodically sends FreshRSS "favourite" articles to Karakeep (a bookmarking and read-it-later app, see [Karakeep on GitHub](https://github.com/karakeep-app/karakeep)).
 
 The development process involved:
 
@@ -238,6 +238,12 @@ except Exception as e:
 
 ```
 
+### Usage Examples
+
+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.
+
 ## Development
 
 1.  Clone the repository.

{karakeep_python_api-0.1.6 → karakeep_python_api-0.1.7}/README.md

@@ -22,7 +22,7 @@ A community-developed Python client for the [Karakeep](https://karakeep.app/) AP
 
 ## Overview
 
-This library provides a Python interface (both a class and a command-line tool) to interact with a Karakeep instance's API.
+This library provides a Python interface (both a class and a command-line tool) to interact with a Karakeep instance's API. The author also developed [freshrss_to_karakeep](https://github.com/thiswillbeyourgithub/freshrss_to_karakeep), a Python script that periodically sends FreshRSS "favourite" articles to Karakeep (a bookmarking and read-it-later app, see [Karakeep on GitHub](https://github.com/karakeep-app/karakeep)).
 
 The development process involved:
 
@@ -203,6 +203,12 @@ except Exception as e:
 
 ```
 
+### Usage Examples
+
+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.
+
 ## Development
 
 1.  Clone the repository.

{karakeep_python_api-0.1.6 → karakeep_python_api-0.1.7}/karakeep_python_api/__main__.py

@@ -286,10 +286,97 @@ def create_click_command(
 
                 # Call the API method
                 try:
-                    logger.debug(
-                        f"Calling API method '{method_name}' with args: {call_args}"
-                    )
-                    result = instance_method(**call_args)
+                    if method_name == "get_all_bookmarks":
+                        logger.debug(f"Special CLI pagination handling for '{method_name}'.")
+                        cli_total_limit = call_args.pop('limit', None)
+                        # Other relevant params for get_all_bookmarks
+                        archived_filter = call_args.get('archived')
+                        favourited_filter = call_args.get('favourited')
+                        include_content_cli = call_args.get('include_content', True) 
+                        
+                        call_args.pop('cursor', None) # Ignore CLI cursor
+
+                        all_bookmarks_data = []
+                        current_page_api_cursor = None
+                        fetched_count = 0
+                        API_INTERNAL_PAGE_SIZE = 50 # Define a page size for API calls
+
+                        while True:
+                            api_call_limit = API_INTERNAL_PAGE_SIZE
+                            if cli_total_limit is not None:
+                                remaining_needed = cli_total_limit - fetched_count
+                                if remaining_needed <= 0:
+                                    break # Reached or exceeded CLI total limit
+                                api_call_limit = min(API_INTERNAL_PAGE_SIZE, remaining_needed)
+                            
+                            if api_call_limit <= 0 and cli_total_limit is not None : # Avoid asking for 0 or negative items unless fetching all
+                                break
+
+
+                            logger.debug(f"Fetching page for '{method_name}' with cursor: {current_page_api_cursor}, api_limit: {api_call_limit}")
+                            
+                            page_call_args = {
+                                'archived': archived_filter,
+                                'favourited': favourited_filter,
+                                'limit': api_call_limit,
+                                'cursor': current_page_api_cursor,
+                                'include_content': include_content_cli,
+                            }
+                            page_call_args_filtered = {k: v for k, v in page_call_args.items() if v is not None}
+
+                            try:
+                                page_result_obj = instance_method(**page_call_args_filtered)
+                            except TypeError as call_error_page:
+                                logger.error(f"Error calling API method '{method_name}' (paginated): {call_error_page}")
+                                logger.error(f"Provided arguments for page: {page_call_args_filtered}")
+                                if verbose: logger.debug(traceback.format_exc())
+                                ctx.exit(1)
+
+                            bookmarks_on_this_page = []
+                            next_api_cursor = None
+
+                            # Convert Pydantic model to dict using model_dump if available
+                            if hasattr(page_result_obj, 'model_dump'):
+                                result_dict = page_result_obj.model_dump()
+                            elif isinstance(page_result_obj, dict):
+                                result_dict = page_result_obj
+                            else:
+                                logger.warning(f"Unexpected result type: {type(page_result_obj)}")
+                                result_dict = {}
+
+                            # Extract data and cursor from the dict
+                            bookmarks_on_this_page = result_dict.get("bookmarks", [])
+                            next_api_cursor = result_dict.get("nextCursor")
+
+                            logger.debug(f"Extracted {len(bookmarks_on_this_page)} bookmarks and cursor: {next_api_cursor}")
+                            
+                            if not isinstance(bookmarks_on_this_page, list):
+                                logger.warning(f"Expected a list of bookmarks, got {type(bookmarks_on_this_page)}. Stopping pagination.")
+                                break
+                            
+                            all_bookmarks_data.extend(bookmarks_on_this_page)
+                            fetched_count += len(bookmarks_on_this_page)
+                            logger.debug(f"Fetched {len(bookmarks_on_this_page)} bookmarks this page. Total fetched: {fetched_count}.")
+
+                            current_page_api_cursor = next_api_cursor
+                            if not current_page_api_cursor:
+                                logger.debug("No nextCursor from API, pagination complete.")
+                                break
+                            if cli_total_limit is not None and fetched_count >= cli_total_limit:
+                                logger.debug(f"CLI total limit of {cli_total_limit} reached or exceeded.")
+                                break
+                            if not bookmarks_on_this_page and api_call_limit > 0:
+                                logger.debug("API returned an empty list of bookmarks while a positive limit was set, assuming end of data.")
+                                break
+                        
+                        result = all_bookmarks_data # This will be a list of Bookmark models or dicts
+                    else:
+                        # Original behavior for other commands
+                        logger.debug(
+                            f"Calling API method '{method_name}' with args: {call_args}"
+                        )
+                        result = instance_method(**call_args)
+
                 except TypeError as call_error:
                     logger.error(
                         f"Error calling API method '{method_name}': {call_error}"
@@ -460,16 +547,33 @@ def create_click_command(
 
         click_required = is_required_in_sig and default_value is None and not is_flag
 
+        # Make copies of properties that might be modified for specific commands/params
+        current_param_help = param_help
+        current_click_required = click_required
+        current_default_value = default_value
+        current_is_flag = is_flag # Though is_flag interpretation might change help/required
+        
+        # Special handling for 'get_all_bookmarks' command parameters
+        if api_method_name == "get_all_bookmarks":
+            if param.name == "cursor":
+                current_param_help = "[Ignored by CLI for get-all-bookmarks] " + param_help
+                current_click_required = False  # Cursor is handled by CLI, not required from user
+                current_default_value = None  # Explicitly set default to None for ignored param
+            elif param.name == "limit":
+                current_param_help = "Total maximum number of bookmarks to fetch across pages for get-all-bookmarks. If omitted, all are fetched."
+                # For 'limit', required status and default remain as derived from its Optional[int] type hint
+                # current_click_required and current_default_value will be correctly False and None respectively.
+
         # Add the Click Option
         click_params.append(
             click.Option(
                 option_names,
                 type=click_type,
-                required=click_required,
-                default=default_value if not is_flag else None,
-                help=param_help,
-                is_flag=(is_flag if len(option_names) == 1 else False),
-                show_default=not is_flag and default_value is not None, # Show default unless it's a flag or None
+                required=current_click_required,
+                default=current_default_value if not current_is_flag else None,
+                help=current_param_help,
+                is_flag=(current_is_flag if len(option_names) == 1 else False),
+                show_default=not current_is_flag and current_default_value is not None,
                 # Click derives the Python identifier (e.g., 'bookmark_id') from the first long option name
             )
         )

{karakeep_python_api-0.1.6 → karakeep_python_api-0.1.7}/karakeep_python_api/datatypes.py

@@ -30,13 +30,13 @@ class HighlightId(RootModel[str]):
     root: str = Field(..., example="ieidlxygmwj87oxz5hxttoc8")
 
 
-class TaggingStatus(Enum):
+class TaggingStatus(str, Enum):
     success = "success"
     failure = "failure"
     pending = "pending"
 
 
-class AttachedBy(Enum):
+class AttachedBy(str, Enum):
     ai = "ai"
     human = "human"
 
@@ -47,7 +47,7 @@ class Tag(BaseModel):
     attachedBy: AttachedBy
 
 
-class Type(Enum):
+class Type(str, Enum):
     link = "link"
 
 
@@ -71,7 +71,7 @@ class Content(BaseModel):
     dateModified: Optional[str] = None
 
 
-class Type1(Enum):
+class Type1(str, Enum):
     text = "text"
 
 
@@ -81,11 +81,11 @@ class Content1(BaseModel):
     sourceUrl: Optional[str] = None
 
 
-class Type2(Enum):
+class Type2(str, Enum):
     asset = "asset"
 
 
-class AssetType(Enum):
+class AssetType(str, Enum):
     image = "image"
     pdf = "pdf"
 
@@ -100,7 +100,7 @@ class Content2(BaseModel):
     content: Optional[str] = None
 
 
-class Type3(Enum):
+class Type3(str, Enum):
     unknown = "unknown"
 
 
@@ -108,7 +108,7 @@ class Content3(BaseModel):
     type: Type3
 
 
-class AssetType1(Enum):
+class AssetType1(str, Enum):
     screenshot = "screenshot"
     assetScreenshot = "assetScreenshot"
     bannerImage = "bannerImage"
@@ -148,7 +148,7 @@ class Cursor(RootModel[str]):
     root: str
 
 
-class Color(Enum):
+class Color(str, Enum):
     yellow = "yellow"
     red = "red"
     green = "green"
@@ -167,7 +167,7 @@ class Highlight(BaseModel):
     createdAt: str
 
 
-class Type4(Enum):
+class Type4(str, Enum):
     manual = "manual"
     smart = "smart"
 

{karakeep_python_api-0.1.6 → karakeep_python_api-0.1.7}/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.6"
+    VERSION: str = "0.1.7"
 
     def __init__(
         self,
@@ -578,9 +578,10 @@ class KarakeepAPI:
             ) from e
 
     @optional_typecheck
-    def _enforce_rate_limit(self, min_interval_sec: float = 2.0) -> None:
+    def _enforce_rate_limit(self, min_interval_sec: float = 0.5) -> None:
         """
         Ensures a minimum time interval between consecutive API calls.
+        Otherwise karakeep tends to error out.
 
         If the time since the last call is less than `min_interval_sec`, this method
         will sleep for the remaining duration. It then updates the timestamp of the
@@ -610,23 +611,36 @@ class KarakeepAPI:
         self,
         archived: Optional[bool] = None,
         favourited: Optional[bool] = None,
-        limit: Optional[int] = None,
+        limit: Optional[int] = None, # This is the per-page limit for the API
         cursor: Optional[str] = None,
         include_content: bool = True,  # Default from spec
     ) -> Any:  # Returns PaginatedBookmarks or raw dict/list
         """
-        Get all bookmarks. Corresponds to GET /bookmarks.
+        Get bookmarks, one page at a time. Corresponds to GET /bookmarks.
+
+        This method fetches a single page of bookmarks.
+        The 'limit' parameter controls the number of items per page for this API call.
+        The 'cursor' parameter is used for pagination to get the next page.
+
+        CLI Usage Notes:
+        - When the 'get-all-bookmarks' command is used via the CLI:
+          - The `--cursor` CLI option is ignored; pagination is handled automatically.
+          - The `--limit` CLI option specifies the *total* number of bookmarks to fetch
+            across multiple pages. If omitted, all bookmarks are fetched.
+          - The CLI internally calls this API method multiple times to achieve this.
 
         Args:
             archived: Filter by archived status (optional).
             favourited: Filter by favourited status (optional).
-            limit: Maximum number of bookmarks to return (optional).
-            cursor: Pagination cursor for the next page (optional).
+            limit: Maximum number of bookmarks to return *per page* in this API call (optional).
+                   When used from the CLI's 'get-all-bookmarks' command, this translates to an
+                   internal per-page fetching limit, while the CLI's `--limit` controls the total.
+            cursor: Pagination cursor for fetching the next page (optional).
             include_content: If set to true, bookmark's content will be included (default: True).
 
         Returns:
-            datatypes.PaginatedBookmarks: Paginated list of bookmarks.
-            If response validation is disabled, returns the raw API response (dict/list).
+            datatypes.PaginatedBookmarks: Paginated list of bookmarks for the current page.
+            If response validation is disabled, returns the raw API response (dict/list) for the current page.
 
         Raises:
             APIError: If the API request fails.

{karakeep_python_api-0.1.6 → karakeep_python_api-0.1.7}/karakeep_python_api/openapi_reference.json

@@ -2876,4 +2876,4 @@
       }
     }
   }
-}
+}

{karakeep_python_api-0.1.6 → karakeep_python_api-0.1.7/karakeep_python_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 0.1.6
+Version: 0.1.7
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3
@@ -57,7 +57,7 @@ A community-developed Python client for the [Karakeep](https://karakeep.app/) AP
 
 ## Overview
 
-This library provides a Python interface (both a class and a command-line tool) to interact with a Karakeep instance's API.
+This library provides a Python interface (both a class and a command-line tool) to interact with a Karakeep instance's API. The author also developed [freshrss_to_karakeep](https://github.com/thiswillbeyourgithub/freshrss_to_karakeep), a Python script that periodically sends FreshRSS "favourite" articles to Karakeep (a bookmarking and read-it-later app, see [Karakeep on GitHub](https://github.com/karakeep-app/karakeep)).
 
 The development process involved:
 
@@ -238,6 +238,12 @@ except Exception as e:
 
 ```
 
+### Usage Examples
+
+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.
+
 ## Development
 
 1.  Clone the repository.

{karakeep_python_api-0.1.6 → karakeep_python_api-0.1.7}/setup.py

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

@@ -600,6 +600,64 @@ def test_tag_lifecycle_on_bookmark(karakeep_client: KarakeepAPI, managed_bookmar
 
 # --- Test User Info/Stats Endpoints ---
 
+def test_cli_get_bookmarks_count_with_jq(karakeep_client: KarakeepAPI):
+    """Test that CLI get-all-bookmarks with --limit returns the expected number of items."""
+    # Skip test if jq is not installed
+    try:
+        subprocess.run(["jq", "--version"], check=True, capture_output=True)
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pytest.skip("jq is not installed. This test requires jq for JSON processing.")
+    
+    # Define the limit we want to test
+    test_limit = 200
+    
+    try:
+        logger.info(f"\nRunning CLI command: get-all-bookmarks --limit={test_limit}")
+        # Use a two-command pipe: Run the CLI command and pipe to jq to count array length
+        cmd = f"python -m karakeep_python_api --verbose get-all-bookmarks --limit={test_limit} | jq 'length'"
+        
+        # Execute the piped command
+        result = subprocess.run(
+            cmd,
+            shell=True,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        
+        # Parse the output (should be just a number)
+        try:
+            actual_count = int(result.stdout.strip())
+            logger.info(f"✓ Command returned {actual_count} bookmarks")
+            
+            # Check if we got exactly the requested number or fewer (if there aren't enough bookmarks)
+            assert actual_count <= test_limit, f"Expected at most {test_limit} bookmarks, got {actual_count}"
+            
+            # Check if we got any bookmarks at all (to ensure the test is meaningful)
+            # This could fail if the account has no bookmarks
+            assert actual_count > 0, "Expected at least some bookmarks to be returned"
+            
+            # If the account has enough bookmarks, we should get exactly the limit
+            # But we can't assert this because we don't know how many bookmarks exist
+            if actual_count < test_limit:
+                logger.info(f"Note: Only {actual_count} bookmarks were returned, which is less than the requested limit of {test_limit}. This is acceptable if the account doesn't have {test_limit} bookmarks.")
+            else:
+                logger.info(f"✓ Command returned exactly the requested limit of {test_limit} bookmarks")
+                
+        except ValueError:
+            logger.error(f"Failed to parse jq output as integer: '{result.stdout}'")
+            pytest.fail(f"jq output is not a valid integer: '{result.stdout}'")
+            
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Command failed with exit code {e.returncode}")
+        logger.error(f"Stdout: {e.stdout}")
+        logger.error(f"Stderr: {e.stderr}")
+        pytest.fail(f"CLI command failed: {e}")
+    except Exception as e:
+        logger.error(f"An unexpected error occurred: {e}")
+        pytest.fail(f"Unexpected error: {e}")
+
+
 def test_get_current_user_stats(karakeep_client: KarakeepAPI):
     """Test retrieving statistics for the current user."""
     try: