karakeep-python-api 1.8.0__py3-none-any.whl → 1.9.1__py3-none-any.whl
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/__init__.py +7 -1
- karakeep_python_api/__main__.py +21 -8
- karakeep_python_api/datatypes.py +53 -6
- karakeep_python_api/karakeep_api.py +356 -79
- karakeep_python_api/openapi_reference.json +379 -8
- {karakeep_python_api-1.8.0.dist-info → karakeep_python_api-1.9.1.dist-info}/METADATA +7 -2
- karakeep_python_api-1.9.1.dist-info/RECORD +11 -0
- {karakeep_python_api-1.8.0.dist-info → karakeep_python_api-1.9.1.dist-info}/WHEEL +1 -1
- karakeep_python_api-1.8.0.dist-info/RECORD +0 -11
- {karakeep_python_api-1.8.0.dist-info → karakeep_python_api-1.9.1.dist-info}/entry_points.txt +0 -0
- {karakeep_python_api-1.8.0.dist-info → karakeep_python_api-1.9.1.dist-info}/licenses/LICENSE +0 -0
- {karakeep_python_api-1.8.0.dist-info → karakeep_python_api-1.9.1.dist-info}/top_level.txt +0 -0
karakeep_python_api/__init__.py
CHANGED
|
@@ -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
|
]
|
karakeep_python_api/__main__.py
CHANGED
|
@@ -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:
|
karakeep_python_api/datatypes.py
CHANGED
|
@@ -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
|
|