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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. {karakeep_python_api-1.0.0/karakeep_python_api.egg-info → karakeep_python_api-1.1.0}/PKG-INFO +20 -17
  2. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/README.md +19 -16
  3. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api/__main__.py +14 -12
  4. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api/datatypes.py +1 -0
  5. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api/karakeep_api.py +41 -33
  6. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api/openapi_reference.json +8 -1
  7. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0/karakeep_python_api.egg-info}/PKG-INFO +20 -17
  8. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/setup.py +1 -1
  9. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/tests/test_karakeep_api.py +5 -5
  10. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/LICENSE +0 -0
  11. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/MANIFEST.in +0 -0
  12. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api/__init__.py +0 -0
  13. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api.egg-info/SOURCES.txt +0 -0
  14. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api.egg-info/dependency_links.txt +0 -0
  15. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api.egg-info/entry_points.txt +0 -0
  16. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api.egg-info/requires.txt +0 -0
  17. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api.egg-info/top_level.txt +0 -0
  18. {karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/setup.cfg +0 -0
{karakeep_python_api-1.0.0/karakeep_python_api.egg-info → karakeep_python_api-1.1.0}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: karakeep_python_api
3
- Version: 1.0.0
3
+ Version: 1.1.0
4
4
  Summary: Community python client for the Karakeep API.
5
5
  Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
6
6
  License: GPLv3
@@ -137,7 +137,7 @@ This package can be used as a Python library or as a command-line interface (CLI
137
137
 
138
138
  The client can be configured using the following environment variables:
139
139
 
140
- * `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/`).
140
+ * `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/`).
141
141
  * `KARAKEEP_PYTHON_API_KEY`: **Required**. Your Karakeep API key (Bearer token).
142
142
  * `KARAKEEP_PYTHON_API_VERIFY_SSL`: Set to `false` to disable SSL certificate verification (default: `true`).
143
143
  * `KARAKEEP_PYTHON_API_VERBOSE`: Set to `true` to enable verbose debug logging for the client and CLI (default: `false`).
@@ -146,7 +146,7 @@ The client can be configured using the following environment variables:
146
146
 
147
147
  ### Command Line Interface (CLI)
148
148
 
149
- 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.
149
+ 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.
150
150
 
151
151
  **Basic Structure:**
152
152
 
@@ -171,8 +171,8 @@ python -m karakeep_python_api get-all-bookmarks --help
171
171
  python -m karakeep_python_api get-all-tags
172
172
 
173
173
  # Get the first page of bookmarks with a limit, overriding env vars if needed
174
- # Note: Ensure the base URL includes the /api/v1/ path
175
- python -m karakeep_python_api --base-url https://my.karakeep.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
174
+ # Note: The /api/v1/ path will be automatically appended if not present
175
+ python -m karakeep_python_api --base-url https://karakeep.domain.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
176
176
 
177
177
  # Get all lists and pipe the JSON output to jq to extract the first list
178
178
  python -m karakeep_python_api get-all-lists | jq '.[0]'
@@ -196,14 +196,14 @@ import os
196
196
  from karakeep_python_api import KarakeepAPI, APIError, AuthenticationError, datatypes
197
197
 
198
198
  # Ensure required environment variables are set
199
- # Example: os.environ["KARAKEEP_PYTHON_API_BASE_URL"] = "https://your-karakeep.example.com/api/v1/"
199
+ # Example: os.environ["KARAKEEP_PYTHON_API_ENDPOINT"] = "https://karakeep.domain.com/api/v1/"
200
200
  # Example: os.environ["KARAKEEP_PYTHON_API_KEY"] = "your_secret_api_key"
201
201
 
202
202
  try:
203
203
  # Initialize the client (reads from env vars by default)
204
204
  client = KarakeepAPI(
205
205
  # Optionally override env vars:
206
- # base_url="https://another.karakeep.com",
206
+ # api_endpoint="https://karakeep.domain.com/api/v1/",
207
207
  # api_key="another_key",
208
208
  # verbose=True,
209
209
  # disable_response_validation=False
@@ -233,7 +233,7 @@ except AuthenticationError as e:
233
233
  except APIError as e:
234
234
  print(f"An API error occurred: {e}")
235
235
  except ValueError as e:
236
- # Handles missing API key/base URL during initialization
236
+ # Handles missing API key/endpoint during initialization
237
237
  print(f"Configuration error: {e}")
238
238
  except Exception as e:
239
239
  print(f"An unexpected error occurred: {e}")
@@ -242,15 +242,18 @@ except Exception as e:
242
242
 
243
243
  ## Community Scripts
244
244
 
245
- Examples of the API being used can be found in the [`./examples`](./examples) folder. Don't hesitate to submit yours!
245
+ 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.
246
246
 
247
- | Example Script | Description | Documentation |
248
- |----------------|-------------|---------------|
249
- | **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) |
250
- | **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) |
251
- | **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) |
252
- | **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) |
253
- | **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) |
247
+ 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.
248
+
249
+ | Community Script | Description | Documentation |
250
+ |----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
251
+ | **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) |
252
+ | **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) |
253
+ | **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) |
254
+ | **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) |
255
+ | **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) |
256
+ | **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) |
254
257
 
255
258
  ## Development
256
259
 
@@ -261,7 +264,7 @@ Examples of the API being used can be found in the [`./examples`](./examples) fo
261
264
  ```bash
262
265
  uv pip install -e ".[dev]"
263
266
  ```
264
- 4. Set the required environment variables (`KARAKEEP_PYTHON_API_BASE_URL`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
267
+ 4. Set the required environment variables (`KARAKEEP_PYTHON_API_ENDPOINT`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
265
268
  5. Run tests:
266
269
 
267
270
  ```bash
{karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/README.md RENAMED
@@ -102,7 +102,7 @@ This package can be used as a Python library or as a command-line interface (CLI
102
102
 
103
103
  The client can be configured using the following environment variables:
104
104
 
105
- * `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/`).
105
+ * `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/`).
106
106
  * `KARAKEEP_PYTHON_API_KEY`: **Required**. Your Karakeep API key (Bearer token).
107
107
  * `KARAKEEP_PYTHON_API_VERIFY_SSL`: Set to `false` to disable SSL certificate verification (default: `true`).
108
108
  * `KARAKEEP_PYTHON_API_VERBOSE`: Set to `true` to enable verbose debug logging for the client and CLI (default: `false`).
@@ -111,7 +111,7 @@ The client can be configured using the following environment variables:
111
111
 
112
112
  ### Command Line Interface (CLI)
113
113
 
114
- 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.
114
+ 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.
115
115
 
116
116
  **Basic Structure:**
117
117
 
@@ -136,8 +136,8 @@ python -m karakeep_python_api get-all-bookmarks --help
136
136
  python -m karakeep_python_api get-all-tags
137
137
 
138
138
  # Get the first page of bookmarks with a limit, overriding env vars if needed
139
- # Note: Ensure the base URL includes the /api/v1/ path
140
- python -m karakeep_python_api --base-url https://my.karakeep.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
139
+ # Note: The /api/v1/ path will be automatically appended if not present
140
+ python -m karakeep_python_api --base-url https://karakeep.domain.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
141
141
 
142
142
  # Get all lists and pipe the JSON output to jq to extract the first list
143
143
  python -m karakeep_python_api get-all-lists | jq '.[0]'
@@ -161,14 +161,14 @@ import os
161
161
  from karakeep_python_api import KarakeepAPI, APIError, AuthenticationError, datatypes
162
162
 
163
163
  # Ensure required environment variables are set
164
- # Example: os.environ["KARAKEEP_PYTHON_API_BASE_URL"] = "https://your-karakeep.example.com/api/v1/"
164
+ # Example: os.environ["KARAKEEP_PYTHON_API_ENDPOINT"] = "https://karakeep.domain.com/api/v1/"
165
165
  # Example: os.environ["KARAKEEP_PYTHON_API_KEY"] = "your_secret_api_key"
166
166
 
167
167
  try:
168
168
  # Initialize the client (reads from env vars by default)
169
169
  client = KarakeepAPI(
170
170
  # Optionally override env vars:
171
- # base_url="https://another.karakeep.com",
171
+ # api_endpoint="https://karakeep.domain.com/api/v1/",
172
172
  # api_key="another_key",
173
173
  # verbose=True,
174
174
  # disable_response_validation=False
@@ -198,7 +198,7 @@ except AuthenticationError as e:
198
198
  except APIError as e:
199
199
  print(f"An API error occurred: {e}")
200
200
  except ValueError as e:
201
- # Handles missing API key/base URL during initialization
201
+ # Handles missing API key/endpoint during initialization
202
202
  print(f"Configuration error: {e}")
203
203
  except Exception as e:
204
204
  print(f"An unexpected error occurred: {e}")
@@ -207,15 +207,18 @@ except Exception as e:
207
207
 
208
208
  ## Community Scripts
209
209
 
210
- Examples of the API being used can be found in the [`./examples`](./examples) folder. Don't hesitate to submit yours!
210
+ 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.
211
211
 
212
- | Example Script | Description | Documentation |
213
- |----------------|-------------|---------------|
214
- | **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) |
215
- | **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) |
216
- | **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) |
217
- | **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) |
218
- | **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) |
212
+ 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.
213
+
214
+ | Community Script | Description | Documentation |
215
+ |----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
216
+ | **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) |
217
+ | **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) |
218
+ | **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) |
219
+ | **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) |
220
+ | **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) |
221
+ | **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) |
219
222
 
220
223
  ## Development
221
224
 
@@ -226,7 +229,7 @@ Examples of the API being used can be found in the [`./examples`](./examples) fo
226
229
  ```bash
227
230
  uv pip install -e ".[dev]"
228
231
  ```
229
- 4. Set the required environment variables (`KARAKEEP_PYTHON_API_BASE_URL`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
232
+ 4. Set the required environment variables (`KARAKEEP_PYTHON_API_ENDPOINT`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
230
233
  5. Run tests:
231
234
 
232
235
  ```bash
{karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api/__main__.py RENAMED
@@ -59,9 +59,9 @@ def serialize_output(data: Any) -> Any:
59
59
  # Shared options for the API client
60
60
  shared_options = [
61
61
  click.option(
62
- "--base-url",
63
- envvar="KARAKEEP_PYTHON_API_BASE_URL",
64
- help="Full Karakeep API base URL, including /api/v1/ (e.g., https://instance.com/api/v1/).",
62
+ "--api-endpoint",
63
+ envvar="KARAKEEP_PYTHON_API_ENDPOINT",
64
+ help="Full Karakeep API endpoint URL, including /api/v1/ (e.g., https://instance.com/api/v1/).",
65
65
  ),
66
66
  click.option(
67
67
  "--api-key",
@@ -151,7 +151,7 @@ def print_openapi_spec(ctx, param, value):
151
151
  @click.pass_context
152
152
  def cli(
153
153
  ctx,
154
- base_url,
154
+ api_endpoint,
155
155
  api_key,
156
156
  verify_ssl,
157
157
  verbose,
@@ -167,7 +167,7 @@ def cli(
167
167
  # Ensure the context object exists
168
168
  ctx.ensure_object(dict)
169
169
 
170
- # --- Strict Check for API Key and Base URL ---
170
+ # --- Strict Check for API Key and Endpoint ---
171
171
  # Check for API key (must be provided via arg or env)
172
172
  resolved_api_key = api_key or os.environ.get("KARAKEEP_PYTHON_API_KEY")
173
173
  if not resolved_api_key:
@@ -175,16 +175,18 @@ def cli(
175
175
  "API Key is required. Provide --api-key option or set KARAKEEP_PYTHON_API_KEY environment variable."
176
176
  )
177
177
 
178
- # Check for Base URL (must be provided via arg or env)
179
- resolved_base_url = base_url or os.environ.get("KARAKEEP_PYTHON_API_BASE_URL")
180
- if not resolved_base_url:
178
+ # Check for API endpoint (must be provided via arg or env)
179
+ resolved_api_endpoint = api_endpoint or os.environ.get(
180
+ "KARAKEEP_PYTHON_API_ENDPOINT"
181
+ )
182
+ if not resolved_api_endpoint:
181
183
  raise click.UsageError(
182
- "API Base URL is required. Provide --base-url option or set KARAKEEP_PYTHON_API_BASE_URL environment variable. "
184
+ "API endpoint is required. Provide --api-endpoint option or set KARAKEEP_PYTHON_API_ENDPOINT environment variable. "
183
185
  "The URL must include the API path, e.g., 'https://your-instance.com/api/v1/'."
184
186
  )
185
187
 
186
188
  # Store common API parameters in the context for commands to use
187
- ctx.obj["BASE_URL"] = resolved_base_url # Store the resolved URL
189
+ ctx.obj["API_ENDPOINT"] = resolved_api_endpoint # Store the resolved endpoint
188
190
  ctx.obj["API_KEY"] = resolved_api_key # Store the resolved key
189
191
  ctx.obj["VERIFY_SSL"] = verify_ssl
190
192
  ctx.obj["VERBOSE"] = verbose
@@ -231,7 +233,7 @@ def create_click_command(
231
233
  def command_func(ctx, **kwargs):
232
234
  """Dynamically generated command function wrapper."""
233
235
  # Retrieve API parameters from context, ensuring API key is present now
234
- base_url = ctx.obj["BASE_URL"]
236
+ api_endpoint = ctx.obj["API_ENDPOINT"]
235
237
  api_key = ctx.obj["API_KEY"]
236
238
  verify_ssl = ctx.obj["VERIFY_SSL"]
237
239
  verbose = ctx.obj["VERBOSE"]
@@ -250,7 +252,7 @@ def create_click_command(
250
252
  # Method generation already happened during inspection phase or initial load
251
253
  api = KarakeepAPI(
252
254
  api_key=api_key,
253
- base_url=base_url,
255
+ api_endpoint=api_endpoint,
254
256
  verify_ssl=verify_ssl,
255
257
  verbose=verbose,
256
258
  disable_response_validation=disable_validation, # Pass flag to constructor
{karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api/datatypes.py RENAMED
@@ -135,6 +135,7 @@ class ListModel(BaseModel):
135
135
  parentId: Optional[str]
136
136
  type: Optional[Literal["manual", "smart"]] = "manual"
137
137
  query: Optional[str] = None
138
+ public: bool
138
139
 
139
140
 
140
141
  class PaginatedHighlights(BaseModel):
{karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api/karakeep_api.py RENAMED
@@ -77,7 +77,7 @@ class KarakeepAPI:
77
77
 
78
78
  Attributes:
79
79
  api_key (str): The API key used for authentication.
80
- api_base_url (str): The base URL of the Karakeep API instance.
80
+ api_endpoint (str): The endpoint of the Karakeep API instance, including /api/v1 (e.g., https://instance.com/api/v1/).
81
81
  openapi_spec (dict): The parsed content of the OpenAPI specification file.
82
82
  verify_ssl (bool): Whether SSL verification is enabled.
83
83
  verbose (bool): Whether verbose logging is enabled.
@@ -85,12 +85,12 @@ class KarakeepAPI:
85
85
  """
86
86
 
87
87
  # Version reflects the client library version, updated by bumpver
88
- VERSION: str = "1.0.0"
88
+ VERSION: str = "1.1.0"
89
89
 
90
90
  def __init__(
91
91
  self,
92
92
  api_key: Optional[str] = None,
93
- base_url: Optional[str] = None,
93
+ api_endpoint: Optional[str] = None,
94
94
  openapi_spec_path: Optional[str] = None, # Allow None, default handled below
95
95
  verify_ssl: bool = True,
96
96
  verbose: bool = False,
@@ -105,8 +105,9 @@ class KarakeepAPI:
105
105
  Args:
106
106
  api_key: Karakeep API key (Bearer token).
107
107
  Defaults to KARAKEEP_PYTHON_API_KEY environment variable if not provided.
108
- base_url: Override the base URL for the API. Must be provided either as an argument
109
- or via the KARAKEEP_PYTHON_API_BASE_URL environment variable.
108
+ api_endpoint: Override the base URL for the API. Must be provided either as an argument
109
+ or via the KARAKEEP_PYTHON_API_ENDPOINT environment variable.
110
+ Example: 'https://karakeep.domain.com/api/v1/'
110
111
  openapi_spec_path: Path to the OpenAPI JSON specification file.
111
112
  Defaults to 'openapi_reference.json' alongside the package code if not provided.
112
113
  The loaded spec is available via the `openapi_spec` attribute.
@@ -131,46 +132,46 @@ class KarakeepAPI:
131
132
  logger.debug("API Key loaded successfully.")
132
133
 
133
134
  # --- Base URL Validation ---
134
- env_base_url = os.environ.get("KARAKEEP_PYTHON_API_BASE_URL")
135
+ env_endpoint = os.environ.get("KARAKEEP_PYTHON_API_ENDPOINT")
135
136
  logger.debug(
136
- f"Checked KARAKEEP_PYTHON_API_BASE_URL environment variable, found: '{env_base_url}'"
137
+ f"Checked KARAKEEP_PYTHON_API_ENDPOINT environment variable, found: '{env_endpoint}'"
137
138
  )
138
- logger.debug(f"Base URL provided as argument: '{base_url}'")
139
+ logger.debug(f"Base URL provided as argument: '{api_endpoint}'")
139
140
 
140
- if base_url:
141
- self.api_base_url = base_url
142
- logger.info(f"Using provided base URL: {self.api_base_url}")
143
- elif env_base_url:
144
- self.api_base_url = env_base_url
141
+ if api_endpoint:
142
+ self.api_endpoint = api_endpoint
143
+ logger.info(f"Using provided base URL: {self.api_endpoint}")
144
+ elif env_endpoint:
145
+ self.api_endpoint = env_endpoint
145
146
  logger.info(
146
- f"Using base URL from KARAKEEP_PYTHON_API_BASE_URL: {self.api_base_url}"
147
+ f"Using base URL from KARAKEEP_PYTHON_API_ENDPOINT: {self.api_endpoint}"
147
148
  )
148
149
  else:
149
- # No base_url from arg or env var - raise error as per requirement
150
+ # No api_endpoint from arg or env var - raise error as per requirement
150
151
  raise ValueError(
151
- "API base URL is required. Provide 'base_url' argument or set KARAKEEP_PYTHON_API_BASE_URL environment variable."
152
+ "API base URL is required. Provide 'api_endpoint' argument or set KARAKEEP_PYTHON_API_ENDPOINT environment variable."
152
153
  )
153
154
 
154
- # Ensure base URL ends with /v1/
155
- resolved_url = self.api_base_url # Use a temporary variable for checks
156
- if resolved_url.endswith("/v1"):
157
- # Ends with /v1, needs a slash
158
- self.api_base_url = resolved_url + "/"
155
+ # Ensure base URL ends with /api/v1/
156
+ resolved_url = self.api_endpoint # Use a temporary variable for checks
157
+ if resolved_url.endswith("/api/v1"):
158
+ # Ends with /api/v1, needs a slash
159
+ self.api_endpoint = resolved_url + "/"
159
160
  logger.info(
160
- f"Appended trailing slash to base URL ending in /v1: {self.api_base_url}"
161
+ f"Appended trailing slash to base URL ending in /api/v1: {self.api_endpoint}"
161
162
  )
162
- elif resolved_url.endswith("/v1/"):
163
+ elif resolved_url.endswith("/api/v1/"):
163
164
  # Already ends correctly, do nothing
164
- logger.debug(f"Base URL already ends with /v1/: {self.api_base_url}")
165
+ logger.debug(f"Base URL already ends with /api/v1/: {self.api_endpoint}")
165
166
  else:
166
- # Doesn't end with /v1 or /v1/, append /v1/
167
- # First, remove any existing trailing slash to avoid //v1/
167
+ # Doesn't end with /api/v1 or /api/v1/, append /api/v1/
168
+ # First, remove any existing trailing slash to avoid //api/v1/
168
169
  if resolved_url.endswith("/"):
169
170
  resolved_url = resolved_url[:-1]
170
- self.api_base_url = resolved_url + "/v1/"
171
- logger.info(f"Appended /v1/ to base URL: {self.api_base_url}")
171
+ self.api_endpoint = resolved_url + "/api/v1/"
172
+ logger.info(f"Appended /api/v1/ to base URL: {self.api_endpoint}")
172
173
 
173
- logger.debug(f"Final API Base URL after /v1/ check: {self.api_base_url}")
174
+ logger.debug(f"Final API Base URL after /api/v1/ check: {self.api_endpoint}")
174
175
 
175
176
  # --- Load and Parse OpenAPI Spec ---
176
177
  if openapi_spec_path is None:
@@ -257,7 +258,7 @@ class KarakeepAPI:
257
258
  # self.verbose is still used for conditional logging within the class methods.
258
259
 
259
260
  logger.debug("KarakeepAPI client initialized.")
260
- logger.debug(f" Base URL: {self.api_base_url}")
261
+ logger.debug(f" Base URL: {self.api_endpoint}")
261
262
  logger.debug(f" Verify SSL: {self.verify_ssl}")
262
263
  logger.debug(f" Verbose: {self.verbose}")
263
264
  logger.debug(
@@ -319,9 +320,9 @@ class KarakeepAPI:
319
320
  AuthenticationError: If authentication fails (401).
320
321
  APIError: For other HTTP errors or request issues.
321
322
  """
322
- # Ensure endpoint doesn't start with / if base_url ends with /
323
+ # Ensure endpoint doesn't start with / if endpoint ends with /
323
324
  safe_endpoint = endpoint.lstrip("/")
324
- url = urljoin(self.api_base_url, safe_endpoint)
325
+ url = urljoin(self.api_endpoint, safe_endpoint)
325
326
 
326
327
  # Default headers
327
328
  headers = {
@@ -1306,6 +1307,7 @@ class KarakeepAPI:
1306
1307
  parent_id: Optional[str] = None,
1307
1308
  list_type: Optional[Literal["manual", "smart"]] = "manual",
1308
1309
  query: Optional[str] = None,
1310
+ public: bool = False,
1309
1311
  ) -> Union[datatypes.ListModel, Dict[str, Any], List[Any]]:
1310
1312
  """
1311
1313
  Create a new list (manual or smart). Corresponds to POST /lists.
@@ -1317,6 +1319,7 @@ class KarakeepAPI:
1317
1319
  parent_id: Optional parent list ID for nested lists.
1318
1320
  list_type: The type of list ('manual' or 'smart'). Default is 'manual'.
1319
1321
  query: Optional query string for smart lists (required if list_type is 'smart').
1322
+ public: Whether the list is public (default: False).
1320
1323
 
1321
1324
  Returns:
1322
1325
  datatypes.ListModel: The created list object.
@@ -1336,6 +1339,7 @@ class KarakeepAPI:
1336
1339
  "name": name,
1337
1340
  "icon": icon,
1338
1341
  "type": list_type,
1342
+ "public": public,
1339
1343
  }
1340
1344
 
1341
1345
  # Add optional fields if provided
@@ -1410,10 +1414,11 @@ class KarakeepAPI:
1410
1414
  icon: Optional[str] = None,
1411
1415
  parent_id: Optional[str] = None,
1412
1416
  query: Optional[str] = None,
1417
+ public: Optional[bool] = None,
1413
1418
  ) -> Union[datatypes.ListModel, Dict[str, Any], List[Any]]:
1414
1419
  """
1415
1420
  Update a list by its ID. Corresponds to PATCH /lists/{listId}.
1416
- Allows updating various list fields including name, description, icon, parent relationship, and query.
1421
+ Allows updating various list fields including name, description, icon, parent relationship, query, and public status.
1417
1422
 
1418
1423
  Args:
1419
1424
  list_id: The ID (string) of the list to update.
@@ -1422,6 +1427,7 @@ class KarakeepAPI:
1422
1427
  icon: Optional new icon for the list.
1423
1428
  parent_id: Optional new parent list ID (can be None to remove parent relationship).
1424
1429
  query: Optional new query string for smart lists (minimum 1 character).
1430
+ public: Optional new public status for the list.
1425
1431
 
1426
1432
  Returns:
1427
1433
  datatypes.ListModel: The updated list object.
@@ -1444,6 +1450,8 @@ class KarakeepAPI:
1444
1450
  update_data["parentId"] = parent_id
1445
1451
  if query is not None:
1446
1452
  update_data["query"] = query
1453
+ if public is not None:
1454
+ update_data["public"] = public
1447
1455
 
1448
1456
  # Ensure at least one field is being updated
1449
1457
  if not update_data:
{karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/karakeep_python_api/openapi_reference.json RENAMED
@@ -426,13 +426,17 @@
426
426
  "query": {
427
427
  "type": "string",
428
428
  "nullable": true
429
+ },
430
+ "public": {
431
+ "type": "boolean"
429
432
  }
430
433
  },
431
434
  "required": [
432
435
  "id",
433
436
  "name",
434
437
  "icon",
435
- "parentId"
438
+ "parentId",
439
+ "public"
436
440
  ]
437
441
  },
438
442
  "Tag": {
@@ -1982,6 +1986,9 @@
1982
1986
  "query": {
1983
1987
  "type": "string",
1984
1988
  "minLength": 1
1989
+ },
1990
+ "public": {
1991
+ "type": "boolean"
1985
1992
  }
1986
1993
  }
1987
1994
  }
{karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0/karakeep_python_api.egg-info}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: karakeep_python_api
3
- Version: 1.0.0
3
+ Version: 1.1.0
4
4
  Summary: Community python client for the Karakeep API.
5
5
  Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
6
6
  License: GPLv3
@@ -137,7 +137,7 @@ This package can be used as a Python library or as a command-line interface (CLI
137
137
 
138
138
  The client can be configured using the following environment variables:
139
139
 
140
- * `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/`).
140
+ * `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/`).
141
141
  * `KARAKEEP_PYTHON_API_KEY`: **Required**. Your Karakeep API key (Bearer token).
142
142
  * `KARAKEEP_PYTHON_API_VERIFY_SSL`: Set to `false` to disable SSL certificate verification (default: `true`).
143
143
  * `KARAKEEP_PYTHON_API_VERBOSE`: Set to `true` to enable verbose debug logging for the client and CLI (default: `false`).
@@ -146,7 +146,7 @@ The client can be configured using the following environment variables:
146
146
 
147
147
  ### Command Line Interface (CLI)
148
148
 
149
- 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.
149
+ 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.
150
150
 
151
151
  **Basic Structure:**
152
152
 
@@ -171,8 +171,8 @@ python -m karakeep_python_api get-all-bookmarks --help
171
171
  python -m karakeep_python_api get-all-tags
172
172
 
173
173
  # Get the first page of bookmarks with a limit, overriding env vars if needed
174
- # Note: Ensure the base URL includes the /api/v1/ path
175
- python -m karakeep_python_api --base-url https://my.karakeep.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
174
+ # Note: The /api/v1/ path will be automatically appended if not present
175
+ python -m karakeep_python_api --base-url https://karakeep.domain.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
176
176
 
177
177
  # Get all lists and pipe the JSON output to jq to extract the first list
178
178
  python -m karakeep_python_api get-all-lists | jq '.[0]'
@@ -196,14 +196,14 @@ import os
196
196
  from karakeep_python_api import KarakeepAPI, APIError, AuthenticationError, datatypes
197
197
 
198
198
  # Ensure required environment variables are set
199
- # Example: os.environ["KARAKEEP_PYTHON_API_BASE_URL"] = "https://your-karakeep.example.com/api/v1/"
199
+ # Example: os.environ["KARAKEEP_PYTHON_API_ENDPOINT"] = "https://karakeep.domain.com/api/v1/"
200
200
  # Example: os.environ["KARAKEEP_PYTHON_API_KEY"] = "your_secret_api_key"
201
201
 
202
202
  try:
203
203
  # Initialize the client (reads from env vars by default)
204
204
  client = KarakeepAPI(
205
205
  # Optionally override env vars:
206
- # base_url="https://another.karakeep.com",
206
+ # api_endpoint="https://karakeep.domain.com/api/v1/",
207
207
  # api_key="another_key",
208
208
  # verbose=True,
209
209
  # disable_response_validation=False
@@ -233,7 +233,7 @@ except AuthenticationError as e:
233
233
  except APIError as e:
234
234
  print(f"An API error occurred: {e}")
235
235
  except ValueError as e:
236
- # Handles missing API key/base URL during initialization
236
+ # Handles missing API key/endpoint during initialization
237
237
  print(f"Configuration error: {e}")
238
238
  except Exception as e:
239
239
  print(f"An unexpected error occurred: {e}")
@@ -242,15 +242,18 @@ except Exception as e:
242
242
 
243
243
  ## Community Scripts
244
244
 
245
- Examples of the API being used can be found in the [`./examples`](./examples) folder. Don't hesitate to submit yours!
245
+ 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.
246
246
 
247
- | Example Script | Description | Documentation |
248
- |----------------|-------------|---------------|
249
- | **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) |
250
- | **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) |
251
- | **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) |
252
- | **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) |
253
- | **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) |
247
+ 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.
248
+
249
+ | Community Script | Description | Documentation |
250
+ |----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
251
+ | **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) |
252
+ | **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) |
253
+ | **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) |
254
+ | **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) |
255
+ | **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) |
256
+ | **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) |
254
257
 
255
258
  ## Development
256
259
 
@@ -261,7 +264,7 @@ Examples of the API being used can be found in the [`./examples`](./examples) fo
261
264
  ```bash
262
265
  uv pip install -e ".[dev]"
263
266
  ```
264
- 4. Set the required environment variables (`KARAKEEP_PYTHON_API_BASE_URL`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
267
+ 4. Set the required environment variables (`KARAKEEP_PYTHON_API_ENDPOINT`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
265
268
  5. Run tests:
266
269
 
267
270
  ```bash
{karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/setup.py RENAMED
@@ -7,7 +7,7 @@ with open("README.md", "r") as readme:
7
7
 
8
8
  setup(
9
9
  name="karakeep_python_api",
10
- version="1.0.0",
10
+ version="1.1.0",
11
11
  description="Community python client for the Karakeep API.", # Simplified description
12
12
  long_description=long_description,
13
13
  long_description_content_type="text/markdown",
{karakeep_python_api-1.0.0 → karakeep_python_api-1.1.0}/tests/test_karakeep_api.py RENAMED
@@ -58,7 +58,7 @@ def test_get_all_bookmarks_paginated(karakeep_client: KarakeepAPI):
58
58
  # --- Add CLI call ---
59
59
  try:
60
60
  logger.info("\n Running CLI equivalent: get-all-bookmarks --limit 2")
61
- # Assumes KARAKEEP_PYTHON_API_BASE_URL and KARAKEEP_PYTHON_API_KEY are set in env
61
+ # Assumes KARAKEEP_PYTHON_API_ENDPOINT and KARAKEEP_PYTHON_API_KEY are set in env
62
62
  subprocess.run(
63
63
  "python -m karakeep_python_api get-all-bookmarks --limit 2",
64
64
  shell=True,
@@ -95,7 +95,7 @@ def test_get_all_lists(karakeep_client: KarakeepAPI):
95
95
  # --- Add CLI call ---
96
96
  try:
97
97
  logger.info("\n Running CLI equivalent: get-all-lists")
98
- # Assumes KARAKEEP_PYTHON_API_BASE_URL and KARAKEEP_PYTHON_API_KEY are set in env
98
+ # Assumes KARAKEEP_PYTHON_API_ENDPOINT and KARAKEEP_PYTHON_API_KEY are set in env
99
99
  subprocess.run(
100
100
  "python -m karakeep_python_api get-all-lists",
101
101
  shell=True,
@@ -132,7 +132,7 @@ def test_get_all_tags(karakeep_client: KarakeepAPI):
132
132
  # --- Add CLI call ---
133
133
  try:
134
134
  logger.info("\n Running CLI equivalent: get-all-tags")
135
- # Assumes KARAKEEP_PYTHON_API_BASE_URL and KARAKEEP_PYTHON_API_KEY are set in env
135
+ # Assumes KARAKEEP_PYTHON_API_ENDPOINT and KARAKEEP_PYTHON_API_KEY are set in env
136
136
  subprocess.run(
137
137
  "python -m karakeep_python_api get-all-tags",
138
138
  shell=True,
@@ -195,7 +195,7 @@ def test_get_all_highlights_paginated(karakeep_client: KarakeepAPI):
195
195
  # --- Add CLI call ---
196
196
  try:
197
197
  logger.info("\n Running CLI equivalent: get-all-highlights --limit 3")
198
- # Assumes KARAKEEP_PYTHON_API_BASE_URL and KARAKEEP_PYTHON_API_KEY are set in env
198
+ # Assumes KARAKEEP_PYTHON_API_ENDPOINT and KARAKEEP_PYTHON_API_KEY are set in env
199
199
  subprocess.run(
200
200
  "python -m karakeep_python_api get-all-highlights --limit 3",
201
201
  shell=True,
@@ -784,7 +784,7 @@ def test_get_current_user_stats(karakeep_client: KarakeepAPI):
784
784
  # --- Add CLI call ---
785
785
  try:
786
786
  logger.info("\n Running CLI equivalent: get-current-user-stats")
787
- # Assumes KARAKEEP_PYTHON_API_BASE_URL and KARAKEEP_PYTHON_API_KEY are set in env
787
+ # Assumes KARAKEEP_PYTHON_API_ENDPOINT and KARAKEEP_PYTHON_API_KEY are set in env
788
788
  subprocess.run(
789
789
  "python -m karakeep_python_api get-current-user-stats",
790
790
  shell=True,