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.
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/MANIFEST.in +2 -1
- eaglewrapper-1.2.0/PKG-INFO +344 -0
- eaglewrapper-1.2.0/README.md +294 -0
- eaglewrapper-1.2.0/doc/api-overview.png +0 -0
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/setup.py +7 -2
- eaglewrapper-1.2.0/src/EagleWrapper.egg-info/PKG-INFO +344 -0
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/src/EagleWrapper.egg-info/SOURCES.txt +16 -1
- eaglewrapper-1.2.0/src/eaglewrapper/__init__.py +17 -0
- eaglewrapper-1.2.0/src/eaglewrapper/_library.py +65 -0
- eaglewrapper-1.2.0/src/eaglewrapper/client.py +149 -0
- eaglewrapper-1.2.0/src/eaglewrapper/eagle.py +721 -0
- eaglewrapper-1.2.0/src/eaglewrapper/errors.py +55 -0
- eaglewrapper-1.2.0/src/eaglewrapper/py.typed +0 -0
- eaglewrapper-1.2.0/src/eaglewrapper/v2.py +615 -0
- eaglewrapper-1.2.0/tests/__init__.py +0 -0
- eaglewrapper-1.2.0/tests/fakes.py +40 -0
- eaglewrapper-1.2.0/tests/test_api_requests.py +277 -0
- eaglewrapper-1.2.0/tests/test_compat.py +96 -0
- eaglewrapper-1.2.0/tests/test_connection_options.py +137 -0
- eaglewrapper-1.2.0/tests/test_errors.py +107 -0
- eaglewrapper-1.2.0/tests/test_library_folder.py +116 -0
- eaglewrapper-1.2.0/tests/test_v1_additions.py +39 -0
- eaglewrapper-1.2.0/tests/test_v2.py +423 -0
- EagleWrapper-1.1.0/PKG-INFO +0 -210
- EagleWrapper-1.1.0/README.md +0 -180
- EagleWrapper-1.1.0/src/EagleWrapper.egg-info/PKG-INFO +0 -210
- EagleWrapper-1.1.0/src/eaglewrapper/__init__.py +0 -3
- EagleWrapper-1.1.0/src/eaglewrapper/eagle.py +0 -688
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/LICENSE +0 -0
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/doc/add-from-url.png +0 -0
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/doc/repo-logo.png +0 -0
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/pyproject.toml +0 -0
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/reinstall.bat +0 -0
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/reinstall.sh +0 -0
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/setup.cfg +0 -0
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/src/EagleWrapper.egg-info/dependency_links.txt +0 -0
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/src/EagleWrapper.egg-info/requires.txt +0 -0
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/src/EagleWrapper.egg-info/top_level.txt +0 -0
- {EagleWrapper-1.1.0 → eaglewrapper-1.2.0}/tests/test_eagle.py +0 -0
|
@@ -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
|
+
[](https://pypi.org/project/EagleWrapper/)
|
|
58
|
+
[](https://pypi.org/project/EagleWrapper/)
|
|
59
|
+
[](https://github.com/NatLee/eagle-wrapper/actions/workflows/test.yml)
|
|
60
|
+
[](https://github.com/NatLee/eagle-wrapper/actions/workflows/release.yml)
|
|
61
|
+
[](https://pypi.org/project/EagleWrapper/)
|
|
62
|
+
[](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
|
+

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

|
|
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
|
+
[](https://pypi.org/project/EagleWrapper/)
|
|
8
|
+
[](https://pypi.org/project/EagleWrapper/)
|
|
9
|
+
[](https://github.com/NatLee/eagle-wrapper/actions/workflows/test.yml)
|
|
10
|
+
[](https://github.com/NatLee/eagle-wrapper/actions/workflows/release.yml)
|
|
11
|
+
[](https://pypi.org/project/EagleWrapper/)
|
|
12
|
+
[](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
|
+

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

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