EagleWrapper 1.1.0__tar.gz → 1.2.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 (39) hide show
  1. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/MANIFEST.in +2 -1
  2. eaglewrapper-1.2.0/PKG-INFO +344 -0
  3. eaglewrapper-1.2.0/README.md +294 -0
  4. eaglewrapper-1.2.0/doc/api-overview.png +0 -0
  5. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/setup.py +7 -2
  6. eaglewrapper-1.2.0/src/EagleWrapper.egg-info/PKG-INFO +344 -0
  7. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/src/EagleWrapper.egg-info/SOURCES.txt +16 -1
  8. eaglewrapper-1.2.0/src/eaglewrapper/__init__.py +17 -0
  9. eaglewrapper-1.2.0/src/eaglewrapper/_library.py +65 -0
  10. eaglewrapper-1.2.0/src/eaglewrapper/client.py +149 -0
  11. eaglewrapper-1.2.0/src/eaglewrapper/eagle.py +721 -0
  12. eaglewrapper-1.2.0/src/eaglewrapper/errors.py +55 -0
  13. eaglewrapper-1.2.0/src/eaglewrapper/py.typed +0 -0
  14. eaglewrapper-1.2.0/src/eaglewrapper/v2.py +615 -0
  15. eaglewrapper-1.2.0/tests/__init__.py +0 -0
  16. eaglewrapper-1.2.0/tests/fakes.py +40 -0
  17. eaglewrapper-1.2.0/tests/test_api_requests.py +277 -0
  18. eaglewrapper-1.2.0/tests/test_compat.py +96 -0
  19. eaglewrapper-1.2.0/tests/test_connection_options.py +137 -0
  20. eaglewrapper-1.2.0/tests/test_errors.py +107 -0
  21. eaglewrapper-1.2.0/tests/test_library_folder.py +116 -0
  22. eaglewrapper-1.2.0/tests/test_v1_additions.py +39 -0
  23. eaglewrapper-1.2.0/tests/test_v2.py +423 -0
  24. EagleWrapper-1.1.0/PKG-INFO +0 -210
  25. EagleWrapper-1.1.0/README.md +0 -180
  26. EagleWrapper-1.1.0/src/EagleWrapper.egg-info/PKG-INFO +0 -210
  27. EagleWrapper-1.1.0/src/eaglewrapper/__init__.py +0 -3
  28. EagleWrapper-1.1.0/src/eaglewrapper/eagle.py +0 -688
  29. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/LICENSE +0 -0
  30. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/doc/add-from-url.png +0 -0
  31. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/doc/repo-logo.png +0 -0
  32. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/pyproject.toml +0 -0
  33. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/reinstall.bat +0 -0
  34. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/reinstall.sh +0 -0
  35. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/setup.cfg +0 -0
  36. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/src/EagleWrapper.egg-info/dependency_links.txt +0 -0
  37. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/src/EagleWrapper.egg-info/requires.txt +0 -0
  38. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/src/EagleWrapper.egg-info/top_level.txt +0 -0
  39. {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/tests/test_eagle.py +0 -0
@@ -3,7 +3,8 @@ include *.md
3
3
  include *.sh
4
4
  include *.bat
5
5
  include LICENSE
6
+ include src/eaglewrapper/py.typed
6
7
  recursive-include test *.py
7
- recursive-include tests test*.py
8
+ recursive-include tests *.py
8
9
  recursive-include doc *.png
9
10
  recursive-include doc *.jpg
@@ -0,0 +1,344 @@
1
+ Metadata-Version: 2.4
2
+ Name: EagleWrapper
3
+ Version: 1.2.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 :: Software Development :: Build Tools
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.6
19
+ Classifier: Programming Language :: Python :: 3.7
20
+ Classifier: Programming Language :: Python :: 3.8
21
+ Classifier: Programming Language :: Python :: 3.9
22
+ Classifier: Programming Language :: Python :: 3.10
23
+ Classifier: Programming Language :: Python :: 3.11
24
+ Classifier: Programming Language :: Python :: 3.12
25
+ Classifier: Programming Language :: Python :: 3.13
26
+ Classifier: Programming Language :: Python :: 3.14
27
+ Classifier: Programming Language :: Python :: 3 :: Only
28
+ Classifier: License :: OSI Approved :: MIT License
29
+ Classifier: Operating System :: OS Independent
30
+ Requires-Python: >=3.6
31
+ Description-Content-Type: text/markdown
32
+ License-File: LICENSE
33
+ Requires-Dist: requests
34
+ Requires-Dist: loguru
35
+ Provides-Extra: dev
36
+ Requires-Dist: check-manifest; extra == "dev"
37
+ Dynamic: author
38
+ Dynamic: author-email
39
+ Dynamic: classifier
40
+ Dynamic: description
41
+ Dynamic: description-content-type
42
+ Dynamic: home-page
43
+ Dynamic: keywords
44
+ Dynamic: license-file
45
+ Dynamic: project-url
46
+ Dynamic: provides-extra
47
+ Dynamic: requires-dist
48
+ Dynamic: requires-python
49
+ Dynamic: summary
50
+
51
+ <div align="center">
52
+
53
+ <img src="https://raw.githubusercontent.com/NatLee/eagle-wrapper/main/doc/repo-logo.png" alt="Eagle Wrapper" width="560">
54
+
55
+ **Script [Eagle](https://eagle.cool/) from Python: both of its local HTTP APIs, V1 and the new Web API V2.**
56
+
57
+ [![PyPI version](https://img.shields.io/pypi/v/EagleWrapper.svg)](https://pypi.org/project/EagleWrapper/)
58
+ [![Python versions](https://img.shields.io/pypi/pyversions/EagleWrapper.svg)](https://pypi.org/project/EagleWrapper/)
59
+ [![Test](https://github.com/NatLee/eagle-wrapper/actions/workflows/test.yml/badge.svg)](https://github.com/NatLee/eagle-wrapper/actions/workflows/test.yml)
60
+ [![Release](https://github.com/NatLee/eagle-wrapper/actions/workflows/release.yml/badge.svg)](https://github.com/NatLee/eagle-wrapper/actions/workflows/release.yml)
61
+ [![Downloads](https://img.shields.io/pypi/dm/EagleWrapper.svg)](https://pypi.org/project/EagleWrapper/)
62
+ [![License: MIT](https://img.shields.io/pypi/l/EagleWrapper.svg)](https://github.com/NatLee/eagle-wrapper/blob/main/LICENSE)
63
+
64
+ </div>
65
+
66
+ Eagle is a desktop app for collecting and organizing images, videos, fonts and other design references.
67
+ While it is open, it runs a small HTTP server on your computer (port `41595`), and anything that can send
68
+ HTTP requests can add files to it, search it, tag things and manage folders. EagleWrapper turns that server
69
+ into plain Python methods, so a downloader, a tagging script or a backup job is a few lines of code.
70
+ It can also read an Eagle library folder straight from disk when the app is closed.
71
+
72
+ ![How EagleWrapper talks to Eagle](https://raw.githubusercontent.com/NatLee/eagle-wrapper/main/doc/api-overview.png)
73
+
74
+ ## Which Eagle API? (checked November 2026)
75
+
76
+ Eagle has not switched its API off. It now has two, on the same port:
77
+
78
+ | | V1 (legacy) | Web API V2 |
79
+ |---|---|---|
80
+ | Paths | `/api/...` | `/api/v2/...` |
81
+ | Needs | Eagle 1.11 Build 21 or later | Eagle 4.0 Build 21 or later (smart folders and comments: Build 22) |
82
+ | Status | Still documented; Eagle calls it legacy and has announced no end date | Current, much larger |
83
+ | Docs | [api.eagle.cool](https://api.eagle.cool/) | [developer.eagle.cool/web-api](https://developer.eagle.cool/web-api) |
84
+ | In this package | the methods of `Eagle()` | `Eagle().v2` |
85
+
86
+ Calls from the same computer need no token. Calls from another device on your network need the API token from
87
+ Eagle > Preferences > Developer, sent as `?token=...` on every request ([V2 docs: Authentication](https://developer.eagle.cool/web-api/get-started/readme#authentication)).
88
+
89
+ ## Install
90
+
91
+ ```bash
92
+ pip install EagleWrapper
93
+ ```
94
+
95
+ Python 3.6 or later. Eagle must be running for everything except the library-folder reader.
96
+ Web API V2, the connection options and the new exceptions arrived in 1.2.0.
97
+
98
+ ## Quick start
99
+
100
+ ```python
101
+ from eaglewrapper import Eagle
102
+
103
+ eagle = Eagle() # http://localhost:41595
104
+
105
+ # V1: add an image from a URL. Positional arguments: url, name, tags, website, annotation.
106
+ eagle.add_from_url(
107
+ 'https://example.com/bocchi.jpg', 'ぼっち・ざ・ろっく!', ['ぼっち', 'ろっく'],
108
+ 'https://example.com/news/bocchi', 'This is an example ;)')
109
+
110
+ # V2 (Eagle 4.0 Build 21+): full-text search, then walk through every page of a filter.
111
+ if eagle.supports_v2():
112
+ print(eagle.v2.app.info()['version'])
113
+ print(eagle.v2.item.query('ぼっち OR cat')['total'], 'matches')
114
+ for item in eagle.v2.item.iterate(tags=['ろっく'], fields=['id', 'name']):
115
+ print(item['id'], item['name'])
116
+ ```
117
+
118
+ This is what the `add_from_url` call looks like in Eagle:
119
+
120
+ ![add-from-url](https://raw.githubusercontent.com/NatLee/eagle-wrapper/main/doc/add-from-url.png)
121
+
122
+ ## Connecting
123
+
124
+ Everything is optional; with no arguments `Eagle()` talks to `http://localhost:41595` like it always did.
125
+
126
+ ```python
127
+ import requests
128
+ from eaglewrapper import Eagle
129
+
130
+ eagle = Eagle(
131
+ base_url='http://192.168.1.20:41595', # Eagle on another computer (default: domain + port)
132
+ token='f366c476-7533-4f33-b454-2bc720a1d0ea', # or set EAGLE_API_TOKEN instead of writing it here
133
+ timeout=30, # seconds; the default waits as long as Eagle needs
134
+ session=requests.Session(), # reuse connections across many calls
135
+ raise_errors=True, # V1 methods raise EagleAPIError instead of returning False/None
136
+ )
137
+ print(eagle.host, eagle.list_folders() is not None)
138
+ ```
139
+
140
+ `Eagle('http://localhost', 41595)` (the 1.1.1 way) still works. `eagle.v2` uses the same settings.
141
+ You can also use V2 on its own with `EagleV2(base_url, token=...)`.
142
+
143
+ ## When something goes wrong
144
+
145
+ | What happened | What you get | Also catchable as |
146
+ |---|---|---|
147
+ | Eagle is closed, or the host or port is wrong | `EagleConnectionError` with a hint | `requests.ConnectionError` (what 1.1.1 raised) |
148
+ | 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) |
149
+ | Eagle answered `{"status": "error"}` to a **V2** call | `EagleAPIError` (`.message`, `.endpoint`, `.status_code`, `.payload`) | `EagleError` |
150
+ | 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` | |
151
+
152
+ All of them are subclasses of `EagleError`. `update_item` has always raised on failure and still does.
153
+
154
+ ```python
155
+ from eaglewrapper import Eagle, EagleAPIError, EagleConnectionError
156
+
157
+ try:
158
+ Eagle().v2.tag.merge('photograph', 'photography')
159
+ except EagleConnectionError:
160
+ print('Is Eagle open?')
161
+ except EagleAPIError as e:
162
+ print('Eagle said no:', e.message)
163
+ ```
164
+
165
+ ## Web API V2 reference
166
+
167
+ `eagle.v2` is grouped like the [official docs](https://developer.eagle.cool/web-api): `POST /api/v2/tag/merge`
168
+ is `eagle.v2.tag.merge(...)`. Methods return the `data` part of Eagle's reply. Filters and options are
169
+ keyword arguments in snake_case (`is_untagged=True` is sent as `isUntagged`); arguments you leave out are not sent.
170
+
171
+ List endpoints are paginated: you get `{'data': [...], 'total': 1250, 'offset': 0, 'limit': 50}`. Eagle returns
172
+ 50 rows unless you pass `limit` (maximum 1000). The `iterate...` helpers fetch page after page for you.
173
+
174
+ | Area | Method | Endpoint |
175
+ |---|---|---|
176
+ | **Item** | `item.get(tags=, folders=, keywords=, ext=, rating=, shape=, is_untagged=, fields=, offset=, limit=, ...)` | `POST item/get` |
177
+ | | `item.iterate(page_size=200, **filters)` · `item.get_by_id(item_id)` | `item/get` |
178
+ | | `item.query('(cat OR dog) -cartoon', limit=)` · `item.iterate_query(query)` | `POST item/query` |
179
+ | | `item.count_all()` | `GET item/countAll` |
180
+ | | `item.add(url= \| path= \| base64= \| bookmark_url=, name=, tags=, folders=, annotation=, website=)` → new ID | `POST item/add` |
181
+ | | `item.add_many([{'url': ...}, {'path': ...}])` → new IDs (up to 1000) | `POST item/add` |
182
+ | | `item.update(item_id, name=, tags=, folders=, annotation=, url=, star=, is_deleted=, ...)` | `POST item/update` |
183
+ | | `item.set_custom_thumbnail(item_id, file_path)` · `item.refresh_thumbnail(item_id)` | `POST item/...` |
184
+ | | `item.get_comments` · `add_comment` · `update_comment` · `remove_comment` (Build 22) | `item/...Comment(s)` |
185
+ | **Folder** | `folder.get(folder_id=, folder_ids=, is_selected=, is_recent=)` · `folder.iterate()` | `POST folder/get` |
186
+ | | `folder.create(name, description=, parent=)` | `POST folder/create` |
187
+ | | `folder.update(folder_id, name=, description=, tags=, icon_color=, parent=, move_to_root=)` | `POST folder/update` |
188
+ | **Smart folder** (Build 22) | `smart_folder.get` · `create(name, conditions)` · `update` · `remove` · `get_items(id)` · `get_rules()` | `smartFolder/...` |
189
+ | **Tag** | `tag.get(name=)` · `tag.iterate()` · `tag.get_recent()` · `tag.get_starred()` | `tag/get...` |
190
+ | | `tag.rename(original_name, new_name)` · `tag.merge(source, target)` | `POST tag/update`, `tag/merge` |
191
+ | **Tag group** | `tag_group.get` · `create(name, tags)` · `update(id, name, tags)` · `remove` · `add_tags` · `remove_tags` | `tagGroup/...` |
192
+ | **Library** | `library.info()` · `library.history()` · `library.switch(path)` · `library.icon(path)` → bytes | `library/...` |
193
+ | **App** | `app.info()` | `GET app/info` |
194
+ | **AI search** | `ai_search.is_installed()` · `is_ready()` · `get_sync_status()` · ... | `GET aiSearch/...` |
195
+ | | `ai_search.search_by_text('an orange cat', limit=)` · `search_by_base64` · `search_by_item_id` | `POST aiSearch/searchBy...` |
196
+ | **Anything else** | `v2.request('GET', 'item/countAll')` for endpoints added after this release | any |
197
+
198
+ ```python
199
+ from eaglewrapper import Eagle
200
+
201
+ v2 = Eagle().v2
202
+ new_id = v2.item.add(url='https://example.com/cat.jpg', name='Cat', tags=['cat'])
203
+ v2.item.update(new_id, star=5, annotation='Good cat')
204
+ folder = v2.folder.create('Cats')
205
+ v2.item.update(new_id, folders=[folder['id']])
206
+ for tag in v2.tag.iterate(name='ca'):
207
+ print(tag['name'], tag['count'])
208
+ if v2.ai_search.is_ready():
209
+ for hit in v2.ai_search.search_by_text('an orange cat', limit=5)['results']:
210
+ print(round(hit['score'], 2), hit['item']['name'])
211
+ ```
212
+
213
+ AI search needs Eagle's [AI Search plugin](https://eagle.cool/support/article/ai-search). Smart folders and comments
214
+ need Eagle 4.0 Build 22. On an older Eagle those calls fail with `EagleResponseError` or `EagleAPIError`.
215
+
216
+ ## V1 (legacy) reference
217
+
218
+ 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/).
219
+
220
+ | Area | Method | Endpoint | Returns |
221
+ |---|---|---|---|
222
+ | **Application** | `get_application_info()` | `GET /api/application/info` | dict |
223
+ | **Item** | `add_from_url(url, name, tags, website, annotation, modification_time, folder_id, headers, star)` | `POST /api/item/addFromURL` | bool |
224
+ | | `add_from_urls(items, folder_id)` | `POST /api/item/addFromURLs` | bool |
225
+ | | `add_from_path(path, name, website, annotation, tags, folder_id)` | `POST /api/item/addFromPath` | Eagle's reply (dict) |
226
+ | | `add_from_paths(items, folder_id)` | `POST /api/item/addFromPaths` | bool |
227
+ | | `add_bookmark(url, name, tags, thumbnail_base64, modification_time, folder_id)` | `POST /api/item/addBookmark` | bool |
228
+ | | `get_item_info(item_id)` | `GET /api/item/info` | dict or None |
229
+ | | `get_thumbnail_path(item_id)` | `GET /api/item/thumbnail` | str or None |
230
+ | | `list_items(limit=200, offset, order_by, keyword, ext, tags, folders)` | `GET /api/item/list` | list |
231
+ | | `get_img_list_info(max_image_number, name_start_filter)` | `GET /api/item/list` | list, filtered by name |
232
+ | | `move_to_trash(item_ids)` | `POST /api/item/moveToTrash` | bool |
233
+ | | `refresh_palette(item_id)` · `refresh_thumbnail(item_id)` | `POST /api/item/refresh...` | bool |
234
+ | | `update_item(item_id, tags, annotation, url, star)` · `set_tag_with_id(item_id, tags)` | `POST /api/item/update` | dict, raises on failure |
235
+ | **Folder** | `create_folder(folder_name, parent_id)` | `POST /api/folder/create` | dict |
236
+ | | `rename_folder(folder_id, new_name)` | `POST /api/folder/rename` | dict |
237
+ | | `update_folder(folder_id, new_name, new_description, new_color)` | `POST /api/folder/update` | dict |
238
+ | | `list_folders()` · `get_recent_folders()` | `GET /api/folder/list`, `listRecent` | list |
239
+ | **Library** | `get_library_info()` | `GET /api/library/info` | dict |
240
+ | | `get_library_history()` | `GET /api/library/history` | list of paths |
241
+ | | `switch_library(library_path)` | `POST /api/library/switch` | bool |
242
+ | | `get_library_icon(library_path)` | `GET /api/library/icon` | bytes or None |
243
+ | **No API** | `get_img_info_from_lib_path(library_path, name_start_filters, max_workers, match)` | reads the library folder | list |
244
+ | **Helpers** | `supports_v2()` · `check_success(response_or_dict)` | | bool |
245
+
246
+ `add_from_path` returns Eagle's whole reply, not a bool, because 1.1.1 did. A dict is always truthy, so check
247
+ `eagle.check_success(reply)` (or use `raise_errors=True`) instead of `if eagle.add_from_path(...)`.
248
+
249
+ ## Reading a library folder without Eagle
250
+
251
+ An Eagle library is a folder (`My.library`) with one `images/<id>.info/metadata.json` per item.
252
+ `get_img_info_from_lib_path` reads those files directly, which is faster than the API for big libraries and
253
+ works while Eagle is closed. The library's own settings file is skipped.
254
+
255
+ ```python
256
+ from eaglewrapper import Eagle
257
+
258
+ eagle = Eagle()
259
+ library = '/path/to/Design.library'
260
+
261
+ everything = eagle.get_img_info_from_lib_path(library)
262
+ # Names starting with "example" OR "ぼ":
263
+ some = eagle.get_img_info_from_lib_path(library, ['example', 'ぼ'], match='any')
264
+ # Default (as in 1.1.1): a name must start with EVERY prefix.
265
+ both = eagle.get_img_info_from_lib_path(library, ['ex', 'example'])
266
+ print(len(everything), [i['name'] for i in some], [i['name'] for i in both])
267
+ ```
268
+
269
+ ## Upgrading from 1.1.1
270
+
271
+ Nothing to change: every 1.1.1 method keeps its name, its parameters and their order, and sends the same
272
+ requests (a test pins the signatures, and the requests were compared against a fake Eagle). What you may notice:
273
+
274
+ - When Eagle reports a failure, the V1 methods still return `False` or `None`, and now also log a warning.
275
+ - A closed Eagle raises `EagleConnectionError` and a non-JSON reply `EagleResponseError`. They are subclasses of
276
+ the exceptions 1.1.1 let through, so existing `except` clauses still catch them.
277
+ - `get_img_list_info` returns `None` when Eagle fails, where 1.1.1 crashed with a `TypeError` if a filter was given.
278
+ - `get_img_info_from_lib_path` treats a single string filter as one prefix (1.1.1 used every character as a
279
+ prefix), skips items without a name when filtering, and returns files in a stable order.
280
+
281
+ Moving a V1 script to V2 when your Eagle is 4.0 Build 21 or later:
282
+
283
+ | V1 | V2 | Watch out |
284
+ |---|---|---|
285
+ | `add_from_url(url, name, ...)` | `v2.item.add(url=..., name=...)` | folders: `folders=[id]` instead of `folder_id` |
286
+ | `add_from_urls(items)` / `add_from_paths(items)` | `v2.item.add_many(items)` | sources can be mixed; returns the new IDs |
287
+ | `add_from_path(path, name)` | `v2.item.add(path=..., name=...)` | |
288
+ | `add_bookmark(url, name)` | `v2.item.add(bookmark_url=..., name=...)` | |
289
+ | `get_item_info(id)` | `v2.item.get_by_id(id)` | |
290
+ | `list_items(limit=200, ...)` | `v2.item.get(...)` or `v2.item.iterate(...)` | V2 pages default to 50 items |
291
+ | `move_to_trash([id])` | `v2.item.update(id, is_deleted=True)` | one item per call |
292
+ | `update_item(id, tags=...)` | `v2.item.update(id, tags=...)` | V2 can also set `name`, `folders` |
293
+ | `refresh_thumbnail(id)` / `refresh_palette(id)` | `v2.item.refresh_thumbnail(id)` | also refreshes the palette |
294
+ | `create_folder(name, parent_id)` | `v2.folder.create(name, parent=...)` | |
295
+ | `rename_folder` / `update_folder` | `v2.folder.update(id, name=..., icon_color=...)` | can also move folders |
296
+ | `list_folders()` / `get_recent_folders()` | `v2.folder.get()` / `v2.folder.get(is_recent=True)` | paginated |
297
+ | `get_library_info()` / `get_library_history()` | `v2.library.info()` / `v2.library.history()` | history items are `{'name', 'path'}` |
298
+ | `switch_library(path)` / `get_library_icon(path)` | `v2.library.switch(path)` / `v2.library.icon(path)` | |
299
+ | `get_application_info()` | `v2.app.info()` | |
300
+ | `get_thumbnail_path(id)` | none | keep using V1 |
301
+
302
+ ## Development
303
+
304
+ The tests replace the HTTP calls with mocks, so Eagle does not need to be running.
305
+
306
+ ```bash
307
+ pip install -e . pytest
308
+ pytest tests
309
+ ```
310
+
311
+ `tox -e py` runs the same tests plus a check of the source distribution. CI runs them on Linux with
312
+ Python 3.6 to 3.14, and on Windows and macOS with Python 3.14.
313
+
314
+ How the code is laid out (`src/eaglewrapper/`):
315
+
316
+ | File | What it does |
317
+ |---|---|
318
+ | `client.py` | `EagleClient`: builds URLs, adds the token, sends requests, decodes replies, raises the errors |
319
+ | `eagle.py` | `Eagle`: the V1 methods, kept compatible with 1.1.1 |
320
+ | `v2.py` | `EagleV2` and its sections (`item`, `folder`, `tag`, ...), plus pagination |
321
+ | `_library.py` | reads `metadata.json` files from a library folder |
322
+ | `errors.py` | the exceptions |
323
+
324
+ ## Contributor
325
+
326
+ <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
327
+ <!-- prettier-ignore-start -->
328
+ <!-- markdownlint-disable -->
329
+ <table>
330
+ <tbody>
331
+ <tr>
332
+ <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>
333
+ </tr>
334
+ </tbody>
335
+ </table>
336
+
337
+ <!-- markdownlint-restore -->
338
+ <!-- prettier-ignore-end -->
339
+
340
+ <!-- ALL-CONTRIBUTORS-LIST:END -->
341
+
342
+ ## License
343
+
344
+ [MIT](LICENSE)
@@ -0,0 +1,294 @@
1
+ <div align="center">
2
+
3
+ <img src="https://raw.githubusercontent.com/NatLee/eagle-wrapper/main/doc/repo-logo.png" alt="Eagle Wrapper" width="560">
4
+
5
+ **Script [Eagle](https://eagle.cool/) from Python: both of its local HTTP APIs, V1 and the new Web API V2.**
6
+
7
+ [![PyPI version](https://img.shields.io/pypi/v/EagleWrapper.svg)](https://pypi.org/project/EagleWrapper/)
8
+ [![Python versions](https://img.shields.io/pypi/pyversions/EagleWrapper.svg)](https://pypi.org/project/EagleWrapper/)
9
+ [![Test](https://github.com/NatLee/eagle-wrapper/actions/workflows/test.yml/badge.svg)](https://github.com/NatLee/eagle-wrapper/actions/workflows/test.yml)
10
+ [![Release](https://github.com/NatLee/eagle-wrapper/actions/workflows/release.yml/badge.svg)](https://github.com/NatLee/eagle-wrapper/actions/workflows/release.yml)
11
+ [![Downloads](https://img.shields.io/pypi/dm/EagleWrapper.svg)](https://pypi.org/project/EagleWrapper/)
12
+ [![License: MIT](https://img.shields.io/pypi/l/EagleWrapper.svg)](https://github.com/NatLee/eagle-wrapper/blob/main/LICENSE)
13
+
14
+ </div>
15
+
16
+ Eagle is a desktop app for collecting and organizing images, videos, fonts and other design references.
17
+ While it is open, it runs a small HTTP server on your computer (port `41595`), and anything that can send
18
+ HTTP requests can add files to it, search it, tag things and manage folders. EagleWrapper turns that server
19
+ into plain Python methods, so a downloader, a tagging script or a backup job is a few lines of code.
20
+ It can also read an Eagle library folder straight from disk when the app is closed.
21
+
22
+ ![How EagleWrapper talks to Eagle](https://raw.githubusercontent.com/NatLee/eagle-wrapper/main/doc/api-overview.png)
23
+
24
+ ## Which Eagle API? (checked November 2026)
25
+
26
+ Eagle has not switched its API off. It now has two, on the same port:
27
+
28
+ | | V1 (legacy) | Web API V2 |
29
+ |---|---|---|
30
+ | Paths | `/api/...` | `/api/v2/...` |
31
+ | Needs | Eagle 1.11 Build 21 or later | Eagle 4.0 Build 21 or later (smart folders and comments: Build 22) |
32
+ | Status | Still documented; Eagle calls it legacy and has announced no end date | Current, much larger |
33
+ | Docs | [api.eagle.cool](https://api.eagle.cool/) | [developer.eagle.cool/web-api](https://developer.eagle.cool/web-api) |
34
+ | In this package | the methods of `Eagle()` | `Eagle().v2` |
35
+
36
+ Calls from the same computer need no token. Calls from another device on your network need the API token from
37
+ Eagle > Preferences > Developer, sent as `?token=...` on every request ([V2 docs: Authentication](https://developer.eagle.cool/web-api/get-started/readme#authentication)).
38
+
39
+ ## Install
40
+
41
+ ```bash
42
+ pip install EagleWrapper
43
+ ```
44
+
45
+ Python 3.6 or later. Eagle must be running for everything except the library-folder reader.
46
+ Web API V2, the connection options and the new exceptions arrived in 1.2.0.
47
+
48
+ ## Quick start
49
+
50
+ ```python
51
+ from eaglewrapper import Eagle
52
+
53
+ eagle = Eagle() # http://localhost:41595
54
+
55
+ # V1: add an image from a URL. Positional arguments: url, name, tags, website, annotation.
56
+ eagle.add_from_url(
57
+ 'https://example.com/bocchi.jpg', 'ぼっち・ざ・ろっく!', ['ぼっち', 'ろっく'],
58
+ 'https://example.com/news/bocchi', 'This is an example ;)')
59
+
60
+ # V2 (Eagle 4.0 Build 21+): full-text search, then walk through every page of a filter.
61
+ if eagle.supports_v2():
62
+ print(eagle.v2.app.info()['version'])
63
+ print(eagle.v2.item.query('ぼっち OR cat')['total'], 'matches')
64
+ for item in eagle.v2.item.iterate(tags=['ろっく'], fields=['id', 'name']):
65
+ print(item['id'], item['name'])
66
+ ```
67
+
68
+ This is what the `add_from_url` call looks like in Eagle:
69
+
70
+ ![add-from-url](https://raw.githubusercontent.com/NatLee/eagle-wrapper/main/doc/add-from-url.png)
71
+
72
+ ## Connecting
73
+
74
+ Everything is optional; with no arguments `Eagle()` talks to `http://localhost:41595` like it always did.
75
+
76
+ ```python
77
+ import requests
78
+ from eaglewrapper import Eagle
79
+
80
+ eagle = Eagle(
81
+ base_url='http://192.168.1.20:41595', # Eagle on another computer (default: domain + port)
82
+ token='f366c476-7533-4f33-b454-2bc720a1d0ea', # or set EAGLE_API_TOKEN instead of writing it here
83
+ timeout=30, # seconds; the default waits as long as Eagle needs
84
+ session=requests.Session(), # reuse connections across many calls
85
+ raise_errors=True, # V1 methods raise EagleAPIError instead of returning False/None
86
+ )
87
+ print(eagle.host, eagle.list_folders() is not None)
88
+ ```
89
+
90
+ `Eagle('http://localhost', 41595)` (the 1.1.1 way) still works. `eagle.v2` uses the same settings.
91
+ You can also use V2 on its own with `EagleV2(base_url, token=...)`.
92
+
93
+ ## When something goes wrong
94
+
95
+ | What happened | What you get | Also catchable as |
96
+ |---|---|---|
97
+ | Eagle is closed, or the host or port is wrong | `EagleConnectionError` with a hint | `requests.ConnectionError` (what 1.1.1 raised) |
98
+ | 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) |
99
+ | Eagle answered `{"status": "error"}` to a **V2** call | `EagleAPIError` (`.message`, `.endpoint`, `.status_code`, `.payload`) | `EagleError` |
100
+ | 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` | |
101
+
102
+ All of them are subclasses of `EagleError`. `update_item` has always raised on failure and still does.
103
+
104
+ ```python
105
+ from eaglewrapper import Eagle, EagleAPIError, EagleConnectionError
106
+
107
+ try:
108
+ Eagle().v2.tag.merge('photograph', 'photography')
109
+ except EagleConnectionError:
110
+ print('Is Eagle open?')
111
+ except EagleAPIError as e:
112
+ print('Eagle said no:', e.message)
113
+ ```
114
+
115
+ ## Web API V2 reference
116
+
117
+ `eagle.v2` is grouped like the [official docs](https://developer.eagle.cool/web-api): `POST /api/v2/tag/merge`
118
+ is `eagle.v2.tag.merge(...)`. Methods return the `data` part of Eagle's reply. Filters and options are
119
+ keyword arguments in snake_case (`is_untagged=True` is sent as `isUntagged`); arguments you leave out are not sent.
120
+
121
+ List endpoints are paginated: you get `{'data': [...], 'total': 1250, 'offset': 0, 'limit': 50}`. Eagle returns
122
+ 50 rows unless you pass `limit` (maximum 1000). The `iterate...` helpers fetch page after page for you.
123
+
124
+ | Area | Method | Endpoint |
125
+ |---|---|---|
126
+ | **Item** | `item.get(tags=, folders=, keywords=, ext=, rating=, shape=, is_untagged=, fields=, offset=, limit=, ...)` | `POST item/get` |
127
+ | | `item.iterate(page_size=200, **filters)` · `item.get_by_id(item_id)` | `item/get` |
128
+ | | `item.query('(cat OR dog) -cartoon', limit=)` · `item.iterate_query(query)` | `POST item/query` |
129
+ | | `item.count_all()` | `GET item/countAll` |
130
+ | | `item.add(url= \| path= \| base64= \| bookmark_url=, name=, tags=, folders=, annotation=, website=)` → new ID | `POST item/add` |
131
+ | | `item.add_many([{'url': ...}, {'path': ...}])` → new IDs (up to 1000) | `POST item/add` |
132
+ | | `item.update(item_id, name=, tags=, folders=, annotation=, url=, star=, is_deleted=, ...)` | `POST item/update` |
133
+ | | `item.set_custom_thumbnail(item_id, file_path)` · `item.refresh_thumbnail(item_id)` | `POST item/...` |
134
+ | | `item.get_comments` · `add_comment` · `update_comment` · `remove_comment` (Build 22) | `item/...Comment(s)` |
135
+ | **Folder** | `folder.get(folder_id=, folder_ids=, is_selected=, is_recent=)` · `folder.iterate()` | `POST folder/get` |
136
+ | | `folder.create(name, description=, parent=)` | `POST folder/create` |
137
+ | | `folder.update(folder_id, name=, description=, tags=, icon_color=, parent=, move_to_root=)` | `POST folder/update` |
138
+ | **Smart folder** (Build 22) | `smart_folder.get` · `create(name, conditions)` · `update` · `remove` · `get_items(id)` · `get_rules()` | `smartFolder/...` |
139
+ | **Tag** | `tag.get(name=)` · `tag.iterate()` · `tag.get_recent()` · `tag.get_starred()` | `tag/get...` |
140
+ | | `tag.rename(original_name, new_name)` · `tag.merge(source, target)` | `POST tag/update`, `tag/merge` |
141
+ | **Tag group** | `tag_group.get` · `create(name, tags)` · `update(id, name, tags)` · `remove` · `add_tags` · `remove_tags` | `tagGroup/...` |
142
+ | **Library** | `library.info()` · `library.history()` · `library.switch(path)` · `library.icon(path)` → bytes | `library/...` |
143
+ | **App** | `app.info()` | `GET app/info` |
144
+ | **AI search** | `ai_search.is_installed()` · `is_ready()` · `get_sync_status()` · ... | `GET aiSearch/...` |
145
+ | | `ai_search.search_by_text('an orange cat', limit=)` · `search_by_base64` · `search_by_item_id` | `POST aiSearch/searchBy...` |
146
+ | **Anything else** | `v2.request('GET', 'item/countAll')` for endpoints added after this release | any |
147
+
148
+ ```python
149
+ from eaglewrapper import Eagle
150
+
151
+ v2 = Eagle().v2
152
+ new_id = v2.item.add(url='https://example.com/cat.jpg', name='Cat', tags=['cat'])
153
+ v2.item.update(new_id, star=5, annotation='Good cat')
154
+ folder = v2.folder.create('Cats')
155
+ v2.item.update(new_id, folders=[folder['id']])
156
+ for tag in v2.tag.iterate(name='ca'):
157
+ print(tag['name'], tag['count'])
158
+ if v2.ai_search.is_ready():
159
+ for hit in v2.ai_search.search_by_text('an orange cat', limit=5)['results']:
160
+ print(round(hit['score'], 2), hit['item']['name'])
161
+ ```
162
+
163
+ AI search needs Eagle's [AI Search plugin](https://eagle.cool/support/article/ai-search). Smart folders and comments
164
+ need Eagle 4.0 Build 22. On an older Eagle those calls fail with `EagleResponseError` or `EagleAPIError`.
165
+
166
+ ## V1 (legacy) reference
167
+
168
+ 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/).
169
+
170
+ | Area | Method | Endpoint | Returns |
171
+ |---|---|---|---|
172
+ | **Application** | `get_application_info()` | `GET /api/application/info` | dict |
173
+ | **Item** | `add_from_url(url, name, tags, website, annotation, modification_time, folder_id, headers, star)` | `POST /api/item/addFromURL` | bool |
174
+ | | `add_from_urls(items, folder_id)` | `POST /api/item/addFromURLs` | bool |
175
+ | | `add_from_path(path, name, website, annotation, tags, folder_id)` | `POST /api/item/addFromPath` | Eagle's reply (dict) |
176
+ | | `add_from_paths(items, folder_id)` | `POST /api/item/addFromPaths` | bool |
177
+ | | `add_bookmark(url, name, tags, thumbnail_base64, modification_time, folder_id)` | `POST /api/item/addBookmark` | bool |
178
+ | | `get_item_info(item_id)` | `GET /api/item/info` | dict or None |
179
+ | | `get_thumbnail_path(item_id)` | `GET /api/item/thumbnail` | str or None |
180
+ | | `list_items(limit=200, offset, order_by, keyword, ext, tags, folders)` | `GET /api/item/list` | list |
181
+ | | `get_img_list_info(max_image_number, name_start_filter)` | `GET /api/item/list` | list, filtered by name |
182
+ | | `move_to_trash(item_ids)` | `POST /api/item/moveToTrash` | bool |
183
+ | | `refresh_palette(item_id)` · `refresh_thumbnail(item_id)` | `POST /api/item/refresh...` | bool |
184
+ | | `update_item(item_id, tags, annotation, url, star)` · `set_tag_with_id(item_id, tags)` | `POST /api/item/update` | dict, raises on failure |
185
+ | **Folder** | `create_folder(folder_name, parent_id)` | `POST /api/folder/create` | dict |
186
+ | | `rename_folder(folder_id, new_name)` | `POST /api/folder/rename` | dict |
187
+ | | `update_folder(folder_id, new_name, new_description, new_color)` | `POST /api/folder/update` | dict |
188
+ | | `list_folders()` · `get_recent_folders()` | `GET /api/folder/list`, `listRecent` | list |
189
+ | **Library** | `get_library_info()` | `GET /api/library/info` | dict |
190
+ | | `get_library_history()` | `GET /api/library/history` | list of paths |
191
+ | | `switch_library(library_path)` | `POST /api/library/switch` | bool |
192
+ | | `get_library_icon(library_path)` | `GET /api/library/icon` | bytes or None |
193
+ | **No API** | `get_img_info_from_lib_path(library_path, name_start_filters, max_workers, match)` | reads the library folder | list |
194
+ | **Helpers** | `supports_v2()` · `check_success(response_or_dict)` | | bool |
195
+
196
+ `add_from_path` returns Eagle's whole reply, not a bool, because 1.1.1 did. A dict is always truthy, so check
197
+ `eagle.check_success(reply)` (or use `raise_errors=True`) instead of `if eagle.add_from_path(...)`.
198
+
199
+ ## Reading a library folder without Eagle
200
+
201
+ An Eagle library is a folder (`My.library`) with one `images/<id>.info/metadata.json` per item.
202
+ `get_img_info_from_lib_path` reads those files directly, which is faster than the API for big libraries and
203
+ works while Eagle is closed. The library's own settings file is skipped.
204
+
205
+ ```python
206
+ from eaglewrapper import Eagle
207
+
208
+ eagle = Eagle()
209
+ library = '/path/to/Design.library'
210
+
211
+ everything = eagle.get_img_info_from_lib_path(library)
212
+ # Names starting with "example" OR "ぼ":
213
+ some = eagle.get_img_info_from_lib_path(library, ['example', 'ぼ'], match='any')
214
+ # Default (as in 1.1.1): a name must start with EVERY prefix.
215
+ both = eagle.get_img_info_from_lib_path(library, ['ex', 'example'])
216
+ print(len(everything), [i['name'] for i in some], [i['name'] for i in both])
217
+ ```
218
+
219
+ ## Upgrading from 1.1.1
220
+
221
+ Nothing to change: every 1.1.1 method keeps its name, its parameters and their order, and sends the same
222
+ requests (a test pins the signatures, and the requests were compared against a fake Eagle). What you may notice:
223
+
224
+ - When Eagle reports a failure, the V1 methods still return `False` or `None`, and now also log a warning.
225
+ - A closed Eagle raises `EagleConnectionError` and a non-JSON reply `EagleResponseError`. They are subclasses of
226
+ the exceptions 1.1.1 let through, so existing `except` clauses still catch them.
227
+ - `get_img_list_info` returns `None` when Eagle fails, where 1.1.1 crashed with a `TypeError` if a filter was given.
228
+ - `get_img_info_from_lib_path` treats a single string filter as one prefix (1.1.1 used every character as a
229
+ prefix), skips items without a name when filtering, and returns files in a stable order.
230
+
231
+ Moving a V1 script to V2 when your Eagle is 4.0 Build 21 or later:
232
+
233
+ | V1 | V2 | Watch out |
234
+ |---|---|---|
235
+ | `add_from_url(url, name, ...)` | `v2.item.add(url=..., name=...)` | folders: `folders=[id]` instead of `folder_id` |
236
+ | `add_from_urls(items)` / `add_from_paths(items)` | `v2.item.add_many(items)` | sources can be mixed; returns the new IDs |
237
+ | `add_from_path(path, name)` | `v2.item.add(path=..., name=...)` | |
238
+ | `add_bookmark(url, name)` | `v2.item.add(bookmark_url=..., name=...)` | |
239
+ | `get_item_info(id)` | `v2.item.get_by_id(id)` | |
240
+ | `list_items(limit=200, ...)` | `v2.item.get(...)` or `v2.item.iterate(...)` | V2 pages default to 50 items |
241
+ | `move_to_trash([id])` | `v2.item.update(id, is_deleted=True)` | one item per call |
242
+ | `update_item(id, tags=...)` | `v2.item.update(id, tags=...)` | V2 can also set `name`, `folders` |
243
+ | `refresh_thumbnail(id)` / `refresh_palette(id)` | `v2.item.refresh_thumbnail(id)` | also refreshes the palette |
244
+ | `create_folder(name, parent_id)` | `v2.folder.create(name, parent=...)` | |
245
+ | `rename_folder` / `update_folder` | `v2.folder.update(id, name=..., icon_color=...)` | can also move folders |
246
+ | `list_folders()` / `get_recent_folders()` | `v2.folder.get()` / `v2.folder.get(is_recent=True)` | paginated |
247
+ | `get_library_info()` / `get_library_history()` | `v2.library.info()` / `v2.library.history()` | history items are `{'name', 'path'}` |
248
+ | `switch_library(path)` / `get_library_icon(path)` | `v2.library.switch(path)` / `v2.library.icon(path)` | |
249
+ | `get_application_info()` | `v2.app.info()` | |
250
+ | `get_thumbnail_path(id)` | none | keep using V1 |
251
+
252
+ ## Development
253
+
254
+ The tests replace the HTTP calls with mocks, so Eagle does not need to be running.
255
+
256
+ ```bash
257
+ pip install -e . pytest
258
+ pytest tests
259
+ ```
260
+
261
+ `tox -e py` runs the same tests plus a check of the source distribution. CI runs them on Linux with
262
+ Python 3.6 to 3.14, and on Windows and macOS with Python 3.14.
263
+
264
+ How the code is laid out (`src/eaglewrapper/`):
265
+
266
+ | File | What it does |
267
+ |---|---|
268
+ | `client.py` | `EagleClient`: builds URLs, adds the token, sends requests, decodes replies, raises the errors |
269
+ | `eagle.py` | `Eagle`: the V1 methods, kept compatible with 1.1.1 |
270
+ | `v2.py` | `EagleV2` and its sections (`item`, `folder`, `tag`, ...), plus pagination |
271
+ | `_library.py` | reads `metadata.json` files from a library folder |
272
+ | `errors.py` | the exceptions |
273
+
274
+ ## Contributor
275
+
276
+ <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
277
+ <!-- prettier-ignore-start -->
278
+ <!-- markdownlint-disable -->
279
+ <table>
280
+ <tbody>
281
+ <tr>
282
+ <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>
283
+ </tr>
284
+ </tbody>
285
+ </table>
286
+
287
+ <!-- markdownlint-restore -->
288
+ <!-- prettier-ignore-end -->
289
+
290
+ <!-- ALL-CONTRIBUTORS-LIST:END -->
291
+
292
+ ## License
293
+
294
+ [MIT](LICENSE)
Binary file