EagleWrapper 1.1.1__tar.gz → 2.0.0__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 (45) hide show
  1. eaglewrapper-2.0.0/MANIFEST.in +6 -0
  2. eaglewrapper-2.0.0/PKG-INFO +460 -0
  3. eaglewrapper-2.0.0/README.md +409 -0
  4. eaglewrapper-2.0.0/doc/api-overview.png +0 -0
  5. eaglewrapper-2.0.0/setup.py +67 -0
  6. eaglewrapper-2.0.0/src/EagleWrapper.egg-info/PKG-INFO +460 -0
  7. eaglewrapper-2.0.0/src/EagleWrapper.egg-info/SOURCES.txt +34 -0
  8. eaglewrapper-2.0.0/src/eaglewrapper/__init__.py +20 -0
  9. eaglewrapper-2.0.0/src/eaglewrapper/_apis.py +62 -0
  10. eaglewrapper-2.0.0/src/eaglewrapper/_library.py +65 -0
  11. eaglewrapper-2.0.0/src/eaglewrapper/client.py +158 -0
  12. eaglewrapper-2.0.0/src/eaglewrapper/eagle.py +713 -0
  13. eaglewrapper-2.0.0/src/eaglewrapper/errors.py +55 -0
  14. eaglewrapper-2.0.0/src/eaglewrapper/py.typed +0 -0
  15. eaglewrapper-2.0.0/src/eaglewrapper/v2.py +616 -0
  16. eaglewrapper-2.0.0/tests/__init__.py +0 -0
  17. eaglewrapper-2.0.0/tests/fakes.py +43 -0
  18. eaglewrapper-2.0.0/tests/test_api_requests.py +270 -0
  19. eaglewrapper-2.0.0/tests/test_apis.py +67 -0
  20. eaglewrapper-2.0.0/tests/test_compat.py +96 -0
  21. eaglewrapper-2.0.0/tests/test_connection_options.py +137 -0
  22. eaglewrapper-2.0.0/tests/test_errors.py +107 -0
  23. eaglewrapper-2.0.0/tests/test_library_folder.py +116 -0
  24. eaglewrapper-2.0.0/tests/test_readme.py +36 -0
  25. eaglewrapper-2.0.0/tests/test_v1_additions.py +39 -0
  26. eaglewrapper-2.0.0/tests/test_v2.py +437 -0
  27. EagleWrapper-1.1.1/MANIFEST.in +0 -9
  28. EagleWrapper-1.1.1/PKG-INFO +0 -210
  29. EagleWrapper-1.1.1/README.md +0 -180
  30. EagleWrapper-1.1.1/reinstall.bat +0 -1
  31. EagleWrapper-1.1.1/reinstall.sh +0 -2
  32. EagleWrapper-1.1.1/setup.py +0 -53
  33. EagleWrapper-1.1.1/src/EagleWrapper.egg-info/PKG-INFO +0 -210
  34. EagleWrapper-1.1.1/src/EagleWrapper.egg-info/SOURCES.txt +0 -18
  35. EagleWrapper-1.1.1/src/eaglewrapper/__init__.py +0 -3
  36. EagleWrapper-1.1.1/src/eaglewrapper/eagle.py +0 -688
  37. {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/LICENSE +0 -0
  38. {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/doc/add-from-url.png +0 -0
  39. {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/doc/repo-logo.png +0 -0
  40. {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/pyproject.toml +0 -0
  41. {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/setup.cfg +0 -0
  42. {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/src/EagleWrapper.egg-info/dependency_links.txt +0 -0
  43. {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/src/EagleWrapper.egg-info/requires.txt +0 -0
  44. {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/src/EagleWrapper.egg-info/top_level.txt +0 -0
  45. {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/tests/test_eagle.py +0 -0
@@ -0,0 +1,6 @@
1
+ include pyproject.toml
2
+ include *.md
3
+ include LICENSE
4
+ include src/eaglewrapper/py.typed
5
+ recursive-include tests *.py
6
+ recursive-include doc *.png
@@ -0,0 +1,460 @@
1
+ Metadata-Version: 2.4
2
+ Name: EagleWrapper
3
+ Version: 2.0.0
4
+ Summary: A wrapper for the local HTTP API (V1 and Web API V2) of Eagle, an image management app.
5
+ Home-page: https://github.com/NatLee/eagle-wrapper
6
+ Author: Nat Lee
7
+ Author-email: natlee.work@gmail.com
8
+ Project-URL: Documentation, https://github.com/NatLee/eagle-wrapper
9
+ Project-URL: Bug Reports, https://github.com/NatLee/eagle-wrapper/issues
10
+ Project-URL: Source Code, https://github.com/NatLee/eagle-wrapper
11
+ Project-URL: Official API Documentation, https://api.eagle.cool/
12
+ Project-URL: Eagle Web API V2, https://developer.eagle.cool/web-api
13
+ Keywords: eagle,eagle api,eagle web api,image management,asset management,wrapper
14
+ Classifier: Development Status :: 5 - Production/Stable
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Topic :: Multimedia :: Graphics
17
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.6
20
+ Classifier: Programming Language :: Python :: 3.7
21
+ Classifier: Programming Language :: Python :: 3.8
22
+ Classifier: Programming Language :: Python :: 3.9
23
+ Classifier: Programming Language :: Python :: 3.10
24
+ Classifier: Programming Language :: Python :: 3.11
25
+ Classifier: Programming Language :: Python :: 3.12
26
+ Classifier: Programming Language :: Python :: 3.13
27
+ Classifier: Programming Language :: Python :: 3.14
28
+ Classifier: Programming Language :: Python :: 3 :: Only
29
+ Classifier: License :: OSI Approved :: MIT License
30
+ Classifier: Operating System :: OS Independent
31
+ Requires-Python: >=3.6
32
+ Description-Content-Type: text/markdown
33
+ License-File: LICENSE
34
+ Requires-Dist: requests
35
+ Requires-Dist: loguru
36
+ Provides-Extra: dev
37
+ Requires-Dist: check-manifest; extra == "dev"
38
+ Dynamic: author
39
+ Dynamic: author-email
40
+ Dynamic: classifier
41
+ Dynamic: description
42
+ Dynamic: description-content-type
43
+ Dynamic: home-page
44
+ Dynamic: keywords
45
+ Dynamic: license-file
46
+ Dynamic: project-url
47
+ Dynamic: provides-extra
48
+ Dynamic: requires-dist
49
+ Dynamic: requires-python
50
+ Dynamic: summary
51
+
52
+ <div align="center">
53
+
54
+ <img src="https://raw.githubusercontent.com/NatLee/eagle-wrapper/main/doc/repo-logo.png" alt="Eagle Wrapper" width="560">
55
+
56
+ **Script [Eagle](https://eagle.cool/) from Python: both of its local HTTP APIs, V1 and the new Web API V2.**
57
+
58
+ [![PyPI version](https://img.shields.io/pypi/v/EagleWrapper.svg)](https://pypi.org/project/EagleWrapper/)
59
+ [![Python versions](https://img.shields.io/pypi/pyversions/EagleWrapper.svg)](https://pypi.org/project/EagleWrapper/)
60
+ [![Test](https://github.com/NatLee/eagle-wrapper/actions/workflows/test.yml/badge.svg)](https://github.com/NatLee/eagle-wrapper/actions/workflows/test.yml)
61
+ [![Release](https://github.com/NatLee/eagle-wrapper/actions/workflows/release.yml/badge.svg)](https://github.com/NatLee/eagle-wrapper/actions/workflows/release.yml)
62
+ [![Downloads](https://img.shields.io/pypi/dm/EagleWrapper.svg)](https://pypi.org/project/EagleWrapper/)
63
+ [![License: MIT](https://img.shields.io/pypi/l/EagleWrapper.svg)](https://github.com/NatLee/eagle-wrapper/blob/main/LICENSE)
64
+
65
+ </div>
66
+
67
+ Eagle is a desktop app for collecting and organizing images, videos, fonts and other design references.
68
+ While it is open, it runs a small HTTP server on your computer (port `41595`), and anything that can send
69
+ HTTP requests can add files to it, search it, tag things and manage folders. EagleWrapper turns that server
70
+ into plain Python methods, so a downloader, a tagging script or a backup job is a few lines of code.
71
+ It can also read an Eagle library folder straight from disk when the app is closed.
72
+
73
+ ![How EagleWrapper talks to Eagle](https://raw.githubusercontent.com/NatLee/eagle-wrapper/main/doc/api-overview.png)
74
+
75
+ ## Which Eagle API? (checked November 2026)
76
+
77
+ Eagle has not switched its API off. It now has two, on the same port:
78
+
79
+ | | V1 (legacy) | Web API V2 |
80
+ |---|---|---|
81
+ | Paths | `/api/...` | `/api/v2/...` |
82
+ | Needs | Eagle 1.11 Build 21 or later | Eagle 4.0 Build 21 or later (smart folders and comments: Build 22) |
83
+ | Status | Still documented; Eagle calls it legacy and has announced no end date | Current, much larger |
84
+ | Docs | [api.eagle.cool](https://api.eagle.cool/) | [developer.eagle.cool/web-api](https://developer.eagle.cool/web-api) |
85
+ | In this package | the methods of `Eagle()` | `Eagle().v2` |
86
+
87
+ Calls from the same computer need no token. Calls from another device on your network need the API token from
88
+ Eagle > Preferences > Developer, sent as `?token=...` on every request ([V2 docs: Authentication](https://developer.eagle.cool/web-api/get-started/readme#authentication)).
89
+
90
+ ## Install
91
+
92
+ ```bash
93
+ pip install EagleWrapper
94
+ ```
95
+
96
+ Python 3.6 or later. Eagle must be running for everything except the library-folder reader.
97
+ Web API V2, the connection options and the new exceptions arrived in 1.2.0.
98
+ Which release speaks which Eagle API, and what to pin: see [Versioning](#versioning).
99
+
100
+ ## Quick start
101
+
102
+ ```python
103
+ from eaglewrapper import Eagle
104
+
105
+ eagle = Eagle() # http://localhost:41595
106
+
107
+ # V1: add an image from a URL. Positional arguments: url, name, tags, website, annotation.
108
+ eagle.add_from_url(
109
+ 'https://example.com/bocchi.jpg', 'ぼっち・ざ・ろっく!', ['ぼっち', 'ろっく'],
110
+ 'https://example.com/news/bocchi', 'This is an example ;)')
111
+
112
+ # V2 (Eagle 4.0 Build 21+): full-text search, then walk through every page of a filter.
113
+ if eagle.supports_v2():
114
+ print(eagle.v2.app.info()['version'])
115
+ print(eagle.v2.item.query('ぼっち OR cat')['total'], 'matches')
116
+ for item in eagle.v2.item.iterate(tags=['ろっく'], fields=['id', 'name']):
117
+ print(item['id'], item['name'])
118
+ ```
119
+
120
+ This is what the `add_from_url` call looks like in Eagle:
121
+
122
+ ![add-from-url](https://raw.githubusercontent.com/NatLee/eagle-wrapper/main/doc/add-from-url.png)
123
+
124
+ ## Connecting
125
+
126
+ Everything is optional; with no arguments `Eagle()` talks to `http://localhost:41595` like it always did.
127
+
128
+ ```python
129
+ import requests
130
+ from eaglewrapper import Eagle
131
+
132
+ eagle = Eagle(
133
+ base_url='http://192.168.1.20:41595', # Eagle on another computer (default: domain + port)
134
+ token='f366c476-7533-4f33-b454-2bc720a1d0ea', # or set EAGLE_API_TOKEN instead of writing it here
135
+ timeout=30, # seconds; the default waits as long as Eagle needs
136
+ session=requests.Session(), # reuse connections across many calls
137
+ raise_errors=True, # V1 methods raise EagleAPIError instead of returning False/None
138
+ )
139
+ print(eagle.host, eagle.list_folders() is not None)
140
+ ```
141
+
142
+ `Eagle('http://localhost', 41595)` (the 1.1.1 way) still works. `eagle.v2` uses the same settings.
143
+ You can also use V2 on its own with `EagleV2(base_url, token=...)`.
144
+
145
+ ## When something goes wrong
146
+
147
+ | What happened | What you get | Also catchable as |
148
+ |---|---|---|
149
+ | Eagle is closed, or the host or port is wrong | `EagleConnectionError` with a hint | `requests.ConnectionError` (what 1.1.1 raised) |
150
+ | The reply is not JSON, e.g. a V2 call on an Eagle older than 4.0 Build 21 | `EagleResponseError` | `ValueError` (what 1.1.1 raised) |
151
+ | Eagle answered `{"status": "error"}` to a **V2** call | `EagleAPIError` (`.message`, `.endpoint`, `.status_code`, `.payload`) | `EagleError` |
152
+ | Eagle answered `{"status": "error"}` to a **V1** call | `False` or `None` as in 1.1.1, plus a logged warning; with `raise_errors=True`, `EagleAPIError` | |
153
+
154
+ All of them are subclasses of `EagleError`. `update_item` has always raised on failure and still does.
155
+
156
+ ```python
157
+ from eaglewrapper import Eagle, EagleAPIError, EagleConnectionError
158
+
159
+ try:
160
+ Eagle().v2.tag.merge('photograph', 'photography')
161
+ except EagleConnectionError:
162
+ print('Is Eagle open?')
163
+ except EagleAPIError as e:
164
+ print('Eagle said no:', e.message)
165
+ ```
166
+
167
+ ## Web API V2 reference
168
+
169
+ `eagle.v2` is grouped like the [official docs](https://developer.eagle.cool/web-api): `POST /api/v2/tag/merge`
170
+ is `eagle.v2.tag.merge(...)`. Methods return the `data` part of Eagle's reply. Filters and options are
171
+ keyword arguments in snake_case (`is_untagged=True` is sent as `isUntagged`); arguments you leave out are not sent.
172
+
173
+ List endpoints are paginated: you get `{'data': [...], 'total': 1250, 'offset': 0, 'limit': 50}`. Eagle returns
174
+ 50 rows unless you pass `limit` (maximum 1000). The `iterate...` helpers fetch page after page for you.
175
+
176
+ | Area | Method | Endpoint |
177
+ |---|---|---|
178
+ | **Item** | `item.get(tags=, folders=, keywords=, ext=, rating=, shape=, is_untagged=, fields=, offset=, limit=, ...)` | `POST item/get` |
179
+ | | `item.iterate(page_size=200, **filters)` · `item.get_by_id(item_id)` | `item/get` |
180
+ | | `item.query('(cat OR dog) -cartoon', limit=)` · `item.iterate_query(query)` | `POST item/query` |
181
+ | | `item.count_all()` | `GET item/countAll` |
182
+ | | `item.add(url= \| path= \| base64= \| bookmark_url=, name=, tags=, folders=, annotation=, website=)` → new ID | `POST item/add` |
183
+ | | `item.add_many([{'url': ...}, {'path': ...}])` → new IDs (up to 1000) | `POST item/add` |
184
+ | | `item.update(item_id, name=, tags=, folders=, annotation=, url=, star=, is_deleted=, ...)` | `POST item/update` |
185
+ | | `item.set_custom_thumbnail(item_id, file_path)` · `item.refresh_thumbnail(item_id)` | `POST item/...` |
186
+ | | `item.get_comments` · `add_comment` · `update_comment` · `remove_comment` (Build 22) | `item/...Comment(s)` |
187
+ | **Folder** | `folder.get(folder_id=, folder_ids=, is_selected=, is_recent=)` · `folder.iterate()` | `POST folder/get` |
188
+ | | `folder.create(name, description=, parent=)` | `POST folder/create` |
189
+ | | `folder.update(folder_id, name=, description=, tags=, icon_color=, parent=, move_to_root=)` | `POST folder/update` |
190
+ | **Smart folder** (Build 22) | `smart_folder.get` · `create(name, conditions)` · `update` · `remove` · `get_items(id)` · `get_rules()` | `smartFolder/...` |
191
+ | **Tag** | `tag.get(name=)` · `tag.iterate()` · `tag.get_recent()` · `tag.get_starred()` | `tag/get...` |
192
+ | | `tag.rename(original_name, new_name)` · `tag.merge(source, target)` | `POST tag/update`, `tag/merge` |
193
+ | **Tag group** | `tag_group.get` · `create(name, tags)` · `update(id, name, tags)` · `remove` · `add_tags` · `remove_tags` | `tagGroup/...` |
194
+ | **Library** | `library.info()` · `library.history()` · `library.switch(path)` · `library.icon(path)` → bytes | `library/...` |
195
+ | **App** | `app.info()` | `GET app/info` |
196
+ | **AI search** | `ai_search.is_installed()` · `is_ready()` · `get_sync_status()` · ... | `GET aiSearch/...` |
197
+ | | `ai_search.search_by_text('an orange cat', limit=)` · `search_by_base64` · `search_by_item_id` | `POST aiSearch/searchBy...` |
198
+ | **Anything else** | `v2.request('GET', 'item/countAll')` for endpoints added after this release | any |
199
+
200
+ ```python
201
+ from eaglewrapper import Eagle
202
+
203
+ v2 = Eagle().v2
204
+ new_id = v2.item.add(url='https://example.com/cat.jpg', name='Cat', tags=['cat'])
205
+ v2.item.update(new_id, star=5, annotation='Good cat')
206
+ folder = v2.folder.create('Cats')
207
+ v2.item.update(new_id, folders=[folder['id']])
208
+ for tag in v2.tag.iterate(name='ca'):
209
+ print(tag['name'], tag['count'])
210
+ if v2.ai_search.is_ready():
211
+ for hit in v2.ai_search.search_by_text('an orange cat', limit=5)['results']:
212
+ print(round(hit['score'], 2), hit['item']['name'])
213
+ ```
214
+
215
+ AI search needs Eagle's [AI Search plugin](https://eagle.cool/support/article/ai-search). Smart folders and comments
216
+ need Eagle 4.0 Build 22. On an older Eagle those calls fail with `EagleResponseError` or `EagleAPIError`.
217
+
218
+ ## V1 (legacy) reference
219
+
220
+ These are the methods of 1.1.1, unchanged, plus `star`, `get_library_icon` and `supports_v2`. Every endpoint has its own page in the [V1 docs](https://api.eagle.cool/).
221
+
222
+ | Area | Method | Endpoint | Returns |
223
+ |---|---|---|---|
224
+ | **Application** | `get_application_info()` | `GET /api/application/info` | dict |
225
+ | **Item** | `add_from_url(url, name, tags, website, annotation, modification_time, folder_id, headers, star)` | `POST /api/item/addFromURL` | bool |
226
+ | | `add_from_urls(items, folder_id)` | `POST /api/item/addFromURLs` | bool |
227
+ | | `add_from_path(path, name, website, annotation, tags, folder_id)` | `POST /api/item/addFromPath` | Eagle's reply (dict) |
228
+ | | `add_from_paths(items, folder_id)` | `POST /api/item/addFromPaths` | bool |
229
+ | | `add_bookmark(url, name, tags, thumbnail_base64, modification_time, folder_id)` | `POST /api/item/addBookmark` | bool |
230
+ | | `get_item_info(item_id)` | `GET /api/item/info` | dict or None |
231
+ | | `get_thumbnail_path(item_id)` | `GET /api/item/thumbnail` | str or None |
232
+ | | `list_items(limit=200, offset, order_by, keyword, ext, tags, folders)` | `GET /api/item/list` | list |
233
+ | | `get_img_list_info(max_image_number, name_start_filter)` | `GET /api/item/list` | list, filtered by name |
234
+ | | `move_to_trash(item_ids)` | `POST /api/item/moveToTrash` | bool |
235
+ | | `refresh_palette(item_id)` · `refresh_thumbnail(item_id)` | `POST /api/item/refresh...` | bool |
236
+ | | `update_item(item_id, tags, annotation, url, star)` · `set_tag_with_id(item_id, tags)` | `POST /api/item/update` | dict, raises on failure |
237
+ | **Folder** | `create_folder(folder_name, parent_id)` | `POST /api/folder/create` | dict |
238
+ | | `rename_folder(folder_id, new_name)` | `POST /api/folder/rename` | dict |
239
+ | | `update_folder(folder_id, new_name, new_description, new_color)` | `POST /api/folder/update` | dict |
240
+ | | `list_folders()` · `get_recent_folders()` | `GET /api/folder/list`, `listRecent` | list |
241
+ | **Library** | `get_library_info()` | `GET /api/library/info` | dict |
242
+ | | `get_library_history()` | `GET /api/library/history` | list of paths |
243
+ | | `switch_library(library_path)` | `POST /api/library/switch` | bool |
244
+ | | `get_library_icon(library_path)` | `GET /api/library/icon` | bytes or None |
245
+ | **No API** | `get_img_info_from_lib_path(library_path, name_start_filters, max_workers, match)` | reads the library folder | list |
246
+ | **Helpers** | `supports_v2()` · `check_success(response_or_dict)` | | bool |
247
+
248
+ `add_from_path` returns Eagle's whole reply (a dict such as `{'status': 'success'}`), not a bool, because
249
+ 1.1.1 did and scripts may read it. A dict is always truthy, so `if eagle.add_from_path(...)` passes even when Eagle
250
+ refused the file. Check the reply, or let failures raise:
251
+
252
+ ```python
253
+ from eaglewrapper import Eagle, EagleAPIError
254
+
255
+ eagle = Eagle()
256
+ reply = eagle.add_from_path('/path/to/cat.jpg', 'Cat')
257
+ if eagle.check_success(reply): # True only for {'status': 'success', ...}
258
+ print('added')
259
+ else:
260
+ print('Eagle said no:', reply)
261
+
262
+ try:
263
+ Eagle(raise_errors=True).add_from_path('/path/to/cat.jpg', 'Cat')
264
+ except EagleAPIError as e:
265
+ print('Eagle said no:', e.message)
266
+ ```
267
+
268
+ ## Reading a library folder without Eagle
269
+
270
+ An Eagle library is a folder (`My.library`) with one `images/<id>.info/metadata.json` per item.
271
+ `get_img_info_from_lib_path` reads those files directly, which is faster than the API for big libraries and
272
+ works while Eagle is closed. The library's own settings file is skipped.
273
+
274
+ ```python
275
+ from eaglewrapper import Eagle
276
+
277
+ eagle = Eagle()
278
+ library = '/path/to/Design.library'
279
+
280
+ everything = eagle.get_img_info_from_lib_path(library)
281
+ # Names starting with "example" OR "ぼ":
282
+ some = eagle.get_img_info_from_lib_path(library, ['example', 'ぼ'], match='any')
283
+ # Default (as in 1.1.1): a name must start with EVERY prefix.
284
+ both = eagle.get_img_info_from_lib_path(library, ['ex', 'example'])
285
+ print(len(everything), [i['name'] for i in some], [i['name'] for i in both])
286
+ ```
287
+
288
+ ## Upgrading from 1.1.1
289
+
290
+ Nothing to change: every 1.1.1 method keeps its name, its parameters and their order, and sends the same
291
+ requests (a test pins the signatures, and the requests were compared against a fake Eagle). What you may notice:
292
+
293
+ - When Eagle reports a failure, the V1 methods still return `False` or `None`, and now also log a warning.
294
+ - A closed Eagle raises `EagleConnectionError` and a non-JSON reply `EagleResponseError`. They are subclasses of
295
+ the exceptions 1.1.1 let through, so existing `except` clauses still catch them.
296
+ - `get_img_list_info` returns `None` when Eagle fails, where 1.1.1 crashed with a `TypeError` if a filter was given.
297
+ - `get_img_info_from_lib_path` treats a single string filter as one prefix (1.1.1 used every character as a
298
+ prefix), skips items without a name when filtering, and returns files in a stable order.
299
+
300
+ Moving a V1 script to V2 when your Eagle is 4.0 Build 21 or later:
301
+
302
+ | V1 | V2 | Watch out |
303
+ |---|---|---|
304
+ | `add_from_url(url, name, ...)` | `v2.item.add(url=..., name=...)` | folders: `folders=[id]` instead of `folder_id` |
305
+ | `add_from_urls(items)` / `add_from_paths(items)` | `v2.item.add_many(items)` | sources can be mixed; returns the new IDs |
306
+ | `add_from_path(path, name)` | `v2.item.add(path=..., name=...)` | |
307
+ | `add_bookmark(url, name)` | `v2.item.add(bookmark_url=..., name=...)` | |
308
+ | `get_item_info(id)` | `v2.item.get_by_id(id)` | |
309
+ | `list_items(limit=200, ...)` | `v2.item.get(...)` or `v2.item.iterate(...)` | V2 pages default to 50 items |
310
+ | `move_to_trash([id])` | `v2.item.update(id, is_deleted=True)` | one item per call |
311
+ | `update_item(id, tags=...)` | `v2.item.update(id, tags=...)` | V2 can also set `name`, `folders` |
312
+ | `refresh_thumbnail(id)` / `refresh_palette(id)` | `v2.item.refresh_thumbnail(id)` | also refreshes the palette |
313
+ | `create_folder(name, parent_id)` | `v2.folder.create(name, parent=...)` | |
314
+ | `rename_folder` / `update_folder` | `v2.folder.update(id, name=..., icon_color=...)` | can also move folders |
315
+ | `list_folders()` / `get_recent_folders()` | `v2.folder.get()` / `v2.folder.get(is_recent=True)` | paginated |
316
+ | `get_library_info()` / `get_library_history()` | `v2.library.info()` / `v2.library.history()` | history items are `{'name', 'path'}` |
317
+ | `switch_library(path)` / `get_library_icon(path)` | `v2.library.switch(path)` / `v2.library.icon(path)` | |
318
+ | `get_application_info()` | `v2.app.info()` | |
319
+ | `get_thumbnail_path(id)` | none | keep using V1 |
320
+
321
+ ## Versioning
322
+
323
+ The version number follows Eagle's API. The major number is the newest Eagle API generation a release
324
+ speaks: 1 for V1, Eagle's original `/api/` API, and 2 for Web API V2 (`/api/v2/`). A test keeps the two in
325
+ step. Minor releases wrap more
326
+ of that API (often what a new Eagle build added) or add options to the package, and patch releases fix bugs.
327
+ Code that works with one release keeps working with later releases that have the same major number.
328
+ One slip from the early days: 1.1.0 renamed two arguments of 1.0.0 and changed what `add_from_url` and
329
+ `set_tag_with_id` return.
330
+
331
+ Eagle numbers its API only as V1 and V2. Whatever it adds inside a generation is tied to the Eagle build
332
+ that brought it (see the [V1 changelog](https://api.eagle.cool/changelog) and the
333
+ [V2 changelog](https://developer.eagle.cool/web-api/changelog)), so each release says which builds it covers:
334
+
335
+ | EagleWrapper | Eagle APIs | What it wraps |
336
+ |---|---|---|
337
+ | 1.0.0 (April 2023) | V1 | 3 endpoints (add from URL, list items, update item) and the library-folder reader |
338
+ | 1.1.0, 1.1.1 (April 2023) | V1 | all 21 endpoints documented at the time |
339
+ | 1.2.0 (November 2026) | V1 and Web API V2 | V1 up to its last change (Eagle 3.0 Build 23) plus `/api/library/icon`; V2 up to Eagle 4.0 Build 22 (smart folders, comments) |
340
+ | 2.0.0 (November 2026) | V1 and Web API V2 | the same as 1.2.0, plus `SUPPORTED_APIS` (below) |
341
+
342
+ 1.2.0 is the odd one out. It was the first release that speaks Web API V2, but it came out as 1.2.0,
343
+ before this rule was written down, because nothing changed for code written against V1. 2.0.0 puts the
344
+ number back on the rule. It is the 1.2.0 code with this versioning written down and `SUPPORTED_APIS`
345
+ added, so going from 1.2.0 to 2.0.0 needs no change in your code.
346
+
347
+ The installed package knows what it covers:
348
+
349
+ ```python
350
+ import eaglewrapper
351
+
352
+ for api in eaglewrapper.SUPPORTED_APIS:
353
+ print(f'{api.name}: {api.prefix}... needs Eagle {api.since}+, wrapped up to Eagle {api.covered_up_to}')
354
+ ```
355
+
356
+ ```text
357
+ V1: /api/... needs Eagle 1.11 Build 21+, wrapped up to Eagle 3.0 Build 23
358
+ Web API V2: /api/v2/... needs Eagle 4.0 Build 21+, wrapped up to Eagle 4.0 Build 22
359
+ ```
360
+
361
+ To see what your Eagle has, `Eagle().get_application_info()` returns its `version` and `buildVersion`,
362
+ and `Eagle().supports_v2()` says whether Web API V2 is there. Endpoints that Eagle adds after the covered
363
+ build are one call away with `eagle.v2.request('GET', 'section/endpoint')`. So are `item/open`,
364
+ `item/select` and `folder/open`: the V2 changelog lists them, but the docs have no page for them yet, so
365
+ they are not wrapped.
366
+
367
+ What to pin: the major number, `EagleWrapper~=2.0` (that is `>=2.0, <3`). You get fixes and newly
368
+ wrapped endpoints, and you move to another API generation only when you change the pin. The 1.x line gets
369
+ no more releases: if you pinned `~=1.2`, change it to `~=2.0`; nothing else to do. `eagle.v2` needs
370
+ 1.2.0 or later. Scripts that only use the V1 methods run on 1.1.0 and later, but 1.2.0 fixed several bugs
371
+ (see [Upgrading from 1.1.1](#upgrading-from-111)).
372
+
373
+ ## Plugins and related projects
374
+
375
+ Not every job needs a script. A few things worth knowing about before you write one:
376
+
377
+ From Eagle:
378
+
379
+ - [Plugin Center](https://community-en.eagle.cool/plugins): plugins you install inside Eagle. The batch job
380
+ you are about to script may already exist as one.
381
+ - [API Playground](https://developer.eagle.cool/web-api/get-started/playground): with Eagle open, visit
382
+ `http://localhost:41595/api/v2/playground` to try any Web API V2 endpoint from a form and see Eagle's real
383
+ reply before you write the Python call. It works on your real library, so writes there are real too.
384
+ - [Plugin API](https://developer.eagle.cool/plugin-api) and the
385
+ [official plugin examples](https://github.com/eagle-app/eagle-plugin-examples): for code that should run
386
+ inside Eagle (a window, a background service, support for a new file format, an inspector panel) rather
387
+ than talk to it from outside. The examples have one small working plugin per type.
388
+ - [AI Search](https://eagle.cool/support/article/ai-search): Eagle's offline search by description or by
389
+ similar image. `eagle.v2.ai_search` only works with this plugin installed.
390
+ - [Eagle Skill / MCP](https://en.eagle.cool/blog/post/eagle-plugin-mcp-skill): lets an AI agent clean up
391
+ tags, plan folders and rewrite names and descriptions in your library. Worth a look when the hard part is
392
+ deciding what to change, not making the calls.
393
+
394
+ Built on EagleWrapper:
395
+
396
+ - [yande-and-konachan-to-eagle](https://github.com/NatLee/yande-and-konachan-to-eagle): fetches images and
397
+ their tags from yande.re and konachan.com and adds them to Eagle with `add_from_url`. A complete,
398
+ small downloader to copy from.
399
+
400
+ Built something with EagleWrapper? Open an issue or a pull request and it can go on this list.
401
+
402
+ ## Development
403
+
404
+ The tests replace the HTTP calls with mocks, so Eagle does not need to be running.
405
+
406
+ ```bash
407
+ pip install -e . pytest
408
+ pytest tests
409
+ ```
410
+
411
+ The editable install picks up your edits right away. To reinstall a regular copy from the checkout instead
412
+ (what the old `reinstall.sh` and `reinstall.bat` did with the retired `setup.py install`):
413
+
414
+ ```bash
415
+ python -m pip install --force-reinstall .
416
+ ```
417
+
418
+ `tox -e py` runs the same tests plus a check of the source distribution. CI runs them on Linux with
419
+ Python 3.6 to 3.14, and on Windows and macOS with Python 3.14.
420
+
421
+ How the code is laid out (`src/eaglewrapper/`):
422
+
423
+ | File | What it does |
424
+ |---|---|
425
+ | `client.py` | `EagleClient`: builds URLs, adds the token, sends requests, decodes replies, raises the errors |
426
+ | `eagle.py` | `Eagle`: the V1 methods, kept compatible with 1.1.1 |
427
+ | `v2.py` | `EagleV2` and its sections (`item`, `folder`, `tag`, ...), plus pagination |
428
+ | `_library.py` | reads `metadata.json` files from a library folder |
429
+ | `_apis.py` | which Eagle APIs and builds this release covers (`SUPPORTED_APIS`); the code, `setup.py` and the README test read it |
430
+ | `errors.py` | the exceptions |
431
+
432
+ ## Support
433
+
434
+ EagleWrapper is free and kept up in spare time. If it saved you an afternoon, you can buy me a coffee on
435
+ Ko-fi or chip in on Liberapay. Bug reports and pull requests help just as much.
436
+
437
+ [![Ko-fi](https://img.shields.io/badge/Ko--fi-natlee__-FF5E5B?logo=ko-fi&logoColor=white)](https://ko-fi.com/natlee_)
438
+ [![Liberapay](https://img.shields.io/badge/Liberapay-natlee-F6C915?logo=liberapay&logoColor=black)](https://liberapay.com/natlee)
439
+
440
+ ## Contributor
441
+
442
+ <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
443
+ <!-- prettier-ignore-start -->
444
+ <!-- markdownlint-disable -->
445
+ <table>
446
+ <tbody>
447
+ <tr>
448
+ <td align="center"><a href="https://github.com/NatLee"><img src="https://avatars.githubusercontent.com/u/10178964?v=3?s=100" width="100px;" alt="Nat Lee"/><br /><sub><b>Nat Lee</b></sub></a></td>
449
+ </tr>
450
+ </tbody>
451
+ </table>
452
+
453
+ <!-- markdownlint-restore -->
454
+ <!-- prettier-ignore-end -->
455
+
456
+ <!-- ALL-CONTRIBUTORS-LIST:END -->
457
+
458
+ ## License
459
+
460
+ [MIT](LICENSE)