karakeep-python-api 1.9.1__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.
@@ -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):
@@ -211,14 +214,35 @@ 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: list[Highlight]
245
+ highlights: list[HighlightWithBookmark]
222
246
  nextCursor: Optional[str] = ""
223
247
 
224
248
 
@@ -192,7 +192,7 @@ class KarakeepAPI:
192
192
  """
193
193
 
194
194
  # Version reflects the client library version, updated by bumpver
195
- VERSION: str = "1.9.1"
195
+ VERSION: str = "1.10.0"
196
196
 
197
197
  def __init__(
198
198
  self,
@@ -2126,7 +2126,9 @@ class KarakeepAPI:
2126
2126
  cursor: Pagination cursor for the next page (optional).
2127
2127
 
2128
2128
  Returns:
2129
- 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).
2130
2132
  If response validation is disabled, returns the raw API response (dict/list).
2131
2133
 
2132
2134
  Raises:
@@ -2152,6 +2154,8 @@ class KarakeepAPI:
2152
2154
  color: Optional[Literal["yellow", "red", "green", "blue"]] = "yellow",
2153
2155
  text: Optional[str] = None,
2154
2156
  note: Optional[str] = None,
2157
+ prefix: Optional[str] = None,
2158
+ suffix: Optional[str] = None,
2155
2159
  ) -> Union[datatypes.Highlight, dict[str, Any], list[Any]]:
2156
2160
  """
2157
2161
  Create a new highlight on a bookmark. Corresponds to POST /highlights.
@@ -2163,6 +2167,8 @@ class KarakeepAPI:
2163
2167
  color: The color of the highlight ("yellow", "red", "green", "blue"). Default is "yellow".
2164
2168
  text: Optional text content of the highlight.
2165
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.
2166
2172
 
2167
2173
  Returns:
2168
2174
  datatypes.Highlight: The created highlight object.
@@ -2181,6 +2187,13 @@ class KarakeepAPI:
2181
2187
  "text": text,
2182
2188
  "note": note,
2183
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
2184
2197
 
2185
2198
  response_data = self._call("POST", "highlights", data=highlight_data)
2186
2199
 
@@ -48,7 +48,7 @@
48
48
  "url": "{address}/api/v1",
49
49
  "variables": {
50
50
  "address": {
51
- "default": "https://try.karakeep.app",
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/Highlight"
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.9.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.app/api/v1/`).
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,5 +1,5 @@
1
1
  Wheel-Version: 1.0
2
- Generator: setuptools (84.0.0)
2
+ Generator: setuptools (84.2.1)
3
3
  Root-Is-Purelib: true
4
4
  Tag: py3-none-any
5
5
 
@@ -1,11 +0,0 @@
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,,