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.
- eaglewrapper-2.0.0/MANIFEST.in +6 -0
- eaglewrapper-2.0.0/PKG-INFO +460 -0
- eaglewrapper-2.0.0/README.md +409 -0
- eaglewrapper-2.0.0/doc/api-overview.png +0 -0
- eaglewrapper-2.0.0/setup.py +67 -0
- eaglewrapper-2.0.0/src/EagleWrapper.egg-info/PKG-INFO +460 -0
- eaglewrapper-2.0.0/src/EagleWrapper.egg-info/SOURCES.txt +34 -0
- eaglewrapper-2.0.0/src/eaglewrapper/__init__.py +20 -0
- eaglewrapper-2.0.0/src/eaglewrapper/_apis.py +62 -0
- eaglewrapper-2.0.0/src/eaglewrapper/_library.py +65 -0
- eaglewrapper-2.0.0/src/eaglewrapper/client.py +158 -0
- eaglewrapper-2.0.0/src/eaglewrapper/eagle.py +713 -0
- eaglewrapper-2.0.0/src/eaglewrapper/errors.py +55 -0
- eaglewrapper-2.0.0/src/eaglewrapper/py.typed +0 -0
- eaglewrapper-2.0.0/src/eaglewrapper/v2.py +616 -0
- eaglewrapper-2.0.0/tests/__init__.py +0 -0
- eaglewrapper-2.0.0/tests/fakes.py +43 -0
- eaglewrapper-2.0.0/tests/test_api_requests.py +270 -0
- eaglewrapper-2.0.0/tests/test_apis.py +67 -0
- eaglewrapper-2.0.0/tests/test_compat.py +96 -0
- eaglewrapper-2.0.0/tests/test_connection_options.py +137 -0
- eaglewrapper-2.0.0/tests/test_errors.py +107 -0
- eaglewrapper-2.0.0/tests/test_library_folder.py +116 -0
- eaglewrapper-2.0.0/tests/test_readme.py +36 -0
- eaglewrapper-2.0.0/tests/test_v1_additions.py +39 -0
- eaglewrapper-2.0.0/tests/test_v2.py +437 -0
- EagleWrapper-1.1.1/MANIFEST.in +0 -9
- EagleWrapper-1.1.1/PKG-INFO +0 -210
- EagleWrapper-1.1.1/README.md +0 -180
- EagleWrapper-1.1.1/reinstall.bat +0 -1
- EagleWrapper-1.1.1/reinstall.sh +0 -2
- EagleWrapper-1.1.1/setup.py +0 -53
- EagleWrapper-1.1.1/src/EagleWrapper.egg-info/PKG-INFO +0 -210
- EagleWrapper-1.1.1/src/EagleWrapper.egg-info/SOURCES.txt +0 -18
- EagleWrapper-1.1.1/src/eaglewrapper/__init__.py +0 -3
- EagleWrapper-1.1.1/src/eaglewrapper/eagle.py +0 -688
- {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/LICENSE +0 -0
- {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/doc/add-from-url.png +0 -0
- {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/doc/repo-logo.png +0 -0
- {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/pyproject.toml +0 -0
- {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/setup.cfg +0 -0
- {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/src/EagleWrapper.egg-info/dependency_links.txt +0 -0
- {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/src/EagleWrapper.egg-info/requires.txt +0 -0
- {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/src/EagleWrapper.egg-info/top_level.txt +0 -0
- {EagleWrapper-1.1.1 → eaglewrapper-2.0.0}/tests/test_eagle.py +0 -0
|
@@ -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
|
+
[](https://pypi.org/project/EagleWrapper/)
|
|
59
|
+
[](https://pypi.org/project/EagleWrapper/)
|
|
60
|
+
[](https://github.com/NatLee/eagle-wrapper/actions/workflows/test.yml)
|
|
61
|
+
[](https://github.com/NatLee/eagle-wrapper/actions/workflows/release.yml)
|
|
62
|
+
[](https://pypi.org/project/EagleWrapper/)
|
|
63
|
+
[](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
|
+

|
|
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
|
+

|
|
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
|
+
[](https://ko-fi.com/natlee_)
|
|
438
|
+
[](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)
|