karakeep-python-api 1.8.0__tar.gz → 1.9.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. {karakeep_python_api-1.8.0/karakeep_python_api.egg-info → karakeep_python_api-1.9.1}/PKG-INFO +7 -2
  2. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/README.md +6 -1
  3. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api/__init__.py +7 -1
  4. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api/__main__.py +21 -8
  5. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api/datatypes.py +53 -6
  6. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api/karakeep_api.py +356 -79
  7. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api/openapi_reference.json +379 -8
  8. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1/karakeep_python_api.egg-info}/PKG-INFO +7 -2
  9. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/setup.py +1 -1
  10. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/tests/test_karakeep_api.py +453 -0
  11. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/LICENSE +0 -0
  12. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/MANIFEST.in +0 -0
  13. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api.egg-info/SOURCES.txt +0 -0
  14. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api.egg-info/dependency_links.txt +0 -0
  15. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api.egg-info/entry_points.txt +0 -0
  16. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api.egg-info/requires.txt +0 -0
  17. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/karakeep_python_api.egg-info/top_level.txt +0 -0
  18. {karakeep_python_api-1.8.0 → karakeep_python_api-1.9.1}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: karakeep_python_api
3
- Version: 1.8.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
@@ -82,6 +82,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
82
82
  | `get_a_single_bookmark` | ✅ | ❌ | |
83
83
  | `delete_a_bookmark` | ✅ | ❌ | |
84
84
  | `update_a_bookmark` | ✅ | ✅ | Tested for title updates. |
85
+ | `get_bookmark_readable_content` | ✅ | ❌ | Chunk merging tested offline; live test reads a text bookmark. |
85
86
  | `summarize_a_bookmark` | ❌ | ❌ | |
86
87
  | `attach_tags_to_a_bookmark` | ✅ | ❌ | |
87
88
  | `detach_tags_from_a_bookmark` | ✅ | ❌ | |
@@ -110,6 +111,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
110
111
  | `update_a_highlight` | ❌ | ❌ | |
111
112
  | `upload_a_new_asset` | ✅ | ❌ | Tested in PDF asset lifecycle test. |
112
113
  | `get_a_single_asset` | ✅ | ❌ | Tested in PDF asset lifecycle test. |
114
+ | `get_asset_signed_url` | ✅ | ❌ | Tested in PDF asset lifecycle test (downloads without an API key). |
113
115
  | `get_current_user_info` | ✅ | ❌ | Pytest: Tested indirectly during client init. CLI not directly tested. |
114
116
  | `get_current_user_stats` | ✅ | ✅ | |
115
117
  | `update_user` | ❌ | ❌ | |
@@ -118,6 +120,9 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
118
120
  | `get_a_single_backup` | ✅ | ❌ | Tested in backup lifecycle test. |
119
121
  | `delete_a_backup` | ✅ | ❌ | Tested in backup lifecycle test. |
120
122
  | `download_a_backup` | ✅ | ❌ | Tested in backup lifecycle test. |
123
+ | `admin_trigger_recrawl` | ❌ | ❌ | Request body construction tested offline only. |
124
+ | `admin_trigger_reindex` | ❌ | ❌ | Request body construction tested offline only. |
125
+ | `admin_trigger_inference` | ❌ | ❌ | Request body construction tested offline only. |
121
126
 
122
127
  ## Installation
123
128
 
@@ -281,4 +286,4 @@ They can be found in the [./community_scripts](https://github.com/thiswillbeyour
281
286
 
282
287
  ---
283
288
 
284
- *This README was generated with assistance from [aider.chat](https://aider.chat).*
289
+ *This README was generated with assistance from [aider.chat](https://aider.chat), and later kept up to date with [Claude Code](https://claude.com/claude-code).*
@@ -50,6 +50,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
50
50
  | `get_a_single_bookmark` | ✅ | ❌ | |
51
51
  | `delete_a_bookmark` | ✅ | ❌ | |
52
52
  | `update_a_bookmark` | ✅ | ✅ | Tested for title updates. |
53
+ | `get_bookmark_readable_content` | ✅ | ❌ | Chunk merging tested offline; live test reads a text bookmark. |
53
54
  | `summarize_a_bookmark` | ❌ | ❌ | |
54
55
  | `attach_tags_to_a_bookmark` | ✅ | ❌ | |
55
56
  | `detach_tags_from_a_bookmark` | ✅ | ❌ | |
@@ -78,6 +79,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
78
79
  | `update_a_highlight` | ❌ | ❌ | |
79
80
  | `upload_a_new_asset` | ✅ | ❌ | Tested in PDF asset lifecycle test. |
80
81
  | `get_a_single_asset` | ✅ | ❌ | Tested in PDF asset lifecycle test. |
82
+ | `get_asset_signed_url` | ✅ | ❌ | Tested in PDF asset lifecycle test (downloads without an API key). |
81
83
  | `get_current_user_info` | ✅ | ❌ | Pytest: Tested indirectly during client init. CLI not directly tested. |
82
84
  | `get_current_user_stats` | ✅ | ✅ | |
83
85
  | `update_user` | ❌ | ❌ | |
@@ -86,6 +88,9 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
86
88
  | `get_a_single_backup` | ✅ | ❌ | Tested in backup lifecycle test. |
87
89
  | `delete_a_backup` | ✅ | ❌ | Tested in backup lifecycle test. |
88
90
  | `download_a_backup` | ✅ | ❌ | Tested in backup lifecycle test. |
91
+ | `admin_trigger_recrawl` | ❌ | ❌ | Request body construction tested offline only. |
92
+ | `admin_trigger_reindex` | ❌ | ❌ | Request body construction tested offline only. |
93
+ | `admin_trigger_inference` | ❌ | ❌ | Request body construction tested offline only. |
89
94
 
90
95
  ## Installation
91
96
 
@@ -249,4 +254,4 @@ They can be found in the [./community_scripts](https://github.com/thiswillbeyour
249
254
 
250
255
  ---
251
256
 
252
- *This README was generated with assistance from [aider.chat](https://aider.chat).*
257
+ *This README was generated with assistance from [aider.chat](https://aider.chat), and later kept up to date with [Claude Code](https://claude.com/claude-code).*
@@ -1,5 +1,10 @@
1
1
  # Import API class and errors directly from the module
2
- from .karakeep_api import 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
@@ -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 is not None:
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 List[T] or Dict[K, V] - expect JSON string
668
- 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):
669
682
  click_type = click.STRING # Expect JSON string
670
683
  # Handle Literal[...] for choices
671
684
  elif origin is Literal:
@@ -5,7 +5,7 @@ The datatype file was originally generated by datamodel-codegen, then refactored
5
5
  from __future__ import annotations
6
6
 
7
7
  from enum import Enum
8
- from typing import List, Optional, Union, Literal
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: List[TagShort]
157
+ tags: list[TagShort]
133
158
  content: Union[
134
159
  ContentTypeLink, ContentTypeText, ContentTypeAsset, ContentTypeUnknown
135
160
  ]
136
- assets: List[BookmarkAsset]
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: List[Bookmark]
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: List[Highlight]
221
+ highlights: list[Highlight]
175
222
  nextCursor: Optional[str] = ""
176
223
 
177
224
 
178
225
  class PaginatedTags(BaseModel):
179
- tags: List[Tag]
226
+ tags: list[Tag]
180
227
  nextCursor: Optional[str] = ""
181
228
 
182
229