karakeep-python-api 1.9.0__py3-none-any.whl → 1.10.0__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 +4 -7
- karakeep_python_api/datatypes.py +30 -6
- karakeep_python_api/karakeep_api.py +188 -78
- karakeep_python_api/openapi_reference.json +108 -2
- {karakeep_python_api-1.9.0.dist-info → karakeep_python_api-1.10.0.dist-info}/METADATA +2 -2
- karakeep_python_api-1.10.0.dist-info/RECORD +11 -0
- {karakeep_python_api-1.9.0.dist-info → karakeep_python_api-1.10.0.dist-info}/WHEEL +1 -1
- karakeep_python_api-1.9.0.dist-info/RECORD +0 -11
- {karakeep_python_api-1.9.0.dist-info → karakeep_python_api-1.10.0.dist-info}/entry_points.txt +0 -0
- {karakeep_python_api-1.9.0.dist-info → karakeep_python_api-1.10.0.dist-info}/licenses/LICENSE +0 -0
- {karakeep_python_api-1.9.0.dist-info → karakeep_python_api-1.10.0.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
|
|
@@ -680,8 +677,8 @@ def create_click_command(
|
|
|
680
677
|
is_required_in_sig = False # Optional means not required
|
|
681
678
|
default_value = None # Default for Optional is None
|
|
682
679
|
|
|
683
|
-
# Handle
|
|
684
|
-
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):
|
|
685
682
|
click_type = click.STRING # Expect JSON string
|
|
686
683
|
# Handle Literal[...] for choices
|
|
687
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
|
|
|
@@ -107,6 +107,9 @@ class BookmarkAsset(BaseModel):
|
|
|
107
107
|
"unknown",
|
|
108
108
|
]
|
|
109
109
|
fileName: Optional[str] = None
|
|
110
|
+
# Size in bytes of the stored asset. Defaults to None because servers older
|
|
111
|
+
# than the spec revision that introduced it do not send the key at all.
|
|
112
|
+
size: Optional[float] = None
|
|
110
113
|
|
|
111
114
|
|
|
112
115
|
class UploadedAsset(BaseModel):
|
|
@@ -154,11 +157,11 @@ class Bookmark(BaseModel):
|
|
|
154
157
|
]
|
|
155
158
|
] = None
|
|
156
159
|
userId: str
|
|
157
|
-
tags:
|
|
160
|
+
tags: list[TagShort]
|
|
158
161
|
content: Union[
|
|
159
162
|
ContentTypeLink, ContentTypeText, ContentTypeAsset, ContentTypeUnknown
|
|
160
163
|
]
|
|
161
|
-
assets:
|
|
164
|
+
assets: list[BookmarkAsset]
|
|
162
165
|
|
|
163
166
|
|
|
164
167
|
class ReadableContentRange(BaseModel):
|
|
@@ -184,7 +187,7 @@ class BookmarkReadableContent(BaseModel):
|
|
|
184
187
|
|
|
185
188
|
|
|
186
189
|
class PaginatedBookmarks(BaseModel):
|
|
187
|
-
bookmarks:
|
|
190
|
+
bookmarks: list[Bookmark]
|
|
188
191
|
nextCursor: Optional[str] = ""
|
|
189
192
|
|
|
190
193
|
|
|
@@ -211,19 +214,40 @@ class Highlight(BaseModel):
|
|
|
211
214
|
endOffset: float
|
|
212
215
|
color: Optional[Literal["yellow", "red", "green", "blue"]] = "yellow"
|
|
213
216
|
text: Optional[str]
|
|
217
|
+
# prefix/suffix hold the text right before/after the highlighted span. The
|
|
218
|
+
# server uses them as context to re-anchor the highlight if the offsets drift
|
|
219
|
+
# (e.g. after a re-crawl changed the content). The spec marks them required
|
|
220
|
+
# but nullable; they default to None here so responses from older servers,
|
|
221
|
+
# which do not send these keys, still validate.
|
|
222
|
+
prefix: Optional[str] = None
|
|
223
|
+
suffix: Optional[str] = None
|
|
214
224
|
note: Optional[str]
|
|
215
225
|
id: str
|
|
216
226
|
userId: str
|
|
217
227
|
createdAt: str
|
|
218
228
|
|
|
219
229
|
|
|
230
|
+
class HighlightBookmarkInfo(BaseModel):
|
|
231
|
+
title: Optional[str]
|
|
232
|
+
url: Optional[str]
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
class HighlightWithBookmark(Highlight):
|
|
236
|
+
# Returned by GET /highlights only: each highlight embeds a short summary of
|
|
237
|
+
# its bookmark so callers can display it without one extra request per
|
|
238
|
+
# highlight. Subclassing Highlight avoids duplicating its fields and keeps
|
|
239
|
+
# isinstance(h, Highlight) true for existing callers. Defaults to None so
|
|
240
|
+
# older servers that return plain Highlight objects still validate.
|
|
241
|
+
bookmark: Optional[HighlightBookmarkInfo] = None
|
|
242
|
+
|
|
243
|
+
|
|
220
244
|
class PaginatedHighlights(BaseModel):
|
|
221
|
-
highlights:
|
|
245
|
+
highlights: list[HighlightWithBookmark]
|
|
222
246
|
nextCursor: Optional[str] = ""
|
|
223
247
|
|
|
224
248
|
|
|
225
249
|
class PaginatedTags(BaseModel):
|
|
226
|
-
tags:
|
|
250
|
+
tags: list[Tag]
|
|
227
251
|
nextCursor: Optional[str] = ""
|
|
228
252
|
|
|
229
253
|
|
|
@@ -10,7 +10,7 @@ import pathlib
|
|
|
10
10
|
import json # Still needed for spec loading if parse_spec not available, and _call
|
|
11
11
|
import datetime
|
|
12
12
|
import typing # Need full import for get_type_hints resolution with forward refs
|
|
13
|
-
from typing import Optional,
|
|
13
|
+
from typing import Optional, Any, Callable, Tuple, Union, Type, Literal
|
|
14
14
|
from urllib.parse import urljoin, urlparse
|
|
15
15
|
from loguru import logger
|
|
16
16
|
from pydantic import BaseModel # Import BaseModel for type checking and serialization
|
|
@@ -40,6 +40,113 @@ class AuthenticationError(APIError):
|
|
|
40
40
|
super().__init__(message, status_code=401)
|
|
41
41
|
|
|
42
42
|
|
|
43
|
+
# --- Logging ---
|
|
44
|
+
|
|
45
|
+
# Records emitted from inside this package have a "name" starting with this
|
|
46
|
+
# prefix, which is what the handler filters below rely on.
|
|
47
|
+
_PACKAGE_NAME = __name__.split(".")[0]
|
|
48
|
+
|
|
49
|
+
# Id of the stderr handler owned by this package. It is kept at module level
|
|
50
|
+
# so that creating several KarakeepAPI instances replaces the handler instead
|
|
51
|
+
# of stacking one more copy per instance (each copy printed every line again).
|
|
52
|
+
_LOG_HANDLER_ID: Optional[int] = None
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _is_package_record(record: dict[str, Any]) -> bool:
|
|
56
|
+
"""
|
|
57
|
+
Tell whether a loguru record was emitted from this package.
|
|
58
|
+
|
|
59
|
+
Parameters
|
|
60
|
+
----------
|
|
61
|
+
record : dict
|
|
62
|
+
Loguru record.
|
|
63
|
+
|
|
64
|
+
Returns
|
|
65
|
+
-------
|
|
66
|
+
bool
|
|
67
|
+
True for records coming from karakeep_python_api modules.
|
|
68
|
+
"""
|
|
69
|
+
return (record["name"] or "").startswith(_PACKAGE_NAME)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def exclude_library_records(record: dict[str, Any]) -> bool:
|
|
73
|
+
"""
|
|
74
|
+
Loguru filter rejecting the records emitted by this package.
|
|
75
|
+
|
|
76
|
+
Meant for applications that install their own stderr handler: the
|
|
77
|
+
package already prints its records through its own handler, so passing
|
|
78
|
+
``filter=exclude_library_records`` to ``logger.add`` keeps them from being
|
|
79
|
+
printed a second time. File handlers usually do not need it, as the
|
|
80
|
+
package never writes to files.
|
|
81
|
+
|
|
82
|
+
Parameters
|
|
83
|
+
----------
|
|
84
|
+
record : dict
|
|
85
|
+
Loguru record.
|
|
86
|
+
|
|
87
|
+
Returns
|
|
88
|
+
-------
|
|
89
|
+
bool
|
|
90
|
+
True for records that do NOT come from karakeep_python_api.
|
|
91
|
+
"""
|
|
92
|
+
return not _is_package_record(record)
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def _configure_logging(level: str) -> None:
|
|
96
|
+
"""
|
|
97
|
+
Install (or replace) the stderr handler used for this package's logs.
|
|
98
|
+
|
|
99
|
+
Loguru has a single global logger shared by the library and the calling
|
|
100
|
+
application, and every record goes to every handler. The previous
|
|
101
|
+
implementation added an unfiltered stderr handler on top of the existing
|
|
102
|
+
ones, so every line of the application (and of the library) was printed
|
|
103
|
+
twice, and once more per extra KarakeepAPI instance.
|
|
104
|
+
|
|
105
|
+
The design is now:
|
|
106
|
+
- the package handler only accepts records emitted by this package, at
|
|
107
|
+
``level``, so it never duplicates the application's own lines;
|
|
108
|
+
- if loguru's default handler (id 0) is still installed, it is replaced by
|
|
109
|
+
an equivalent one (stderr, DEBUG, default format) that skips this
|
|
110
|
+
package's records, so library lines are printed once, by the package
|
|
111
|
+
handler, while the application keeps exactly the output it had.
|
|
112
|
+
If the application already replaced the default handler with its own
|
|
113
|
+
catch-all handler, the library records will reach both: such
|
|
114
|
+
applications should pass ``filter=exclude_library_records`` to their
|
|
115
|
+
stderr handler.
|
|
116
|
+
|
|
117
|
+
Parameters
|
|
118
|
+
----------
|
|
119
|
+
level : str
|
|
120
|
+
Minimum level of library records to print, e.g. "DEBUG" or "INFO".
|
|
121
|
+
"""
|
|
122
|
+
global _LOG_HANDLER_ID
|
|
123
|
+
if _LOG_HANDLER_ID is not None:
|
|
124
|
+
try:
|
|
125
|
+
logger.remove(_LOG_HANDLER_ID)
|
|
126
|
+
except ValueError:
|
|
127
|
+
# Already removed by the application, nothing to do.
|
|
128
|
+
pass
|
|
129
|
+
try:
|
|
130
|
+
logger.remove(0)
|
|
131
|
+
except ValueError:
|
|
132
|
+
# Default handler already removed by the application (or by a
|
|
133
|
+
# previous call of this function): leave the app's handlers alone.
|
|
134
|
+
pass
|
|
135
|
+
else:
|
|
136
|
+
logger.add(
|
|
137
|
+
sys.stderr,
|
|
138
|
+
level="DEBUG",
|
|
139
|
+
filter=exclude_library_records,
|
|
140
|
+
)
|
|
141
|
+
if level == "DEBUG":
|
|
142
|
+
log_format = "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>"
|
|
143
|
+
_LOG_HANDLER_ID = logger.add(
|
|
144
|
+
sys.stderr, level=level, format=log_format, filter=_is_package_record
|
|
145
|
+
)
|
|
146
|
+
else:
|
|
147
|
+
_LOG_HANDLER_ID = logger.add(sys.stderr, level=level, filter=_is_package_record)
|
|
148
|
+
|
|
149
|
+
|
|
43
150
|
# --- Optional Imports ---
|
|
44
151
|
|
|
45
152
|
# Optional type checking with beartype
|
|
@@ -85,7 +192,7 @@ class KarakeepAPI:
|
|
|
85
192
|
"""
|
|
86
193
|
|
|
87
194
|
# Version reflects the client library version, updated by bumpver
|
|
88
|
-
VERSION: str = "1.
|
|
195
|
+
VERSION: str = "1.10.0"
|
|
89
196
|
|
|
90
197
|
def __init__(
|
|
91
198
|
self,
|
|
@@ -134,17 +241,7 @@ class KarakeepAPI:
|
|
|
134
241
|
|
|
135
242
|
# Configure logger based on verbose setting
|
|
136
243
|
log_level = "DEBUG" if self.verbose else "INFO"
|
|
137
|
-
|
|
138
|
-
if self.verbose:
|
|
139
|
-
logger.add(
|
|
140
|
-
sys.stderr,
|
|
141
|
-
level=log_level,
|
|
142
|
-
format="<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
|
|
143
|
-
)
|
|
144
|
-
logger.debug("Verbose logging enabled with detailed format.")
|
|
145
|
-
else:
|
|
146
|
-
logger.add(sys.stderr, level=log_level) # Default format for INFO
|
|
147
|
-
|
|
244
|
+
_configure_logging(level=log_level)
|
|
148
245
|
logger.debug(verbose_mess)
|
|
149
246
|
logger.debug("Logger configured for level: {}", log_level)
|
|
150
247
|
|
|
@@ -211,7 +308,7 @@ class KarakeepAPI:
|
|
|
211
308
|
else:
|
|
212
309
|
logger.debug(f"Using provided OpenAPI spec path: {openapi_spec_path}")
|
|
213
310
|
|
|
214
|
-
self.openapi_spec: Optional[
|
|
311
|
+
self.openapi_spec: Optional[dict[str, Any]] = None # Initialize attribute
|
|
215
312
|
try:
|
|
216
313
|
with open(openapi_spec_path, "r", encoding="utf-8") as f:
|
|
217
314
|
self.openapi_spec = json.load(f)
|
|
@@ -312,13 +409,13 @@ class KarakeepAPI:
|
|
|
312
409
|
self,
|
|
313
410
|
method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"],
|
|
314
411
|
endpoint: str,
|
|
315
|
-
params: Optional[
|
|
412
|
+
params: Optional[dict[str, Any]] = None,
|
|
316
413
|
data: Optional[
|
|
317
414
|
Union[BaseModel, dict, list, str, bytes]
|
|
318
415
|
] = None, # More specific type hint
|
|
319
|
-
files: Optional[
|
|
320
|
-
extra_headers: Optional[
|
|
321
|
-
) -> Union[
|
|
416
|
+
files: Optional[dict[str, Any]] = None,
|
|
417
|
+
extra_headers: Optional[dict[str, str]] = None,
|
|
418
|
+
) -> Union[dict[str, Any], list[Any], None, bytes]:
|
|
322
419
|
"""
|
|
323
420
|
Internal method to make an HTTP call to the Karakeep API. Handles authentication,
|
|
324
421
|
request formatting, response parsing, and error handling.
|
|
@@ -697,7 +794,7 @@ class KarakeepAPI:
|
|
|
697
794
|
limit: Optional[int] = None, # This is the per-page limit for the API
|
|
698
795
|
cursor: Optional[str] = None,
|
|
699
796
|
include_content: bool = True, # Default from spec
|
|
700
|
-
) -> Union[datatypes.PaginatedBookmarks,
|
|
797
|
+
) -> Union[datatypes.PaginatedBookmarks, dict[str, Any], list[Any]]:
|
|
701
798
|
"""
|
|
702
799
|
Get bookmarks, one page at a time. Corresponds to GET /bookmarks.
|
|
703
800
|
|
|
@@ -783,7 +880,7 @@ class KarakeepAPI:
|
|
|
783
880
|
fileName: Optional[str] = None,
|
|
784
881
|
# size: Optional[int] = None, # Size is not in POST spec
|
|
785
882
|
# content: Optional[str] = None, # Content is not in POST spec
|
|
786
|
-
) -> Union[datatypes.Bookmark,
|
|
883
|
+
) -> Union[datatypes.Bookmark, dict[str, Any], list[Any]]:
|
|
787
884
|
"""
|
|
788
885
|
Create a new bookmark. Corresponds to POST /bookmarks.
|
|
789
886
|
|
|
@@ -825,7 +922,7 @@ class KarakeepAPI:
|
|
|
825
922
|
pydantic.ValidationError: If response validation fails (and is not disabled).
|
|
826
923
|
"""
|
|
827
924
|
# --- Construct the request body ---
|
|
828
|
-
request_body:
|
|
925
|
+
request_body: dict[str, Any] = {"type": type}
|
|
829
926
|
|
|
830
927
|
# Add common optional fields if provided
|
|
831
928
|
if title is not None:
|
|
@@ -896,7 +993,7 @@ class KarakeepAPI:
|
|
|
896
993
|
limit: Optional[int] = None,
|
|
897
994
|
cursor: Optional[str] = None,
|
|
898
995
|
include_content: bool = True, # Default from spec
|
|
899
|
-
) -> Union[datatypes.PaginatedBookmarks,
|
|
996
|
+
) -> Union[datatypes.PaginatedBookmarks, dict[str, Any], list[Any]]:
|
|
900
997
|
"""
|
|
901
998
|
Search bookmarks using full-text, semantic or hybrid ranking.
|
|
902
999
|
Corresponds to GET /bookmarks/search.
|
|
@@ -944,7 +1041,7 @@ class KarakeepAPI:
|
|
|
944
1041
|
def check_url(
|
|
945
1042
|
self,
|
|
946
1043
|
url: str,
|
|
947
|
-
) -> Union[datatypes.CheckUrlResponse,
|
|
1044
|
+
) -> Union[datatypes.CheckUrlResponse, dict[str, Any], list[Any]]:
|
|
948
1045
|
"""
|
|
949
1046
|
Check if a URL is already bookmarked. Corresponds to GET /bookmarks/check-url.
|
|
950
1047
|
Uses substring matching to find candidates, then normalizes URLs (ignoring hash fragments and trailing slashes) for exact comparison.
|
|
@@ -977,7 +1074,7 @@ class KarakeepAPI:
|
|
|
977
1074
|
self,
|
|
978
1075
|
bookmark_id: str,
|
|
979
1076
|
include_content: bool = True, # Default from spec
|
|
980
|
-
) -> Union[datatypes.Bookmark,
|
|
1077
|
+
) -> Union[datatypes.Bookmark, dict[str, Any], list[Any]]:
|
|
981
1078
|
"""
|
|
982
1079
|
Get a single bookmark by its ID. Corresponds to GET /bookmarks/{bookmarkId}.
|
|
983
1080
|
|
|
@@ -1028,8 +1125,8 @@ class KarakeepAPI:
|
|
|
1028
1125
|
def update_a_bookmark(
|
|
1029
1126
|
self,
|
|
1030
1127
|
bookmark_id: str,
|
|
1031
|
-
update_data:
|
|
1032
|
-
) ->
|
|
1128
|
+
update_data: dict[str, Any],
|
|
1129
|
+
) -> dict[str, Any]:
|
|
1033
1130
|
"""
|
|
1034
1131
|
Update a bookmark by its ID. Corresponds to PATCH /bookmarks/{bookmarkId}.
|
|
1035
1132
|
Allows updating various bookmark fields including metadata, content, and status.
|
|
@@ -1069,7 +1166,7 @@ class KarakeepAPI:
|
|
|
1069
1166
|
max_chars: Optional[int] = None,
|
|
1070
1167
|
cursor: Optional[str] = None,
|
|
1071
1168
|
fetch_all: bool = False,
|
|
1072
|
-
) -> Union[datatypes.BookmarkReadableContent,
|
|
1169
|
+
) -> Union[datatypes.BookmarkReadableContent, dict[str, Any], list[Any]]:
|
|
1073
1170
|
"""
|
|
1074
1171
|
Get an agent-readable rendering of a bookmark's content.
|
|
1075
1172
|
Corresponds to GET /bookmarks/{bookmarkId}/content.
|
|
@@ -1157,7 +1254,7 @@ class KarakeepAPI:
|
|
|
1157
1254
|
return datatypes.BookmarkReadableContent.model_validate(response_data)
|
|
1158
1255
|
|
|
1159
1256
|
@optional_typecheck
|
|
1160
|
-
def summarize_a_bookmark(self, bookmark_id: str) ->
|
|
1257
|
+
def summarize_a_bookmark(self, bookmark_id: str) -> dict[str, Any]:
|
|
1161
1258
|
"""
|
|
1162
1259
|
Summarize a bookmark by its ID. Corresponds to POST /bookmarks/{bookmarkId}/summarize.
|
|
1163
1260
|
This triggers the summarization process and returns the updated bookmark record (partially).
|
|
@@ -1183,10 +1280,10 @@ class KarakeepAPI:
|
|
|
1183
1280
|
def attach_tags_to_a_bookmark(
|
|
1184
1281
|
self,
|
|
1185
1282
|
bookmark_id: str,
|
|
1186
|
-
tag_ids: Optional[
|
|
1187
|
-
tag_names: Optional[
|
|
1283
|
+
tag_ids: Optional[list[str]] = None,
|
|
1284
|
+
tag_names: Optional[list[str]] = None,
|
|
1188
1285
|
attached_by: Optional[Literal["ai", "human"]] = "human",
|
|
1189
|
-
) ->
|
|
1286
|
+
) -> dict[str, Any]:
|
|
1190
1287
|
"""
|
|
1191
1288
|
Attach one or more tags to a bookmark. Corresponds to POST /bookmarks/{bookmarkId}/tags.
|
|
1192
1289
|
|
|
@@ -1236,7 +1333,7 @@ class KarakeepAPI:
|
|
|
1236
1333
|
|
|
1237
1334
|
if tag_ids:
|
|
1238
1335
|
for tag_id in tag_ids:
|
|
1239
|
-
tag_entry:
|
|
1336
|
+
tag_entry: dict[str, Any] = {"tagId": tag_id.strip()}
|
|
1240
1337
|
if attached_by is not None:
|
|
1241
1338
|
tag_entry["attachedBy"] = attached_by
|
|
1242
1339
|
tags_list.append(tag_entry)
|
|
@@ -1266,10 +1363,10 @@ class KarakeepAPI:
|
|
|
1266
1363
|
def detach_tags_from_a_bookmark(
|
|
1267
1364
|
self,
|
|
1268
1365
|
bookmark_id: str,
|
|
1269
|
-
tag_ids: Optional[
|
|
1270
|
-
tag_names: Optional[
|
|
1366
|
+
tag_ids: Optional[list[str]] = None,
|
|
1367
|
+
tag_names: Optional[list[str]] = None,
|
|
1271
1368
|
attached_by: Optional[Literal["ai", "human"]] = "human",
|
|
1272
|
-
) ->
|
|
1369
|
+
) -> dict[str, Any]:
|
|
1273
1370
|
"""
|
|
1274
1371
|
Detach one or more tags from a bookmark. Corresponds to DELETE /bookmarks/{bookmarkId}/tags.
|
|
1275
1372
|
|
|
@@ -1319,7 +1416,7 @@ class KarakeepAPI:
|
|
|
1319
1416
|
|
|
1320
1417
|
if tag_ids:
|
|
1321
1418
|
for tag_id in tag_ids:
|
|
1322
|
-
tag_entry:
|
|
1419
|
+
tag_entry: dict[str, Any] = {"tagId": tag_id.strip()}
|
|
1323
1420
|
if attached_by is not None:
|
|
1324
1421
|
tag_entry["attachedBy"] = attached_by
|
|
1325
1422
|
tags_list.append(tag_entry)
|
|
@@ -1348,7 +1445,7 @@ class KarakeepAPI:
|
|
|
1348
1445
|
@optional_typecheck
|
|
1349
1446
|
def get_lists_of_a_bookmark(
|
|
1350
1447
|
self, bookmark_id: str
|
|
1351
|
-
) -> Union[
|
|
1448
|
+
) -> Union[list[datatypes.ListModel], dict[str, Any], list[Any]]:
|
|
1352
1449
|
"""
|
|
1353
1450
|
Get all lists associated with a specific bookmark. Corresponds to GET /bookmarks/{bookmarkId}/lists.
|
|
1354
1451
|
|
|
@@ -1356,7 +1453,7 @@ class KarakeepAPI:
|
|
|
1356
1453
|
bookmark_id: The ID (string) of the bookmark.
|
|
1357
1454
|
|
|
1358
1455
|
Returns:
|
|
1359
|
-
|
|
1456
|
+
list[datatypes.ListModel]: A list of list objects associated with the bookmark.
|
|
1360
1457
|
If response validation is disabled, returns the raw API response (dict/list).
|
|
1361
1458
|
|
|
1362
1459
|
Raises:
|
|
@@ -1396,7 +1493,7 @@ class KarakeepAPI:
|
|
|
1396
1493
|
@optional_typecheck
|
|
1397
1494
|
def get_highlights_of_a_bookmark(
|
|
1398
1495
|
self, bookmark_id: str
|
|
1399
|
-
) -> Union[
|
|
1496
|
+
) -> Union[list[datatypes.Highlight], dict[str, Any], list[Any]]:
|
|
1400
1497
|
"""
|
|
1401
1498
|
Get all highlights associated with a specific bookmark. Corresponds to GET /bookmarks/{bookmarkId}/highlights.
|
|
1402
1499
|
|
|
@@ -1404,7 +1501,7 @@ class KarakeepAPI:
|
|
|
1404
1501
|
bookmark_id: The ID (string) of the bookmark.
|
|
1405
1502
|
|
|
1406
1503
|
Returns:
|
|
1407
|
-
|
|
1504
|
+
list[datatypes.Highlight]: A list of highlight objects associated with the bookmark.
|
|
1408
1505
|
If response validation is disabled, returns the raw API response (dict/list).
|
|
1409
1506
|
|
|
1410
1507
|
Raises:
|
|
@@ -1459,7 +1556,7 @@ class KarakeepAPI:
|
|
|
1459
1556
|
"avatar",
|
|
1460
1557
|
"unknown",
|
|
1461
1558
|
],
|
|
1462
|
-
) -> Union[datatypes.BookmarkAsset,
|
|
1559
|
+
) -> Union[datatypes.BookmarkAsset, dict[str, Any], list[Any]]:
|
|
1463
1560
|
"""
|
|
1464
1561
|
Attach a new asset to a bookmark. Corresponds to POST /bookmarks/{bookmarkId}/assets.
|
|
1465
1562
|
|
|
@@ -1537,12 +1634,12 @@ class KarakeepAPI:
|
|
|
1537
1634
|
@optional_typecheck
|
|
1538
1635
|
def get_all_lists(
|
|
1539
1636
|
self,
|
|
1540
|
-
) -> Union[
|
|
1637
|
+
) -> Union[list[datatypes.ListModel], dict[str, Any], list[Any]]:
|
|
1541
1638
|
"""
|
|
1542
1639
|
Get all lists for the current user. Corresponds to GET /lists.
|
|
1543
1640
|
|
|
1544
1641
|
Returns:
|
|
1545
|
-
|
|
1642
|
+
list[datatypes.ListModel]: A list of list objects.
|
|
1546
1643
|
If response validation is disabled, returns the raw API response (dict/list).
|
|
1547
1644
|
|
|
1548
1645
|
Raises:
|
|
@@ -1588,7 +1685,7 @@ class KarakeepAPI:
|
|
|
1588
1685
|
list_type: Optional[Literal["manual", "smart"]] = "manual",
|
|
1589
1686
|
query: Optional[str] = None,
|
|
1590
1687
|
public: bool = False,
|
|
1591
|
-
) -> Union[datatypes.ListModel,
|
|
1688
|
+
) -> Union[datatypes.ListModel, dict[str, Any], list[Any]]:
|
|
1592
1689
|
"""
|
|
1593
1690
|
Create a new list (manual or smart). Corresponds to POST /lists.
|
|
1594
1691
|
|
|
@@ -1642,7 +1739,7 @@ class KarakeepAPI:
|
|
|
1642
1739
|
@optional_typecheck
|
|
1643
1740
|
def get_a_single_list(
|
|
1644
1741
|
self, list_id: str
|
|
1645
|
-
) -> Union[datatypes.ListModel,
|
|
1742
|
+
) -> Union[datatypes.ListModel, dict[str, Any], list[Any]]:
|
|
1646
1743
|
"""
|
|
1647
1744
|
Get a single list by its ID. Corresponds to GET /lists/{listId}.
|
|
1648
1745
|
|
|
@@ -1695,7 +1792,7 @@ class KarakeepAPI:
|
|
|
1695
1792
|
parent_id: Optional[str] = None,
|
|
1696
1793
|
query: Optional[str] = None,
|
|
1697
1794
|
public: Optional[bool] = None,
|
|
1698
|
-
) -> Union[datatypes.ListModel,
|
|
1795
|
+
) -> Union[datatypes.ListModel, dict[str, Any], list[Any]]:
|
|
1699
1796
|
"""
|
|
1700
1797
|
Update a list by its ID. Corresponds to PATCH /lists/{listId}.
|
|
1701
1798
|
Allows updating various list fields including name, description, icon, parent relationship, query, and public status.
|
|
@@ -1755,7 +1852,7 @@ class KarakeepAPI:
|
|
|
1755
1852
|
limit: Optional[int] = None,
|
|
1756
1853
|
cursor: Optional[str] = None,
|
|
1757
1854
|
include_content: bool = True, # Default from spec
|
|
1758
|
-
) -> Union[datatypes.PaginatedBookmarks,
|
|
1855
|
+
) -> Union[datatypes.PaginatedBookmarks, dict[str, Any], list[Any]]:
|
|
1759
1856
|
"""
|
|
1760
1857
|
Get the bookmarks contained within a specific list. Corresponds to GET /lists/{listId}/bookmarks.
|
|
1761
1858
|
|
|
@@ -1836,7 +1933,7 @@ class KarakeepAPI:
|
|
|
1836
1933
|
attached_by: Optional[Literal["ai", "human", "none"]] = None,
|
|
1837
1934
|
cursor: Optional[str] = None,
|
|
1838
1935
|
limit: Optional[int] = None,
|
|
1839
|
-
) -> Union[datatypes.PaginatedTags,
|
|
1936
|
+
) -> Union[datatypes.PaginatedTags, dict[str, Any], list[Any]]:
|
|
1840
1937
|
"""
|
|
1841
1938
|
Get all tags for the current user. Corresponds to GET /tags.
|
|
1842
1939
|
|
|
@@ -1872,7 +1969,7 @@ class KarakeepAPI:
|
|
|
1872
1969
|
return datatypes.PaginatedTags.model_validate(response_data)
|
|
1873
1970
|
|
|
1874
1971
|
@optional_typecheck
|
|
1875
|
-
def create_a_new_tag(self, name: str) ->
|
|
1972
|
+
def create_a_new_tag(self, name: str) -> dict[str, Any]:
|
|
1876
1973
|
"""
|
|
1877
1974
|
Create a new tag. Corresponds to POST /tags.
|
|
1878
1975
|
|
|
@@ -1902,7 +1999,7 @@ class KarakeepAPI:
|
|
|
1902
1999
|
@optional_typecheck
|
|
1903
2000
|
def get_a_single_tag(
|
|
1904
2001
|
self, tag_id: str
|
|
1905
|
-
) -> Union[datatypes.Tag,
|
|
2002
|
+
) -> Union[datatypes.Tag, dict[str, Any], list[Any]]:
|
|
1906
2003
|
"""
|
|
1907
2004
|
Get a single tag by its ID. Corresponds to GET /tags/{tagId}.
|
|
1908
2005
|
|
|
@@ -1946,7 +2043,7 @@ class KarakeepAPI:
|
|
|
1946
2043
|
return None # Explicitly return None for 204
|
|
1947
2044
|
|
|
1948
2045
|
@optional_typecheck
|
|
1949
|
-
def update_a_tag(self, tag_id: str, update_data:
|
|
2046
|
+
def update_a_tag(self, tag_id: str, update_data: dict[str, Any]) -> dict[str, Any]:
|
|
1950
2047
|
"""
|
|
1951
2048
|
Update a tag by its ID. Currently only supports updating the "name".
|
|
1952
2049
|
Corresponds to PATCH /tags/{tagId}.
|
|
@@ -1982,7 +2079,7 @@ class KarakeepAPI:
|
|
|
1982
2079
|
limit: Optional[int] = None,
|
|
1983
2080
|
cursor: Optional[str] = None,
|
|
1984
2081
|
include_content: bool = True, # Default from spec
|
|
1985
|
-
) -> Union[datatypes.PaginatedBookmarks,
|
|
2082
|
+
) -> Union[datatypes.PaginatedBookmarks, dict[str, Any], list[Any]]:
|
|
1986
2083
|
"""
|
|
1987
2084
|
Get the bookmarks associated with a specific tag. Corresponds to GET /tags/{tagId}/bookmarks.
|
|
1988
2085
|
|
|
@@ -2020,7 +2117,7 @@ class KarakeepAPI:
|
|
|
2020
2117
|
@optional_typecheck
|
|
2021
2118
|
def get_all_highlights(
|
|
2022
2119
|
self, limit: Optional[int] = None, cursor: Optional[str] = None
|
|
2023
|
-
) -> Union[datatypes.PaginatedHighlights,
|
|
2120
|
+
) -> Union[datatypes.PaginatedHighlights, dict[str, Any], list[Any]]:
|
|
2024
2121
|
"""
|
|
2025
2122
|
Get all highlights for the current user. Corresponds to GET /highlights.
|
|
2026
2123
|
|
|
@@ -2029,7 +2126,9 @@ class KarakeepAPI:
|
|
|
2029
2126
|
cursor: Pagination cursor for the next page (optional).
|
|
2030
2127
|
|
|
2031
2128
|
Returns:
|
|
2032
|
-
datatypes.PaginatedHighlights: Paginated list of highlights.
|
|
2129
|
+
datatypes.PaginatedHighlights: Paginated list of highlights. Each item is a
|
|
2130
|
+
datatypes.HighlightWithBookmark, i.e. a Highlight plus a ``bookmark`` field
|
|
2131
|
+
holding the bookmark's title and url (None on servers predating it).
|
|
2033
2132
|
If response validation is disabled, returns the raw API response (dict/list).
|
|
2034
2133
|
|
|
2035
2134
|
Raises:
|
|
@@ -2055,7 +2154,9 @@ class KarakeepAPI:
|
|
|
2055
2154
|
color: Optional[Literal["yellow", "red", "green", "blue"]] = "yellow",
|
|
2056
2155
|
text: Optional[str] = None,
|
|
2057
2156
|
note: Optional[str] = None,
|
|
2058
|
-
|
|
2157
|
+
prefix: Optional[str] = None,
|
|
2158
|
+
suffix: Optional[str] = None,
|
|
2159
|
+
) -> Union[datatypes.Highlight, dict[str, Any], list[Any]]:
|
|
2059
2160
|
"""
|
|
2060
2161
|
Create a new highlight on a bookmark. Corresponds to POST /highlights.
|
|
2061
2162
|
|
|
@@ -2066,6 +2167,8 @@ class KarakeepAPI:
|
|
|
2066
2167
|
color: The color of the highlight ("yellow", "red", "green", "blue"). Default is "yellow".
|
|
2067
2168
|
text: Optional text content of the highlight.
|
|
2068
2169
|
note: Optional note associated with the highlight.
|
|
2170
|
+
prefix: Optional text immediately preceding the highlight, used by the server as context to re-anchor it if the offsets drift.
|
|
2171
|
+
suffix: Optional text immediately following the highlight, same purpose as prefix.
|
|
2069
2172
|
|
|
2070
2173
|
Returns:
|
|
2071
2174
|
datatypes.Highlight: The created highlight object.
|
|
@@ -2084,6 +2187,13 @@ class KarakeepAPI:
|
|
|
2084
2187
|
"text": text,
|
|
2085
2188
|
"note": note,
|
|
2086
2189
|
}
|
|
2190
|
+
# prefix/suffix are only sent when given: they are optional in the spec,
|
|
2191
|
+
# and omitting them keeps the request body identical to before for
|
|
2192
|
+
# servers that predate these fields.
|
|
2193
|
+
if prefix is not None:
|
|
2194
|
+
highlight_data["prefix"] = prefix
|
|
2195
|
+
if suffix is not None:
|
|
2196
|
+
highlight_data["suffix"] = suffix
|
|
2087
2197
|
|
|
2088
2198
|
response_data = self._call("POST", "highlights", data=highlight_data)
|
|
2089
2199
|
|
|
@@ -2097,7 +2207,7 @@ class KarakeepAPI:
|
|
|
2097
2207
|
@optional_typecheck
|
|
2098
2208
|
def get_a_single_highlight(
|
|
2099
2209
|
self, highlight_id: str
|
|
2100
|
-
) -> Union[datatypes.Highlight,
|
|
2210
|
+
) -> Union[datatypes.Highlight, dict[str, Any], list[Any]]:
|
|
2101
2211
|
"""
|
|
2102
2212
|
Get a single highlight by its ID. Corresponds to GET /highlights/{highlightId}.
|
|
2103
2213
|
|
|
@@ -2125,7 +2235,7 @@ class KarakeepAPI:
|
|
|
2125
2235
|
@optional_typecheck
|
|
2126
2236
|
def delete_a_highlight(
|
|
2127
2237
|
self, highlight_id: str
|
|
2128
|
-
) -> Union[datatypes.Highlight,
|
|
2238
|
+
) -> Union[datatypes.Highlight, dict[str, Any], list[Any]]:
|
|
2129
2239
|
"""
|
|
2130
2240
|
Delete a highlight by its ID. Corresponds to DELETE /highlights/{highlightId}.
|
|
2131
2241
|
Note: Unlike most DELETE endpoints, this returns the deleted highlight object on success (status 200).
|
|
@@ -2156,7 +2266,7 @@ class KarakeepAPI:
|
|
|
2156
2266
|
self,
|
|
2157
2267
|
highlight_id: str,
|
|
2158
2268
|
color: Optional[Literal["yellow", "red", "green", "blue"]] = None,
|
|
2159
|
-
) -> Union[datatypes.Highlight,
|
|
2269
|
+
) -> Union[datatypes.Highlight, dict[str, Any], list[Any]]:
|
|
2160
2270
|
"""
|
|
2161
2271
|
Update a highlight by its ID. Currently only supports updating the "color".
|
|
2162
2272
|
Corresponds to PATCH /highlights/{highlightId}.
|
|
@@ -2194,7 +2304,7 @@ class KarakeepAPI:
|
|
|
2194
2304
|
return datatypes.Highlight.model_validate(response_data)
|
|
2195
2305
|
|
|
2196
2306
|
@optional_typecheck
|
|
2197
|
-
def get_current_user_info(self) ->
|
|
2307
|
+
def get_current_user_info(self) -> dict[str, Any]:
|
|
2198
2308
|
"""
|
|
2199
2309
|
Get information about the current authenticated user. Corresponds to GET /users/me.
|
|
2200
2310
|
|
|
@@ -2210,7 +2320,7 @@ class KarakeepAPI:
|
|
|
2210
2320
|
return response_data
|
|
2211
2321
|
|
|
2212
2322
|
@optional_typecheck
|
|
2213
|
-
def get_current_user_stats(self) ->
|
|
2323
|
+
def get_current_user_stats(self) -> dict[str, Any]:
|
|
2214
2324
|
"""
|
|
2215
2325
|
Get statistics about the current authenticated user's data. Corresponds to GET /users/me/stats.
|
|
2216
2326
|
|
|
@@ -2241,7 +2351,7 @@ class KarakeepAPI:
|
|
|
2241
2351
|
bookmark_quota: Optional[int] = None,
|
|
2242
2352
|
storage_quota: Optional[int] = None,
|
|
2243
2353
|
browser_crawling_enabled: Optional[bool] = None,
|
|
2244
|
-
) ->
|
|
2354
|
+
) -> dict[str, Any]:
|
|
2245
2355
|
"""
|
|
2246
2356
|
Update a user's role, bookmark quota, or storage quota. Admin access required.
|
|
2247
2357
|
Corresponds to PUT /admin/users/{userId}.
|
|
@@ -2287,7 +2397,7 @@ class KarakeepAPI:
|
|
|
2287
2397
|
@optional_typecheck
|
|
2288
2398
|
def upload_a_new_asset(
|
|
2289
2399
|
self, file: str
|
|
2290
|
-
) -> Union[datatypes.UploadedAsset,
|
|
2400
|
+
) -> Union[datatypes.UploadedAsset, dict[str, Any], list[Any]]:
|
|
2291
2401
|
"""
|
|
2292
2402
|
Upload a new asset file. Corresponds to POST /assets.
|
|
2293
2403
|
|
|
@@ -2343,12 +2453,12 @@ class KarakeepAPI:
|
|
|
2343
2453
|
@optional_typecheck
|
|
2344
2454
|
def get_all_backups(
|
|
2345
2455
|
self,
|
|
2346
|
-
) -> Union[
|
|
2456
|
+
) -> Union[list[datatypes.Backup], dict[str, Any], list[Any]]:
|
|
2347
2457
|
"""
|
|
2348
2458
|
Get all backups for the current user. Corresponds to GET /backups.
|
|
2349
2459
|
|
|
2350
2460
|
Returns:
|
|
2351
|
-
|
|
2461
|
+
list[datatypes.Backup]: A list of backup objects.
|
|
2352
2462
|
If response validation is disabled, returns the raw API response (dict/list).
|
|
2353
2463
|
|
|
2354
2464
|
Raises:
|
|
@@ -2387,7 +2497,7 @@ class KarakeepAPI:
|
|
|
2387
2497
|
@optional_typecheck
|
|
2388
2498
|
def trigger_a_new_backup(
|
|
2389
2499
|
self,
|
|
2390
|
-
) -> Union[datatypes.Backup,
|
|
2500
|
+
) -> Union[datatypes.Backup, dict[str, Any], list[Any]]:
|
|
2391
2501
|
"""
|
|
2392
2502
|
Trigger a new backup. Corresponds to POST /backups.
|
|
2393
2503
|
|
|
@@ -2411,7 +2521,7 @@ class KarakeepAPI:
|
|
|
2411
2521
|
@optional_typecheck
|
|
2412
2522
|
def get_a_single_backup(
|
|
2413
2523
|
self, backup_id: str
|
|
2414
|
-
) -> Union[datatypes.Backup,
|
|
2524
|
+
) -> Union[datatypes.Backup, dict[str, Any], list[Any]]:
|
|
2415
2525
|
"""
|
|
2416
2526
|
Get a single backup by its ID. Corresponds to GET /backups/{backupId}.
|
|
2417
2527
|
|
|
@@ -2589,7 +2699,7 @@ class KarakeepAPI:
|
|
|
2589
2699
|
@optional_typecheck
|
|
2590
2700
|
def get_asset_signed_url(
|
|
2591
2701
|
self, asset_id: str
|
|
2592
|
-
) -> Union[datatypes.SignedAssetUrl,
|
|
2702
|
+
) -> Union[datatypes.SignedAssetUrl, dict[str, Any], list[Any]]:
|
|
2593
2703
|
"""
|
|
2594
2704
|
Get a temporary signed URL for downloading an asset.
|
|
2595
2705
|
Corresponds to GET /assets/{assetId}/signed-url.
|
|
@@ -2632,7 +2742,7 @@ class KarakeepAPI:
|
|
|
2632
2742
|
crawl_status: Literal["success", "failure", "pending", "all"] = "all",
|
|
2633
2743
|
run_inference: bool = False,
|
|
2634
2744
|
modified_within_seconds: Optional[int] = None,
|
|
2635
|
-
) ->
|
|
2745
|
+
) -> dict[str, Any]:
|
|
2636
2746
|
"""
|
|
2637
2747
|
Trigger a recrawl of link bookmarks. Admin only.
|
|
2638
2748
|
Corresponds to POST /admin/jobs/trigger/recrawl.
|
|
@@ -2651,7 +2761,7 @@ class KarakeepAPI:
|
|
|
2651
2761
|
Raises:
|
|
2652
2762
|
APIError: If the API request fails (e.g., 403 admin access required).
|
|
2653
2763
|
"""
|
|
2654
|
-
body:
|
|
2764
|
+
body: dict[str, Any] = {
|
|
2655
2765
|
"crawlStatus": crawl_status,
|
|
2656
2766
|
"runInference": run_inference,
|
|
2657
2767
|
}
|
|
@@ -2665,7 +2775,7 @@ class KarakeepAPI:
|
|
|
2665
2775
|
def admin_trigger_reindex(
|
|
2666
2776
|
self,
|
|
2667
2777
|
modified_within_seconds: Optional[int] = None,
|
|
2668
|
-
) ->
|
|
2778
|
+
) -> dict[str, Any]:
|
|
2669
2779
|
"""
|
|
2670
2780
|
Trigger a reindex of bookmarks in the search engine. Admin only.
|
|
2671
2781
|
Corresponds to POST /admin/jobs/trigger/reindex.
|
|
@@ -2702,7 +2812,7 @@ class KarakeepAPI:
|
|
|
2702
2812
|
type: Literal["tag", "summarize"],
|
|
2703
2813
|
status: Literal["success", "failure", "pending", "all"] = "all",
|
|
2704
2814
|
modified_within_seconds: Optional[int] = None,
|
|
2705
|
-
) ->
|
|
2815
|
+
) -> dict[str, Any]:
|
|
2706
2816
|
"""
|
|
2707
2817
|
Trigger AI inference (tagging or summarization) on bookmarks. Admin only.
|
|
2708
2818
|
Corresponds to POST /admin/jobs/trigger/inference.
|
|
@@ -2722,7 +2832,7 @@ class KarakeepAPI:
|
|
|
2722
2832
|
Raises:
|
|
2723
2833
|
APIError: If the API request fails (e.g., 403 admin access required).
|
|
2724
2834
|
"""
|
|
2725
|
-
body:
|
|
2835
|
+
body: dict[str, Any] = {"type": type, "status": status}
|
|
2726
2836
|
# See admin_trigger_recrawl: the key is omitted rather than sent as null.
|
|
2727
2837
|
if modified_within_seconds is not None:
|
|
2728
2838
|
body["modifiedWithinSeconds"] = modified_within_seconds
|
|
@@ -2733,12 +2843,12 @@ class KarakeepAPI:
|
|
|
2733
2843
|
@optional_typecheck
|
|
2734
2844
|
def get_all_feeds(
|
|
2735
2845
|
self,
|
|
2736
|
-
) -> Union[
|
|
2846
|
+
) -> Union[list[datatypes.Feed], dict[str, Any], list[Any]]:
|
|
2737
2847
|
"""
|
|
2738
2848
|
Get all RSS feed subscriptions for the current user. Corresponds to GET /feeds.
|
|
2739
2849
|
|
|
2740
2850
|
Returns:
|
|
2741
|
-
|
|
2851
|
+
list[datatypes.Feed]: A list of feed objects.
|
|
2742
2852
|
If response validation is disabled, returns the raw API response (dict/list).
|
|
2743
2853
|
|
|
2744
2854
|
Raises:
|
|
@@ -2769,7 +2879,7 @@ class KarakeepAPI:
|
|
|
2769
2879
|
url: str,
|
|
2770
2880
|
enabled: bool = True,
|
|
2771
2881
|
import_tags: bool = False,
|
|
2772
|
-
) -> Union[datatypes.Feed,
|
|
2882
|
+
) -> Union[datatypes.Feed, dict[str, Any], list[Any]]:
|
|
2773
2883
|
"""
|
|
2774
2884
|
Create a new RSS feed subscription. Corresponds to POST /feeds.
|
|
2775
2885
|
|
|
@@ -2803,7 +2913,7 @@ class KarakeepAPI:
|
|
|
2803
2913
|
@optional_typecheck
|
|
2804
2914
|
def get_a_single_feed(
|
|
2805
2915
|
self, feed_id: str
|
|
2806
|
-
) -> Union[datatypes.Feed,
|
|
2916
|
+
) -> Union[datatypes.Feed, dict[str, Any], list[Any]]:
|
|
2807
2917
|
"""
|
|
2808
2918
|
Get a single RSS feed by its ID. Corresponds to GET /feeds/{feedId}.
|
|
2809
2919
|
|
|
@@ -2832,7 +2942,7 @@ class KarakeepAPI:
|
|
|
2832
2942
|
url: Optional[str] = None,
|
|
2833
2943
|
enabled: Optional[bool] = None,
|
|
2834
2944
|
import_tags: Optional[bool] = None,
|
|
2835
|
-
) -> Union[datatypes.Feed,
|
|
2945
|
+
) -> Union[datatypes.Feed, dict[str, Any], list[Any]]:
|
|
2836
2946
|
"""
|
|
2837
2947
|
Update an RSS feed subscription. Corresponds to PATCH /feeds/{feedId}.
|
|
2838
2948
|
|
|
@@ -2851,7 +2961,7 @@ class KarakeepAPI:
|
|
|
2851
2961
|
ValueError: If no fields are provided to update.
|
|
2852
2962
|
APIError: If the API request fails (e.g., 404 feed not found).
|
|
2853
2963
|
"""
|
|
2854
|
-
update_data:
|
|
2964
|
+
update_data: dict[str, Any] = {}
|
|
2855
2965
|
if name is not None:
|
|
2856
2966
|
update_data["name"] = name
|
|
2857
2967
|
if url is not None:
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
"url": "{address}/api/v1",
|
|
49
49
|
"variables": {
|
|
50
50
|
"address": {
|
|
51
|
-
"default": "https://try.karakeep.
|
|
51
|
+
"default": "https://try.karakeep.com",
|
|
52
52
|
"description": "The address of the Karakeep server"
|
|
53
53
|
}
|
|
54
54
|
}
|
|
@@ -465,6 +465,10 @@
|
|
|
465
465
|
"fileName": {
|
|
466
466
|
"type": "string",
|
|
467
467
|
"nullable": true
|
|
468
|
+
},
|
|
469
|
+
"size": {
|
|
470
|
+
"type": "number",
|
|
471
|
+
"nullable": true
|
|
468
472
|
}
|
|
469
473
|
},
|
|
470
474
|
"required": [
|
|
@@ -665,6 +669,14 @@
|
|
|
665
669
|
"type": "string",
|
|
666
670
|
"nullable": true
|
|
667
671
|
},
|
|
672
|
+
"prefix": {
|
|
673
|
+
"type": "string",
|
|
674
|
+
"nullable": true
|
|
675
|
+
},
|
|
676
|
+
"suffix": {
|
|
677
|
+
"type": "string",
|
|
678
|
+
"nullable": true
|
|
679
|
+
},
|
|
668
680
|
"note": {
|
|
669
681
|
"type": "string",
|
|
670
682
|
"nullable": true
|
|
@@ -685,6 +697,8 @@
|
|
|
685
697
|
"startOffset",
|
|
686
698
|
"endOffset",
|
|
687
699
|
"text",
|
|
700
|
+
"prefix",
|
|
701
|
+
"suffix",
|
|
688
702
|
"note",
|
|
689
703
|
"id",
|
|
690
704
|
"userId",
|
|
@@ -728,7 +742,7 @@
|
|
|
728
742
|
"highlights": {
|
|
729
743
|
"type": "array",
|
|
730
744
|
"items": {
|
|
731
|
-
"$ref": "#/components/schemas/
|
|
745
|
+
"$ref": "#/components/schemas/HighlightWithBookmark"
|
|
732
746
|
}
|
|
733
747
|
},
|
|
734
748
|
"nextCursor": {
|
|
@@ -742,6 +756,86 @@
|
|
|
742
756
|
"nextCursor"
|
|
743
757
|
]
|
|
744
758
|
},
|
|
759
|
+
"HighlightWithBookmark": {
|
|
760
|
+
"type": "object",
|
|
761
|
+
"properties": {
|
|
762
|
+
"bookmarkId": {
|
|
763
|
+
"type": "string"
|
|
764
|
+
},
|
|
765
|
+
"startOffset": {
|
|
766
|
+
"type": "number"
|
|
767
|
+
},
|
|
768
|
+
"endOffset": {
|
|
769
|
+
"type": "number"
|
|
770
|
+
},
|
|
771
|
+
"color": {
|
|
772
|
+
"type": "string",
|
|
773
|
+
"enum": [
|
|
774
|
+
"yellow",
|
|
775
|
+
"red",
|
|
776
|
+
"green",
|
|
777
|
+
"blue"
|
|
778
|
+
],
|
|
779
|
+
"default": "yellow"
|
|
780
|
+
},
|
|
781
|
+
"text": {
|
|
782
|
+
"type": "string",
|
|
783
|
+
"nullable": true
|
|
784
|
+
},
|
|
785
|
+
"prefix": {
|
|
786
|
+
"type": "string",
|
|
787
|
+
"nullable": true
|
|
788
|
+
},
|
|
789
|
+
"suffix": {
|
|
790
|
+
"type": "string",
|
|
791
|
+
"nullable": true
|
|
792
|
+
},
|
|
793
|
+
"note": {
|
|
794
|
+
"type": "string",
|
|
795
|
+
"nullable": true
|
|
796
|
+
},
|
|
797
|
+
"id": {
|
|
798
|
+
"type": "string"
|
|
799
|
+
},
|
|
800
|
+
"userId": {
|
|
801
|
+
"type": "string"
|
|
802
|
+
},
|
|
803
|
+
"createdAt": {
|
|
804
|
+
"type": "string",
|
|
805
|
+
"format": "date-time"
|
|
806
|
+
},
|
|
807
|
+
"bookmark": {
|
|
808
|
+
"type": "object",
|
|
809
|
+
"properties": {
|
|
810
|
+
"title": {
|
|
811
|
+
"type": "string",
|
|
812
|
+
"nullable": true
|
|
813
|
+
},
|
|
814
|
+
"url": {
|
|
815
|
+
"type": "string",
|
|
816
|
+
"nullable": true
|
|
817
|
+
}
|
|
818
|
+
},
|
|
819
|
+
"required": [
|
|
820
|
+
"title",
|
|
821
|
+
"url"
|
|
822
|
+
]
|
|
823
|
+
}
|
|
824
|
+
},
|
|
825
|
+
"required": [
|
|
826
|
+
"bookmarkId",
|
|
827
|
+
"startOffset",
|
|
828
|
+
"endOffset",
|
|
829
|
+
"text",
|
|
830
|
+
"prefix",
|
|
831
|
+
"suffix",
|
|
832
|
+
"note",
|
|
833
|
+
"id",
|
|
834
|
+
"userId",
|
|
835
|
+
"createdAt",
|
|
836
|
+
"bookmark"
|
|
837
|
+
]
|
|
838
|
+
},
|
|
745
839
|
"UploadedAsset": {
|
|
746
840
|
"type": "object",
|
|
747
841
|
"properties": {
|
|
@@ -2383,6 +2477,10 @@
|
|
|
2383
2477
|
"fileName": {
|
|
2384
2478
|
"type": "string",
|
|
2385
2479
|
"nullable": true
|
|
2480
|
+
},
|
|
2481
|
+
"size": {
|
|
2482
|
+
"type": "number",
|
|
2483
|
+
"nullable": true
|
|
2386
2484
|
}
|
|
2387
2485
|
},
|
|
2388
2486
|
"required": [
|
|
@@ -3609,6 +3707,14 @@
|
|
|
3609
3707
|
"type": "string",
|
|
3610
3708
|
"nullable": true
|
|
3611
3709
|
},
|
|
3710
|
+
"prefix": {
|
|
3711
|
+
"type": "string",
|
|
3712
|
+
"nullable": true
|
|
3713
|
+
},
|
|
3714
|
+
"suffix": {
|
|
3715
|
+
"type": "string",
|
|
3716
|
+
"nullable": true
|
|
3717
|
+
},
|
|
3612
3718
|
"note": {
|
|
3613
3719
|
"type": "string",
|
|
3614
3720
|
"nullable": true
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: karakeep_python_api
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.10.0
|
|
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
|
|
@@ -146,7 +146,7 @@ This package can be used as a Python library or as a command-line interface (CLI
|
|
|
146
146
|
|
|
147
147
|
The client can be configured using the following environment variables:
|
|
148
148
|
|
|
149
|
-
* `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.
|
|
149
|
+
* `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.com/api/v1/`).
|
|
150
150
|
* `KARAKEEP_PYTHON_API_KEY`: **Required**. Your Karakeep API key (Bearer token).
|
|
151
151
|
* `KARAKEEP_PYTHON_API_VERIFY_SSL`: Set to `false` to disable SSL certificate verification (default: `true`).
|
|
152
152
|
* `KARAKEEP_PYTHON_API_VERBOSE`: Set to `true` to enable verbose debug logging for the client and CLI (default: `false`).
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
karakeep_python_api/__init__.py,sha256=e2-y0wlhuQPRX2gMXZKGJH8LHHV9dUd6a0qXMZt1KgE,683
|
|
2
|
+
karakeep_python_api/__main__.py,sha256=tH4A6J1UFMRSyEfJnPA_QExI1kvO19nhiH0nV1HqA5w,39356
|
|
3
|
+
karakeep_python_api/datatypes.py,sha256=gdqRdaafmJCrkLMY-pZixFflDmrdMhhBLR3GK9WlIvY,8139
|
|
4
|
+
karakeep_python_api/karakeep_api.py,sha256=yB8o4hwtov17fvN5chQP4fuSJrBzRptfZH2MtmjCO2o,130614
|
|
5
|
+
karakeep_python_api/openapi_reference.json,sha256=vfhPYYMrtpfI_Jgz1E6FDlHM1jog2nY_SxcehyxiORU,165805
|
|
6
|
+
karakeep_python_api-1.10.0.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
|
|
7
|
+
karakeep_python_api-1.10.0.dist-info/METADATA,sha256=PUBQCIJEQV8cIzYACMS5IHitI5tLcfJks5zYsBBBnOs,17688
|
|
8
|
+
karakeep_python_api-1.10.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
9
|
+
karakeep_python_api-1.10.0.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
|
|
10
|
+
karakeep_python_api-1.10.0.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
|
|
11
|
+
karakeep_python_api-1.10.0.dist-info/RECORD,,
|
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
karakeep_python_api/__init__.py,sha256=qk3MeIIvnCNAyYzJrv8dMKVXvA4ejLU3mhB3xFzdLDY,606
|
|
2
|
-
karakeep_python_api/__main__.py,sha256=weIwZtSEe8rbSd1nnVj-F__e84tBsVZTaR6DGdZFhn4,39410
|
|
3
|
-
karakeep_python_api/datatypes.py,sha256=tOROux_Ehnum0hmbopFfYBZ_ZaB8M22ktPXWtnOP8ig,6936
|
|
4
|
-
karakeep_python_api/karakeep_api.py,sha256=ExS7S8CjyNYF56G-TitRPlQewyx-Q5rRBkhrbm3-ukk,126407
|
|
5
|
-
karakeep_python_api/openapi_reference.json,sha256=uENNNF1bHCuHzJPHQa2-DfqlEOBrLmQ0mFrVnPu9XaA,163271
|
|
6
|
-
karakeep_python_api-1.9.0.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
|
|
7
|
-
karakeep_python_api-1.9.0.dist-info/METADATA,sha256=P9j-caj1OfqFGsnIGvwpKlRVvYrUd6_w37wACZ_v_pE,17687
|
|
8
|
-
karakeep_python_api-1.9.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
|
|
9
|
-
karakeep_python_api-1.9.0.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
|
|
10
|
-
karakeep_python_api-1.9.0.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
|
|
11
|
-
karakeep_python_api-1.9.0.dist-info/RECORD,,
|
{karakeep_python_api-1.9.0.dist-info → karakeep_python_api-1.10.0.dist-info}/entry_points.txt
RENAMED
|
File without changes
|
{karakeep_python_api-1.9.0.dist-info → karakeep_python_api-1.10.0.dist-info}/licenses/LICENSE
RENAMED
|
File without changes
|
|
File without changes
|