karakeep-python-api 1.8.0__tar.gz → 1.9.1__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.
- {karakeep_python_api-1.8.0/karakeep_python_api.egg-info → karakeep_python_api-1.9.1}/PKG-INFO +7 -2
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/README.md +6 -1
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api/__init__.py +7 -1
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api/__main__.py +21 -8
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api/datatypes.py +53 -6
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api/karakeep_api.py +356 -79
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api/openapi_reference.json +379 -8
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1/karakeep_python_api.egg-info}/PKG-INFO +7 -2
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/setup.py +1 -1
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/tests/test_karakeep_api.py +453 -0
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/LICENSE +0 -0
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/MANIFEST.in +0 -0
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api.egg-info/SOURCES.txt +0 -0
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api.egg-info/dependency_links.txt +0 -0
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api.egg-info/entry_points.txt +0 -0
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api.egg-info/requires.txt +0 -0
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api.egg-info/top_level.txt +0 -0
- {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/setup.cfg +0 -0
{karakeep_python_api-1.8.0/karakeep_python_api.egg-info → karakeep_python_api-1.9.1}/PKG-INFO
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: karakeep_python_api
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.9.1
|
|
4
4
|
Summary: Community python client for the Karakeep API.
|
|
5
5
|
Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
|
|
6
6
|
Keywords: rss,karakeep,hoarder,data-hoarding,python,api,feeds,openapi
|
|
@@ -82,6 +82,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
|
|
|
82
82
|
| `get_a_single_bookmark` | ✅ | ❌ | |
|
|
83
83
|
| `delete_a_bookmark` | ✅ | ❌ | |
|
|
84
84
|
| `update_a_bookmark` | ✅ | ✅ | Tested for title updates. |
|
|
85
|
+
| `get_bookmark_readable_content` | ✅ | ❌ | Chunk merging tested offline; live test reads a text bookmark. |
|
|
85
86
|
| `summarize_a_bookmark` | ❌ | ❌ | |
|
|
86
87
|
| `attach_tags_to_a_bookmark` | ✅ | ❌ | |
|
|
87
88
|
| `detach_tags_from_a_bookmark` | ✅ | ❌ | |
|
|
@@ -110,6 +111,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
|
|
|
110
111
|
| `update_a_highlight` | ❌ | ❌ | |
|
|
111
112
|
| `upload_a_new_asset` | ✅ | ❌ | Tested in PDF asset lifecycle test. |
|
|
112
113
|
| `get_a_single_asset` | ✅ | ❌ | Tested in PDF asset lifecycle test. |
|
|
114
|
+
| `get_asset_signed_url` | ✅ | ❌ | Tested in PDF asset lifecycle test (downloads without an API key). |
|
|
113
115
|
| `get_current_user_info` | ✅ | ❌ | Pytest: Tested indirectly during client init. CLI not directly tested. |
|
|
114
116
|
| `get_current_user_stats` | ✅ | ✅ | |
|
|
115
117
|
| `update_user` | ❌ | ❌ | |
|
|
@@ -118,6 +120,9 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
|
|
|
118
120
|
| `get_a_single_backup` | ✅ | ❌ | Tested in backup lifecycle test. |
|
|
119
121
|
| `delete_a_backup` | ✅ | ❌ | Tested in backup lifecycle test. |
|
|
120
122
|
| `download_a_backup` | ✅ | ❌ | Tested in backup lifecycle test. |
|
|
123
|
+
| `admin_trigger_recrawl` | ❌ | ❌ | Request body construction tested offline only. |
|
|
124
|
+
| `admin_trigger_reindex` | ❌ | ❌ | Request body construction tested offline only. |
|
|
125
|
+
| `admin_trigger_inference` | ❌ | ❌ | Request body construction tested offline only. |
|
|
121
126
|
|
|
122
127
|
## Installation
|
|
123
128
|
|
|
@@ -281,4 +286,4 @@ They can be found in the [./community_scripts](https://github.com/thiswillbeyour
|
|
|
281
286
|
|
|
282
287
|
---
|
|
283
288
|
|
|
284
|
-
*This README was generated with assistance from [aider.chat](https://aider.chat).*
|
|
289
|
+
*This README was generated with assistance from [aider.chat](https://aider.chat), and later kept up to date with [Claude Code](https://claude.com/claude-code).*
|
|
@@ -50,6 +50,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
|
|
|
50
50
|
| `get_a_single_bookmark` | ✅ | ❌ | |
|
|
51
51
|
| `delete_a_bookmark` | ✅ | ❌ | |
|
|
52
52
|
| `update_a_bookmark` | ✅ | ✅ | Tested for title updates. |
|
|
53
|
+
| `get_bookmark_readable_content` | ✅ | ❌ | Chunk merging tested offline; live test reads a text bookmark. |
|
|
53
54
|
| `summarize_a_bookmark` | ❌ | ❌ | |
|
|
54
55
|
| `attach_tags_to_a_bookmark` | ✅ | ❌ | |
|
|
55
56
|
| `detach_tags_from_a_bookmark` | ✅ | ❌ | |
|
|
@@ -78,6 +79,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
|
|
|
78
79
|
| `update_a_highlight` | ❌ | ❌ | |
|
|
79
80
|
| `upload_a_new_asset` | ✅ | ❌ | Tested in PDF asset lifecycle test. |
|
|
80
81
|
| `get_a_single_asset` | ✅ | ❌ | Tested in PDF asset lifecycle test. |
|
|
82
|
+
| `get_asset_signed_url` | ✅ | ❌ | Tested in PDF asset lifecycle test (downloads without an API key). |
|
|
81
83
|
| `get_current_user_info` | ✅ | ❌ | Pytest: Tested indirectly during client init. CLI not directly tested. |
|
|
82
84
|
| `get_current_user_stats` | ✅ | ✅ | |
|
|
83
85
|
| `update_user` | ❌ | ❌ | |
|
|
@@ -86,6 +88,9 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
|
|
|
86
88
|
| `get_a_single_backup` | ✅ | ❌ | Tested in backup lifecycle test. |
|
|
87
89
|
| `delete_a_backup` | ✅ | ❌ | Tested in backup lifecycle test. |
|
|
88
90
|
| `download_a_backup` | ✅ | ❌ | Tested in backup lifecycle test. |
|
|
91
|
+
| `admin_trigger_recrawl` | ❌ | ❌ | Request body construction tested offline only. |
|
|
92
|
+
| `admin_trigger_reindex` | ❌ | ❌ | Request body construction tested offline only. |
|
|
93
|
+
| `admin_trigger_inference` | ❌ | ❌ | Request body construction tested offline only. |
|
|
89
94
|
|
|
90
95
|
## Installation
|
|
91
96
|
|
|
@@ -249,4 +254,4 @@ They can be found in the [./community_scripts](https://github.com/thiswillbeyour
|
|
|
249
254
|
|
|
250
255
|
---
|
|
251
256
|
|
|
252
|
-
*This README was generated with assistance from [aider.chat](https://aider.chat).*
|
|
257
|
+
*This README was generated with assistance from [aider.chat](https://aider.chat), and later kept up to date with [Claude Code](https://claude.com/claude-code).*
|
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
# Import API class and errors directly from the module
|
|
2
|
-
from .karakeep_api import
|
|
2
|
+
from .karakeep_api import (
|
|
3
|
+
KarakeepAPI,
|
|
4
|
+
APIError,
|
|
5
|
+
AuthenticationError,
|
|
6
|
+
exclude_library_records,
|
|
7
|
+
)
|
|
3
8
|
|
|
4
9
|
# Import the datatypes module so users can do `from karakeep_python_api.datatypes import ...`
|
|
5
10
|
from . import datatypes
|
|
@@ -12,6 +17,7 @@ __all__ = [
|
|
|
12
17
|
"KarakeepAPI",
|
|
13
18
|
"APIError",
|
|
14
19
|
"AuthenticationError",
|
|
20
|
+
"exclude_library_records",
|
|
15
21
|
"datatypes", # Expose the datatypes module
|
|
16
22
|
"__version__",
|
|
17
23
|
]
|
|
@@ -9,8 +9,6 @@ import click
|
|
|
9
9
|
import traceback # Moved import to top
|
|
10
10
|
from typing import (
|
|
11
11
|
Any,
|
|
12
|
-
List,
|
|
13
|
-
Dict,
|
|
14
12
|
Optional,
|
|
15
13
|
Callable,
|
|
16
14
|
Union,
|
|
@@ -269,11 +267,10 @@ def create_click_command(
|
|
|
269
267
|
param_annotation = param_sig.annotation
|
|
270
268
|
origin = getattr(param_annotation, "__origin__", None)
|
|
271
269
|
|
|
272
|
-
# Check if the annotation is dict/list or
|
|
270
|
+
# Check if the annotation is dict/list or a parametrized list[...]/dict[...]
|
|
273
271
|
# and if the received value is a string (needs parsing)
|
|
274
272
|
if (
|
|
275
|
-
param_annotation in (dict, list)
|
|
276
|
-
or origin in (dict, list, Dict, List)
|
|
273
|
+
param_annotation in (dict, list) or origin in (dict, list)
|
|
277
274
|
) and isinstance(param_value, str):
|
|
278
275
|
try:
|
|
279
276
|
# Attempt to parse the JSON string
|
|
@@ -538,7 +535,23 @@ def create_click_command(
|
|
|
538
535
|
ctx.exit(1)
|
|
539
536
|
|
|
540
537
|
# Serialize and print the result
|
|
541
|
-
if result
|
|
538
|
+
if isinstance(result, (bytes, bytearray)):
|
|
539
|
+
# Binary payloads (e.g. download_a_backup, get_a_single_asset)
|
|
540
|
+
# cannot be JSON encoded: write them raw to stdout so the
|
|
541
|
+
# output can be redirected straight into a file.
|
|
542
|
+
logger.debug(f"Writing {len(result)} raw bytes to stdout.")
|
|
543
|
+
stdout_buffer = getattr(sys.stdout, "buffer", None)
|
|
544
|
+
if stdout_buffer is not None:
|
|
545
|
+
stdout_buffer.write(result)
|
|
546
|
+
stdout_buffer.flush()
|
|
547
|
+
else:
|
|
548
|
+
# Some test/capture harnesses replace sys.stdout with a
|
|
549
|
+
# text-only stream that has no .buffer attribute.
|
|
550
|
+
sys.stdout.write(
|
|
551
|
+
bytes(result).decode("utf-8", errors="surrogateescape")
|
|
552
|
+
)
|
|
553
|
+
sys.stdout.flush()
|
|
554
|
+
elif result is not None:
|
|
542
555
|
output_data = serialize_output(result)
|
|
543
556
|
# Use ensure_ascii_output flag to control JSON encoding
|
|
544
557
|
click.echo(
|
|
@@ -664,8 +677,8 @@ def create_click_command(
|
|
|
664
677
|
is_required_in_sig = False # Optional means not required
|
|
665
678
|
default_value = None # Default for Optional is None
|
|
666
679
|
|
|
667
|
-
# Handle
|
|
668
|
-
elif origin in (list, dict
|
|
680
|
+
# Handle list[T] or dict[K, V] - expect JSON string
|
|
681
|
+
elif origin in (list, dict) or annotation in (list, dict):
|
|
669
682
|
click_type = click.STRING # Expect JSON string
|
|
670
683
|
# Handle Literal[...] for choices
|
|
671
684
|
elif origin is Literal:
|
|
@@ -5,7 +5,7 @@ The datatype file was originally generated by datamodel-codegen, then refactored
|
|
|
5
5
|
from __future__ import annotations
|
|
6
6
|
|
|
7
7
|
from enum import Enum
|
|
8
|
-
from typing import
|
|
8
|
+
from typing import Optional, Union, Literal
|
|
9
9
|
|
|
10
10
|
from pydantic import BaseModel, Field, RootModel
|
|
11
11
|
|
|
@@ -53,6 +53,15 @@ class ContentTypeLink(BaseModel):
|
|
|
53
53
|
favicon: Optional[str] = None
|
|
54
54
|
htmlContent: Optional[str] = None
|
|
55
55
|
contentAssetId: Optional[str] = None
|
|
56
|
+
# Reader-view triage produced by the crawler: readerViewStatus says whether a
|
|
57
|
+
# distraction-free rendering could be extracted, readerViewScore (0-100) how
|
|
58
|
+
# confident that extraction is, and preferredPreview which of the available
|
|
59
|
+
# renderings the UI should show by default.
|
|
60
|
+
readerViewStatus: Optional[
|
|
61
|
+
Literal["readable", "not_readable", "uncertain", "unavailable"]
|
|
62
|
+
] = None
|
|
63
|
+
readerViewScore: Optional[int] = None
|
|
64
|
+
preferredPreview: Optional[Literal["reader_view", "screenshot", "overview"]] = None
|
|
56
65
|
crawledAt: Optional[str] = None
|
|
57
66
|
crawlStatus: Optional[Literal["success", "failure", "pending"]] = None
|
|
58
67
|
author: Optional[str] = None
|
|
@@ -112,8 +121,20 @@ class UploadedAsset(BaseModel):
|
|
|
112
121
|
Asset = UploadedAsset
|
|
113
122
|
|
|
114
123
|
|
|
124
|
+
class SignedAssetUrl(BaseModel):
|
|
125
|
+
assetId: str
|
|
126
|
+
# Temporary download URL that carries its own signature, so it works without
|
|
127
|
+
# the Authorization header and can be handed to a browser or media player.
|
|
128
|
+
signedUrl: str
|
|
129
|
+
expiresAt: str
|
|
130
|
+
|
|
131
|
+
|
|
115
132
|
class Bookmark(BaseModel):
|
|
116
133
|
id: str
|
|
134
|
+
# firstCreatedAt records the original creation time when a bookmark is
|
|
135
|
+
# recreated/re-imported, so it can predate createdAt. Optional in the spec
|
|
136
|
+
# and absent on Karakeep servers older than the one that introduced it.
|
|
137
|
+
firstCreatedAt: Optional[str] = None
|
|
117
138
|
createdAt: str
|
|
118
139
|
modifiedAt: Optional[str]
|
|
119
140
|
title: Optional[str] = None
|
|
@@ -121,6 +142,10 @@ class Bookmark(BaseModel):
|
|
|
121
142
|
favourited: bool
|
|
122
143
|
taggingStatus: Optional[Literal["success", "failure", "pending"]] = None
|
|
123
144
|
summarizationStatus: Optional[Literal["success", "failure", "pending"]] = None
|
|
145
|
+
# Status of the vector-embedding job used by semantic/hybrid search. The
|
|
146
|
+
# spec marks it required-but-nullable, so no default is given here: a
|
|
147
|
+
# missing key is a genuine mismatch with the documented server response.
|
|
148
|
+
embeddingStatus: Optional[Literal["success", "failure", "pending"]]
|
|
124
149
|
note: Optional[str] = None
|
|
125
150
|
summary: Optional[str] = None
|
|
126
151
|
source: Optional[
|
|
@@ -129,15 +154,37 @@ class Bookmark(BaseModel):
|
|
|
129
154
|
]
|
|
130
155
|
] = None
|
|
131
156
|
userId: str
|
|
132
|
-
tags:
|
|
157
|
+
tags: list[TagShort]
|
|
133
158
|
content: Union[
|
|
134
159
|
ContentTypeLink, ContentTypeText, ContentTypeAsset, ContentTypeUnknown
|
|
135
160
|
]
|
|
136
|
-
assets:
|
|
161
|
+
assets: list[BookmarkAsset]
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
class ReadableContentRange(BaseModel):
|
|
165
|
+
# Offsets are in Unicode characters over the *rendered* content, not bytes:
|
|
166
|
+
# start is inclusive, end is exclusive, and total is the full rendered length.
|
|
167
|
+
start: int
|
|
168
|
+
end: int
|
|
169
|
+
total: int
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
class BookmarkReadableContent(BaseModel):
|
|
173
|
+
bookmarkId: str
|
|
174
|
+
bookmarkType: Literal["link", "text", "asset"]
|
|
175
|
+
format: Literal["markdown", "text"]
|
|
176
|
+
content: str
|
|
177
|
+
# Hash of the rendered content the cursor was issued against. The server
|
|
178
|
+
# answers 409 if the bookmark changed between two chunks, so this value must
|
|
179
|
+
# not be mixed across a paginated read.
|
|
180
|
+
contentVersion: str
|
|
181
|
+
range: ReadableContentRange
|
|
182
|
+
nextCursor: Optional[str]
|
|
183
|
+
truncated: bool
|
|
137
184
|
|
|
138
185
|
|
|
139
186
|
class PaginatedBookmarks(BaseModel):
|
|
140
|
-
bookmarks:
|
|
187
|
+
bookmarks: list[Bookmark]
|
|
141
188
|
nextCursor: Optional[str] = ""
|
|
142
189
|
|
|
143
190
|
|
|
@@ -171,12 +218,12 @@ class Highlight(BaseModel):
|
|
|
171
218
|
|
|
172
219
|
|
|
173
220
|
class PaginatedHighlights(BaseModel):
|
|
174
|
-
highlights:
|
|
221
|
+
highlights: list[Highlight]
|
|
175
222
|
nextCursor: Optional[str] = ""
|
|
176
223
|
|
|
177
224
|
|
|
178
225
|
class PaginatedTags(BaseModel):
|
|
179
|
-
tags:
|
|
226
|
+
tags: list[Tag]
|
|
180
227
|
nextCursor: Optional[str] = ""
|
|
181
228
|
|
|
182
229
|
|