karakeep-python-api 0.2.3__tar.gz → 1.1.0__tar.gz

{karakeep_python_api-0.2.3/karakeep_python_api.egg-info → karakeep_python_api-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 0.2.3
+Version: 1.1.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)
 
@@ -136,7 +137,7 @@ This package can be used as a Python library or as a command-line interface (CLI
 
 The client can be configured using the following environment variables:
 
-*   `KARAKEEP_PYTHON_API_BASE_URL`: **Required**. The full base URL of your Karakeep API, including the `/api/v1/` path (e.g., `https://your-karakeep.example.com/api/v1/` or `https://try.karakeep.app/api/v1/`).
+*   `KARAKEEP_PYTHON_API_ENDPOINT`: **Required**. The full URL of your Karakeep API, including the `/api/v1/` path (e.g., `https://karakeep.domain.com/api/v1/` or `https://try.karakeep.app/api/v1/`).
 *   `KARAKEEP_PYTHON_API_KEY`: **Required**. Your Karakeep API key (Bearer token).
 *   `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`).
@@ -145,7 +146,7 @@ The client can be configured using the following environment variables:
 
 ### Command Line Interface (CLI)
 
-The CLI dynamically generates commands based on the API methods. You need to provide your API key and base URL either via environment variables (recommended) or command-line options.
+The CLI dynamically generates commands based on the API methods. You need to provide your API key and endpoint either via environment variables (recommended) or command-line options.
 
 **Basic Structure:**
 
@@ -170,8 +171,8 @@ python -m karakeep_python_api get-all-bookmarks --help
 python -m karakeep_python_api get-all-tags
 
 # Get the first page of bookmarks with a limit, overriding env vars if needed
-# Note: Ensure the base URL includes the /api/v1/ path
-python -m karakeep_python_api --base-url https://my.karakeep.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
+# Note: The /api/v1/ path will be automatically appended if not present
+python -m karakeep_python_api --base-url https://karakeep.domain.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
 
 # Get all lists and pipe the JSON output to jq to extract the first list
 python -m karakeep_python_api get-all-lists | jq '.[0]'
@@ -195,14 +196,14 @@ import os
 from karakeep_python_api import KarakeepAPI, APIError, AuthenticationError, datatypes
 
 # Ensure required environment variables are set
-# Example: os.environ["KARAKEEP_PYTHON_API_BASE_URL"] = "https://your-karakeep.example.com/api/v1/"
+# Example: os.environ["KARAKEEP_PYTHON_API_ENDPOINT"] = "https://karakeep.domain.com/api/v1/"
 # Example: os.environ["KARAKEEP_PYTHON_API_KEY"] = "your_secret_api_key"
 
 try:
     # Initialize the client (reads from env vars by default)
     client = KarakeepAPI(
         # Optionally override env vars:
-        # base_url="https://another.karakeep.com",
+        # api_endpoint="https://karakeep.domain.com/api/v1/",
         # api_key="another_key",
         # verbose=True,
         # disable_response_validation=False
@@ -232,23 +233,27 @@ except AuthenticationError as e:
 except APIError as e:
     print(f"An API error occurred: {e}")
 except ValueError as e:
-    # Handles missing API key/base URL during initialization
+    # Handles missing API key/endpoint during initialization
     print(f"Configuration error: {e}")
 except Exception as e:
     print(f"An unexpected error occurred: {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!
+Community Scripts are a bunch of scripts made to solve specific issues. They are made by the community so don't hesitate to submit yours or open an issue if you have a bug. They also serve as example of how to use the API.
 
-| 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. | [`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 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) |
+They can be found in the [./community_scripts](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts) folder. Don't hesitate to submit yours, the contribution guidelines are in the community_scripts directory README.md file.
+
+| Community Script | Description                                                                                                                                                                            | Documentation |
+|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
+| **Karakeep-Time-Tagger** | 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. | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/karakeep-time-tagger) |
+| **Karakeep-List-To-Tag** | Converts a Karakeep list into tags by adding a specified tag to all bookmarks within that list.                                                                                        | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/karakeep-list-to-tag) |
+| **Omnivore2Karakeep-Highlights** | Imports highlights from Omnivore export data to Karakeep, with intelligent position detection and bookmark matching. Supports dry-run mode for testing.                                | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/omnivore2karakeep-highlights) |
+| **Omnivore2Karakeep-Archived** | (Should not be needed anymore) Fixes the archived status of bookmarks imported from Omnivore by reading export data and updating Karakeep accordingly.                                 | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/omnivore2karakeep-archived) |
+| **pocket2karakeep-archived** by [@youenchene](https://github.com/youenchene) | (Should not be needed anymore) Fixes the archived status of bookmarks imported from Pocket by reading export data and updating Karakeep accordingly.                                   | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/pocket2karakeep-archived) |
+| **karakeep-archive-before-date** by [@youenchene](https://github.com/youenchene) | Allow you to archive all not archived post before a given date                                                                                                                         | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/karakeep-archive-before-date) |
 
 ## Development
 
@@ -259,7 +264,7 @@ Examples of the API being used can be found in the [`./examples`](./examples) fo
     ```bash
     uv pip install -e ".[dev]"
     ```
-4.  Set the required environment variables (`KARAKEEP_PYTHON_API_BASE_URL`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
+4.  Set the required environment variables (`KARAKEEP_PYTHON_API_ENDPOINT`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
 5.  Run tests:
 
     ```bash

{karakeep_python_api-0.2.3 → karakeep_python_api-1.1.0}/README.md

@@ -17,6 +17,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)
 
@@ -101,7 +102,7 @@ This package can be used as a Python library or as a command-line interface (CLI
 
 The client can be configured using the following environment variables:
 
-*   `KARAKEEP_PYTHON_API_BASE_URL`: **Required**. The full base URL of your Karakeep API, including the `/api/v1/` path (e.g., `https://your-karakeep.example.com/api/v1/` or `https://try.karakeep.app/api/v1/`).
+*   `KARAKEEP_PYTHON_API_ENDPOINT`: **Required**. The full URL of your Karakeep API, including the `/api/v1/` path (e.g., `https://karakeep.domain.com/api/v1/` or `https://try.karakeep.app/api/v1/`).
 *   `KARAKEEP_PYTHON_API_KEY`: **Required**. Your Karakeep API key (Bearer token).
 *   `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`).
@@ -110,7 +111,7 @@ The client can be configured using the following environment variables:
 
 ### Command Line Interface (CLI)
 
-The CLI dynamically generates commands based on the API methods. You need to provide your API key and base URL either via environment variables (recommended) or command-line options.
+The CLI dynamically generates commands based on the API methods. You need to provide your API key and endpoint either via environment variables (recommended) or command-line options.
 
 **Basic Structure:**
 
@@ -135,8 +136,8 @@ python -m karakeep_python_api get-all-bookmarks --help
 python -m karakeep_python_api get-all-tags
 
 # Get the first page of bookmarks with a limit, overriding env vars if needed
-# Note: Ensure the base URL includes the /api/v1/ path
-python -m karakeep_python_api --base-url https://my.karakeep.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
+# Note: The /api/v1/ path will be automatically appended if not present
+python -m karakeep_python_api --base-url https://karakeep.domain.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
 
 # Get all lists and pipe the JSON output to jq to extract the first list
 python -m karakeep_python_api get-all-lists | jq '.[0]'
@@ -160,14 +161,14 @@ import os
 from karakeep_python_api import KarakeepAPI, APIError, AuthenticationError, datatypes
 
 # Ensure required environment variables are set
-# Example: os.environ["KARAKEEP_PYTHON_API_BASE_URL"] = "https://your-karakeep.example.com/api/v1/"
+# Example: os.environ["KARAKEEP_PYTHON_API_ENDPOINT"] = "https://karakeep.domain.com/api/v1/"
 # Example: os.environ["KARAKEEP_PYTHON_API_KEY"] = "your_secret_api_key"
 
 try:
     # Initialize the client (reads from env vars by default)
     client = KarakeepAPI(
         # Optionally override env vars:
-        # base_url="https://another.karakeep.com",
+        # api_endpoint="https://karakeep.domain.com/api/v1/",
         # api_key="another_key",
         # verbose=True,
         # disable_response_validation=False
@@ -197,23 +198,27 @@ except AuthenticationError as e:
 except APIError as e:
     print(f"An API error occurred: {e}")
 except ValueError as e:
-    # Handles missing API key/base URL during initialization
+    # Handles missing API key/endpoint during initialization
     print(f"Configuration error: {e}")
 except Exception as e:
     print(f"An unexpected error occurred: {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!
+Community Scripts are a bunch of scripts made to solve specific issues. They are made by the community so don't hesitate to submit yours or open an issue if you have a bug. They also serve as example of how to use the API.
 
-| 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. | [`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 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) |
+They can be found in the [./community_scripts](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts) folder. Don't hesitate to submit yours, the contribution guidelines are in the community_scripts directory README.md file.
+
+| Community Script | Description                                                                                                                                                                            | Documentation |
+|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
+| **Karakeep-Time-Tagger** | 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. | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/karakeep-time-tagger) |
+| **Karakeep-List-To-Tag** | Converts a Karakeep list into tags by adding a specified tag to all bookmarks within that list.                                                                                        | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/karakeep-list-to-tag) |
+| **Omnivore2Karakeep-Highlights** | Imports highlights from Omnivore export data to Karakeep, with intelligent position detection and bookmark matching. Supports dry-run mode for testing.                                | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/omnivore2karakeep-highlights) |
+| **Omnivore2Karakeep-Archived** | (Should not be needed anymore) Fixes the archived status of bookmarks imported from Omnivore by reading export data and updating Karakeep accordingly.                                 | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/omnivore2karakeep-archived) |
+| **pocket2karakeep-archived** by [@youenchene](https://github.com/youenchene) | (Should not be needed anymore) Fixes the archived status of bookmarks imported from Pocket by reading export data and updating Karakeep accordingly.                                   | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/pocket2karakeep-archived) |
+| **karakeep-archive-before-date** by [@youenchene](https://github.com/youenchene) | Allow you to archive all not archived post before a given date                                                                                                                         | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/karakeep-archive-before-date) |
 
 ## Development
 
@@ -224,7 +229,7 @@ Examples of the API being used can be found in the [`./examples`](./examples) fo
     ```bash
     uv pip install -e ".[dev]"
     ```
-4.  Set the required environment variables (`KARAKEEP_PYTHON_API_BASE_URL`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
+4.  Set the required environment variables (`KARAKEEP_PYTHON_API_ENDPOINT`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
 5.  Run tests:
 
     ```bash

{karakeep_python_api-0.2.3 → karakeep_python_api-1.1.0}/karakeep_python_api/__main__.py

@@ -59,9 +59,9 @@ def serialize_output(data: Any) -> Any:
 # Shared options for the API client
 shared_options = [
     click.option(
-        "--base-url",
-        envvar="KARAKEEP_PYTHON_API_BASE_URL",
-        help="Full Karakeep API base URL, including /api/v1/ (e.g., https://instance.com/api/v1/).",
+        "--api-endpoint",
+        envvar="KARAKEEP_PYTHON_API_ENDPOINT",
+        help="Full Karakeep API endpoint URL, including /api/v1/ (e.g., https://instance.com/api/v1/).",
     ),
     click.option(
         "--api-key",
@@ -151,7 +151,7 @@ def print_openapi_spec(ctx, param, value):
 @click.pass_context
 def cli(
     ctx,
-    base_url,
+    api_endpoint,
     api_key,
     verify_ssl,
     verbose,
@@ -167,7 +167,7 @@ def cli(
     # Ensure the context object exists
     ctx.ensure_object(dict)
 
-    # --- Strict Check for API Key and Base URL ---
+    # --- Strict Check for API Key and Endpoint ---
     # Check for API key (must be provided via arg or env)
     resolved_api_key = api_key or os.environ.get("KARAKEEP_PYTHON_API_KEY")
     if not resolved_api_key:
@@ -175,16 +175,18 @@ def cli(
             "API Key is required. Provide --api-key option or set KARAKEEP_PYTHON_API_KEY environment variable."
         )
 
-    # Check for Base URL (must be provided via arg or env)
-    resolved_base_url = base_url or os.environ.get("KARAKEEP_PYTHON_API_BASE_URL")
-    if not resolved_base_url:
+    # Check for API endpoint (must be provided via arg or env)
+    resolved_api_endpoint = api_endpoint or os.environ.get(
+        "KARAKEEP_PYTHON_API_ENDPOINT"
+    )
+    if not resolved_api_endpoint:
         raise click.UsageError(
-            "API Base URL is required. Provide --base-url option or set KARAKEEP_PYTHON_API_BASE_URL environment variable. "
+            "API endpoint is required. Provide --api-endpoint option or set KARAKEEP_PYTHON_API_ENDPOINT environment variable. "
             "The URL must include the API path, e.g., 'https://your-instance.com/api/v1/'."
         )
 
     # Store common API parameters in the context for commands to use
-    ctx.obj["BASE_URL"] = resolved_base_url  # Store the resolved URL
+    ctx.obj["API_ENDPOINT"] = resolved_api_endpoint  # Store the resolved endpoint
     ctx.obj["API_KEY"] = resolved_api_key  # Store the resolved key
     ctx.obj["VERIFY_SSL"] = verify_ssl
     ctx.obj["VERBOSE"] = verbose
@@ -231,7 +233,7 @@ def create_click_command(
         def command_func(ctx, **kwargs):
             """Dynamically generated command function wrapper."""
             # Retrieve API parameters from context, ensuring API key is present now
-            base_url = ctx.obj["BASE_URL"]
+            api_endpoint = ctx.obj["API_ENDPOINT"]
             api_key = ctx.obj["API_KEY"]
             verify_ssl = ctx.obj["VERIFY_SSL"]
             verbose = ctx.obj["VERBOSE"]
@@ -250,7 +252,7 @@ def create_click_command(
                 # Method generation already happened during inspection phase or initial load
                 api = KarakeepAPI(
                     api_key=api_key,
-                    base_url=base_url,
+                    api_endpoint=api_endpoint,
                     verify_ssl=verify_ssl,
                     verbose=verbose,
                     disable_response_validation=disable_validation,  # Pass flag to constructor

{karakeep_python_api-0.2.3 → karakeep_python_api-1.1.0}/karakeep_python_api/datatypes.py

@@ -135,6 +135,7 @@ class ListModel(BaseModel):
     parentId: Optional[str]
     type: Optional[Literal["manual", "smart"]] = "manual"
     query: Optional[str] = None
+    public: bool
 
 
 class PaginatedHighlights(BaseModel):