karakeep-python-api 1.9.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.
@@ -1,5 +1,10 @@
1
1
  # Import API class and errors directly from the module
2
- from .karakeep_api import KarakeepAPI, APIError, AuthenticationError
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 typing.Dict/List
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 List[T] or Dict[K, V] - expect JSON string
684
- elif origin in (list, dict, List, Dict) or annotation 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:
@@ -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 List, Optional, Union, Literal
8
+ from typing import Optional, Union, Literal
9
9
 
10
10
  from pydantic import BaseModel, Field, RootModel
11
11
 
@@ -154,11 +154,11 @@ class Bookmark(BaseModel):
154
154
  ]
155
155
  ] = None
156
156
  userId: str
157
- tags: List[TagShort]
157
+ tags: list[TagShort]
158
158
  content: Union[
159
159
  ContentTypeLink, ContentTypeText, ContentTypeAsset, ContentTypeUnknown
160
160
  ]
161
- assets: List[BookmarkAsset]
161
+ assets: list[BookmarkAsset]
162
162
 
163
163
 
164
164
  class ReadableContentRange(BaseModel):
@@ -184,7 +184,7 @@ class BookmarkReadableContent(BaseModel):
184
184
 
185
185
 
186
186
  class PaginatedBookmarks(BaseModel):
187
- bookmarks: List[Bookmark]
187
+ bookmarks: list[Bookmark]
188
188
  nextCursor: Optional[str] = ""
189
189
 
190
190
 
@@ -218,12 +218,12 @@ class Highlight(BaseModel):
218
218
 
219
219
 
220
220
  class PaginatedHighlights(BaseModel):
221
- highlights: List[Highlight]
221
+ highlights: list[Highlight]
222
222
  nextCursor: Optional[str] = ""
223
223
 
224
224
 
225
225
  class PaginatedTags(BaseModel):
226
- tags: List[Tag]
226
+ tags: list[Tag]
227
227
  nextCursor: Optional[str] = ""
228
228
 
229
229
 
@@ -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, Dict, Any, List, Callable, Tuple, Union, Type, Literal
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.9.0"
195
+ VERSION: str = "1.9.1"
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
- # logger.remove() # Remove default handler
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[Dict[str, Any]] = None # Initialize attribute
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[Dict[str, Any]] = None,
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[Dict[str, Any]] = None,
320
- extra_headers: Optional[Dict[str, str]] = None,
321
- ) -> Union[Dict[str, Any], List[Any], None, bytes]:
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, Dict[str, Any], List[Any]]:
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, Dict[str, Any], List[Any]]:
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: Dict[str, Any] = {"type": type}
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, Dict[str, Any], List[Any]]:
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, Dict[str, Any], List[Any]]:
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, Dict[str, Any], List[Any]]:
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: Dict[str, Any],
1032
- ) -> Dict[str, Any]:
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, Dict[str, Any], List[Any]]:
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) -> Dict[str, Any]:
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[List[str]] = None,
1187
- tag_names: Optional[List[str]] = None,
1283
+ tag_ids: Optional[list[str]] = None,
1284
+ tag_names: Optional[list[str]] = None,
1188
1285
  attached_by: Optional[Literal["ai", "human"]] = "human",
1189
- ) -> Dict[str, Any]:
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: Dict[str, Any] = {"tagId": tag_id.strip()}
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[List[str]] = None,
1270
- tag_names: Optional[List[str]] = None,
1366
+ tag_ids: Optional[list[str]] = None,
1367
+ tag_names: Optional[list[str]] = None,
1271
1368
  attached_by: Optional[Literal["ai", "human"]] = "human",
1272
- ) -> Dict[str, Any]:
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: Dict[str, Any] = {"tagId": tag_id.strip()}
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[List[datatypes.ListModel], Dict[str, Any], List[Any]]:
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
- List[datatypes.ListModel]: A list of list objects associated with the bookmark.
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[List[datatypes.Highlight], Dict[str, Any], List[Any]]:
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
- List[datatypes.Highlight]: A list of highlight objects associated with the bookmark.
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, Dict[str, Any], List[Any]]:
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[List[datatypes.ListModel], Dict[str, Any], List[Any]]:
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
- List[datatypes.ListModel]: A list of list objects.
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, Dict[str, Any], List[Any]]:
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, Dict[str, Any], List[Any]]:
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, Dict[str, Any], List[Any]]:
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, Dict[str, Any], List[Any]]:
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, Dict[str, Any], List[Any]]:
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) -> Dict[str, Any]:
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, Dict[str, Any], List[Any]]:
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: Dict[str, Any]) -> Dict[str, Any]:
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, Dict[str, Any], List[Any]]:
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, Dict[str, Any], List[Any]]:
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
 
@@ -2055,7 +2152,7 @@ class KarakeepAPI:
2055
2152
  color: Optional[Literal["yellow", "red", "green", "blue"]] = "yellow",
2056
2153
  text: Optional[str] = None,
2057
2154
  note: Optional[str] = None,
2058
- ) -> Union[datatypes.Highlight, Dict[str, Any], List[Any]]:
2155
+ ) -> Union[datatypes.Highlight, dict[str, Any], list[Any]]:
2059
2156
  """
2060
2157
  Create a new highlight on a bookmark. Corresponds to POST /highlights.
2061
2158
 
@@ -2097,7 +2194,7 @@ class KarakeepAPI:
2097
2194
  @optional_typecheck
2098
2195
  def get_a_single_highlight(
2099
2196
  self, highlight_id: str
2100
- ) -> Union[datatypes.Highlight, Dict[str, Any], List[Any]]:
2197
+ ) -> Union[datatypes.Highlight, dict[str, Any], list[Any]]:
2101
2198
  """
2102
2199
  Get a single highlight by its ID. Corresponds to GET /highlights/{highlightId}.
2103
2200
 
@@ -2125,7 +2222,7 @@ class KarakeepAPI:
2125
2222
  @optional_typecheck
2126
2223
  def delete_a_highlight(
2127
2224
  self, highlight_id: str
2128
- ) -> Union[datatypes.Highlight, Dict[str, Any], List[Any]]:
2225
+ ) -> Union[datatypes.Highlight, dict[str, Any], list[Any]]:
2129
2226
  """
2130
2227
  Delete a highlight by its ID. Corresponds to DELETE /highlights/{highlightId}.
2131
2228
  Note: Unlike most DELETE endpoints, this returns the deleted highlight object on success (status 200).
@@ -2156,7 +2253,7 @@ class KarakeepAPI:
2156
2253
  self,
2157
2254
  highlight_id: str,
2158
2255
  color: Optional[Literal["yellow", "red", "green", "blue"]] = None,
2159
- ) -> Union[datatypes.Highlight, Dict[str, Any], List[Any]]:
2256
+ ) -> Union[datatypes.Highlight, dict[str, Any], list[Any]]:
2160
2257
  """
2161
2258
  Update a highlight by its ID. Currently only supports updating the "color".
2162
2259
  Corresponds to PATCH /highlights/{highlightId}.
@@ -2194,7 +2291,7 @@ class KarakeepAPI:
2194
2291
  return datatypes.Highlight.model_validate(response_data)
2195
2292
 
2196
2293
  @optional_typecheck
2197
- def get_current_user_info(self) -> Dict[str, Any]:
2294
+ def get_current_user_info(self) -> dict[str, Any]:
2198
2295
  """
2199
2296
  Get information about the current authenticated user. Corresponds to GET /users/me.
2200
2297
 
@@ -2210,7 +2307,7 @@ class KarakeepAPI:
2210
2307
  return response_data
2211
2308
 
2212
2309
  @optional_typecheck
2213
- def get_current_user_stats(self) -> Dict[str, Any]:
2310
+ def get_current_user_stats(self) -> dict[str, Any]:
2214
2311
  """
2215
2312
  Get statistics about the current authenticated user's data. Corresponds to GET /users/me/stats.
2216
2313
 
@@ -2241,7 +2338,7 @@ class KarakeepAPI:
2241
2338
  bookmark_quota: Optional[int] = None,
2242
2339
  storage_quota: Optional[int] = None,
2243
2340
  browser_crawling_enabled: Optional[bool] = None,
2244
- ) -> Dict[str, Any]:
2341
+ ) -> dict[str, Any]:
2245
2342
  """
2246
2343
  Update a user's role, bookmark quota, or storage quota. Admin access required.
2247
2344
  Corresponds to PUT /admin/users/{userId}.
@@ -2287,7 +2384,7 @@ class KarakeepAPI:
2287
2384
  @optional_typecheck
2288
2385
  def upload_a_new_asset(
2289
2386
  self, file: str
2290
- ) -> Union[datatypes.UploadedAsset, Dict[str, Any], List[Any]]:
2387
+ ) -> Union[datatypes.UploadedAsset, dict[str, Any], list[Any]]:
2291
2388
  """
2292
2389
  Upload a new asset file. Corresponds to POST /assets.
2293
2390
 
@@ -2343,12 +2440,12 @@ class KarakeepAPI:
2343
2440
  @optional_typecheck
2344
2441
  def get_all_backups(
2345
2442
  self,
2346
- ) -> Union[List[datatypes.Backup], Dict[str, Any], List[Any]]:
2443
+ ) -> Union[list[datatypes.Backup], dict[str, Any], list[Any]]:
2347
2444
  """
2348
2445
  Get all backups for the current user. Corresponds to GET /backups.
2349
2446
 
2350
2447
  Returns:
2351
- List[datatypes.Backup]: A list of backup objects.
2448
+ list[datatypes.Backup]: A list of backup objects.
2352
2449
  If response validation is disabled, returns the raw API response (dict/list).
2353
2450
 
2354
2451
  Raises:
@@ -2387,7 +2484,7 @@ class KarakeepAPI:
2387
2484
  @optional_typecheck
2388
2485
  def trigger_a_new_backup(
2389
2486
  self,
2390
- ) -> Union[datatypes.Backup, Dict[str, Any], List[Any]]:
2487
+ ) -> Union[datatypes.Backup, dict[str, Any], list[Any]]:
2391
2488
  """
2392
2489
  Trigger a new backup. Corresponds to POST /backups.
2393
2490
 
@@ -2411,7 +2508,7 @@ class KarakeepAPI:
2411
2508
  @optional_typecheck
2412
2509
  def get_a_single_backup(
2413
2510
  self, backup_id: str
2414
- ) -> Union[datatypes.Backup, Dict[str, Any], List[Any]]:
2511
+ ) -> Union[datatypes.Backup, dict[str, Any], list[Any]]:
2415
2512
  """
2416
2513
  Get a single backup by its ID. Corresponds to GET /backups/{backupId}.
2417
2514
 
@@ -2589,7 +2686,7 @@ class KarakeepAPI:
2589
2686
  @optional_typecheck
2590
2687
  def get_asset_signed_url(
2591
2688
  self, asset_id: str
2592
- ) -> Union[datatypes.SignedAssetUrl, Dict[str, Any], List[Any]]:
2689
+ ) -> Union[datatypes.SignedAssetUrl, dict[str, Any], list[Any]]:
2593
2690
  """
2594
2691
  Get a temporary signed URL for downloading an asset.
2595
2692
  Corresponds to GET /assets/{assetId}/signed-url.
@@ -2632,7 +2729,7 @@ class KarakeepAPI:
2632
2729
  crawl_status: Literal["success", "failure", "pending", "all"] = "all",
2633
2730
  run_inference: bool = False,
2634
2731
  modified_within_seconds: Optional[int] = None,
2635
- ) -> Dict[str, Any]:
2732
+ ) -> dict[str, Any]:
2636
2733
  """
2637
2734
  Trigger a recrawl of link bookmarks. Admin only.
2638
2735
  Corresponds to POST /admin/jobs/trigger/recrawl.
@@ -2651,7 +2748,7 @@ class KarakeepAPI:
2651
2748
  Raises:
2652
2749
  APIError: If the API request fails (e.g., 403 admin access required).
2653
2750
  """
2654
- body: Dict[str, Any] = {
2751
+ body: dict[str, Any] = {
2655
2752
  "crawlStatus": crawl_status,
2656
2753
  "runInference": run_inference,
2657
2754
  }
@@ -2665,7 +2762,7 @@ class KarakeepAPI:
2665
2762
  def admin_trigger_reindex(
2666
2763
  self,
2667
2764
  modified_within_seconds: Optional[int] = None,
2668
- ) -> Dict[str, Any]:
2765
+ ) -> dict[str, Any]:
2669
2766
  """
2670
2767
  Trigger a reindex of bookmarks in the search engine. Admin only.
2671
2768
  Corresponds to POST /admin/jobs/trigger/reindex.
@@ -2702,7 +2799,7 @@ class KarakeepAPI:
2702
2799
  type: Literal["tag", "summarize"],
2703
2800
  status: Literal["success", "failure", "pending", "all"] = "all",
2704
2801
  modified_within_seconds: Optional[int] = None,
2705
- ) -> Dict[str, Any]:
2802
+ ) -> dict[str, Any]:
2706
2803
  """
2707
2804
  Trigger AI inference (tagging or summarization) on bookmarks. Admin only.
2708
2805
  Corresponds to POST /admin/jobs/trigger/inference.
@@ -2722,7 +2819,7 @@ class KarakeepAPI:
2722
2819
  Raises:
2723
2820
  APIError: If the API request fails (e.g., 403 admin access required).
2724
2821
  """
2725
- body: Dict[str, Any] = {"type": type, "status": status}
2822
+ body: dict[str, Any] = {"type": type, "status": status}
2726
2823
  # See admin_trigger_recrawl: the key is omitted rather than sent as null.
2727
2824
  if modified_within_seconds is not None:
2728
2825
  body["modifiedWithinSeconds"] = modified_within_seconds
@@ -2733,12 +2830,12 @@ class KarakeepAPI:
2733
2830
  @optional_typecheck
2734
2831
  def get_all_feeds(
2735
2832
  self,
2736
- ) -> Union[List[datatypes.Feed], Dict[str, Any], List[Any]]:
2833
+ ) -> Union[list[datatypes.Feed], dict[str, Any], list[Any]]:
2737
2834
  """
2738
2835
  Get all RSS feed subscriptions for the current user. Corresponds to GET /feeds.
2739
2836
 
2740
2837
  Returns:
2741
- List[datatypes.Feed]: A list of feed objects.
2838
+ list[datatypes.Feed]: A list of feed objects.
2742
2839
  If response validation is disabled, returns the raw API response (dict/list).
2743
2840
 
2744
2841
  Raises:
@@ -2769,7 +2866,7 @@ class KarakeepAPI:
2769
2866
  url: str,
2770
2867
  enabled: bool = True,
2771
2868
  import_tags: bool = False,
2772
- ) -> Union[datatypes.Feed, Dict[str, Any], List[Any]]:
2869
+ ) -> Union[datatypes.Feed, dict[str, Any], list[Any]]:
2773
2870
  """
2774
2871
  Create a new RSS feed subscription. Corresponds to POST /feeds.
2775
2872
 
@@ -2803,7 +2900,7 @@ class KarakeepAPI:
2803
2900
  @optional_typecheck
2804
2901
  def get_a_single_feed(
2805
2902
  self, feed_id: str
2806
- ) -> Union[datatypes.Feed, Dict[str, Any], List[Any]]:
2903
+ ) -> Union[datatypes.Feed, dict[str, Any], list[Any]]:
2807
2904
  """
2808
2905
  Get a single RSS feed by its ID. Corresponds to GET /feeds/{feedId}.
2809
2906
 
@@ -2832,7 +2929,7 @@ class KarakeepAPI:
2832
2929
  url: Optional[str] = None,
2833
2930
  enabled: Optional[bool] = None,
2834
2931
  import_tags: Optional[bool] = None,
2835
- ) -> Union[datatypes.Feed, Dict[str, Any], List[Any]]:
2932
+ ) -> Union[datatypes.Feed, dict[str, Any], list[Any]]:
2836
2933
  """
2837
2934
  Update an RSS feed subscription. Corresponds to PATCH /feeds/{feedId}.
2838
2935
 
@@ -2851,7 +2948,7 @@ class KarakeepAPI:
2851
2948
  ValueError: If no fields are provided to update.
2852
2949
  APIError: If the API request fails (e.g., 404 feed not found).
2853
2950
  """
2854
- update_data: Dict[str, Any] = {}
2951
+ update_data: dict[str, Any] = {}
2855
2952
  if name is not None:
2856
2953
  update_data["name"] = name
2857
2954
  if url is not None:
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: karakeep_python_api
3
- Version: 1.9.0
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
@@ -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=CDZDVbidr0JLb8aahrTx9En760n3aE9Lz8Nbc7VigsE,6930
4
+ karakeep_python_api/karakeep_api.py,sha256=SsjrZQtnSgQu2xbC1yGcloUNR-w_yONWdfkoQ4wb5WI,129764
5
+ karakeep_python_api/openapi_reference.json,sha256=uENNNF1bHCuHzJPHQa2-DfqlEOBrLmQ0mFrVnPu9XaA,163271
6
+ karakeep_python_api-1.9.1.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
7
+ karakeep_python_api-1.9.1.dist-info/METADATA,sha256=ga2rJoXIOmYKtYSHrh4kmrspFuQoiIStB_7ozFwIZc4,17687
8
+ karakeep_python_api-1.9.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
9
+ karakeep_python_api-1.9.1.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
10
+ karakeep_python_api-1.9.1.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
11
+ karakeep_python_api-1.9.1.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,,