EagleWrapper 1.2.0__tar.gz → 2.0.0__tar.gz

{eaglewrapper-1.2.0 → eaglewrapper-2.0.0}/MANIFEST.in

@@ -1,10 +1,6 @@
 include pyproject.toml
 include *.md
-include *.sh
-include *.bat
 include LICENSE
 include src/eaglewrapper/py.typed
-recursive-include test *.py
 recursive-include tests *.py
 recursive-include doc *.png
-recursive-include doc *.jpg

{eaglewrapper-1.2.0/src/EagleWrapper.egg-info → eaglewrapper-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: EagleWrapper
-Version: 1.2.0
+Version: 2.0.0
 Summary: A wrapper for the local HTTP API (V1 and Web API V2) of Eagle, an image management app.
 Home-page: https://github.com/NatLee/eagle-wrapper
 Author: Nat Lee
@@ -13,7 +13,8 @@ Project-URL: Eagle Web API V2, https://developer.eagle.cool/web-api
 Keywords: eagle,eagle api,eagle web api,image management,asset management,wrapper
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.6
 Classifier: Programming Language :: Python :: 3.7
@@ -94,6 +95,7 @@ pip install EagleWrapper
 
 Python 3.6 or later. Eagle must be running for everything except the library-folder reader.
 Web API V2, the connection options and the new exceptions arrived in 1.2.0.
+Which release speaks which Eagle API, and what to pin: see [Versioning](#versioning).
 
 ## Quick start
 
@@ -243,8 +245,25 @@ These are the methods of 1.1.1, unchanged, plus `star`, `get_library_icon` and `
 | **No API** | `get_img_info_from_lib_path(library_path, name_start_filters, max_workers, match)` | reads the library folder | list |
 | **Helpers** | `supports_v2()` · `check_success(response_or_dict)` | | bool |
 
-`add_from_path` returns Eagle's whole reply, not a bool, because 1.1.1 did. A dict is always truthy, so check
-`eagle.check_success(reply)` (or use `raise_errors=True`) instead of `if eagle.add_from_path(...)`.
+`add_from_path` returns Eagle's whole reply (a dict such as `{'status': 'success'}`), not a bool, because
+1.1.1 did and scripts may read it. A dict is always truthy, so `if eagle.add_from_path(...)` passes even when Eagle
+refused the file. Check the reply, or let failures raise:
+
+```python
+from eaglewrapper import Eagle, EagleAPIError
+
+eagle = Eagle()
+reply = eagle.add_from_path('/path/to/cat.jpg', 'Cat')
+if eagle.check_success(reply):  # True only for {'status': 'success', ...}
+    print('added')
+else:
+    print('Eagle said no:', reply)
+
+try:
+    Eagle(raise_errors=True).add_from_path('/path/to/cat.jpg', 'Cat')
+except EagleAPIError as e:
+    print('Eagle said no:', e.message)
+```
 
 ## Reading a library folder without Eagle
 
@@ -299,6 +318,87 @@ Moving a V1 script to V2 when your Eagle is 4.0 Build 21 or later:
 | `get_application_info()` | `v2.app.info()` | |
 | `get_thumbnail_path(id)` | none | keep using V1 |
 
+## Versioning
+
+The version number follows Eagle's API. The major number is the newest Eagle API generation a release
+speaks: 1 for V1, Eagle's original `/api/` API, and 2 for Web API V2 (`/api/v2/`). A test keeps the two in
+step. Minor releases wrap more
+of that API (often what a new Eagle build added) or add options to the package, and patch releases fix bugs.
+Code that works with one release keeps working with later releases that have the same major number.
+One slip from the early days: 1.1.0 renamed two arguments of 1.0.0 and changed what `add_from_url` and
+`set_tag_with_id` return.
+
+Eagle numbers its API only as V1 and V2. Whatever it adds inside a generation is tied to the Eagle build
+that brought it (see the [V1 changelog](https://api.eagle.cool/changelog) and the
+[V2 changelog](https://developer.eagle.cool/web-api/changelog)), so each release says which builds it covers:
+
+| EagleWrapper | Eagle APIs | What it wraps |
+|---|---|---|
+| 1.0.0 (April 2023) | V1 | 3 endpoints (add from URL, list items, update item) and the library-folder reader |
+| 1.1.0, 1.1.1 (April 2023) | V1 | all 21 endpoints documented at the time |
+| 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) |
+| 2.0.0 (November 2026) | V1 and Web API V2 | the same as 1.2.0, plus `SUPPORTED_APIS` (below) |
+
+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,
+before this rule was written down, because nothing changed for code written against V1. 2.0.0 puts the
+number back on the rule. It is the 1.2.0 code with this versioning written down and `SUPPORTED_APIS`
+added, so going from 1.2.0 to 2.0.0 needs no change in your code.
+
+The installed package knows what it covers:
+
+```python
+import eaglewrapper
+
+for api in eaglewrapper.SUPPORTED_APIS:
+    print(f'{api.name}: {api.prefix}... needs Eagle {api.since}+, wrapped up to Eagle {api.covered_up_to}')
+```
+
+```text
+V1: /api/... needs Eagle 1.11 Build 21+, wrapped up to Eagle 3.0 Build 23
+Web API V2: /api/v2/... needs Eagle 4.0 Build 21+, wrapped up to Eagle 4.0 Build 22
+```
+
+To see what your Eagle has, `Eagle().get_application_info()` returns its `version` and `buildVersion`,
+and `Eagle().supports_v2()` says whether Web API V2 is there. Endpoints that Eagle adds after the covered
+build are one call away with `eagle.v2.request('GET', 'section/endpoint')`. So are `item/open`,
+`item/select` and `folder/open`: the V2 changelog lists them, but the docs have no page for them yet, so
+they are not wrapped.
+
+What to pin: the major number, `EagleWrapper~=2.0` (that is `>=2.0, <3`). You get fixes and newly
+wrapped endpoints, and you move to another API generation only when you change the pin. The 1.x line gets
+no more releases: if you pinned `~=1.2`, change it to `~=2.0`; nothing else to do. `eagle.v2` needs
+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
+(see [Upgrading from 1.1.1](#upgrading-from-111)).
+
+## Plugins and related projects
+
+Not every job needs a script. A few things worth knowing about before you write one:
+
+From Eagle:
+
+- [Plugin Center](https://community-en.eagle.cool/plugins): plugins you install inside Eagle. The batch job
+  you are about to script may already exist as one.
+- [API Playground](https://developer.eagle.cool/web-api/get-started/playground): with Eagle open, visit
+  `http://localhost:41595/api/v2/playground` to try any Web API V2 endpoint from a form and see Eagle's real
+  reply before you write the Python call. It works on your real library, so writes there are real too.
+- [Plugin API](https://developer.eagle.cool/plugin-api) and the
+  [official plugin examples](https://github.com/eagle-app/eagle-plugin-examples): for code that should run
+  inside Eagle (a window, a background service, support for a new file format, an inspector panel) rather
+  than talk to it from outside. The examples have one small working plugin per type.
+- [AI Search](https://eagle.cool/support/article/ai-search): Eagle's offline search by description or by
+  similar image. `eagle.v2.ai_search` only works with this plugin installed.
+- [Eagle Skill / MCP](https://en.eagle.cool/blog/post/eagle-plugin-mcp-skill): lets an AI agent clean up
+  tags, plan folders and rewrite names and descriptions in your library. Worth a look when the hard part is
+  deciding what to change, not making the calls.
+
+Built on EagleWrapper:
+
+- [yande-and-konachan-to-eagle](https://github.com/NatLee/yande-and-konachan-to-eagle): fetches images and
+  their tags from yande.re and konachan.com and adds them to Eagle with `add_from_url`. A complete,
+  small downloader to copy from.
+
+Built something with EagleWrapper? Open an issue or a pull request and it can go on this list.
+
 ## Development
 
 The tests replace the HTTP calls with mocks, so Eagle does not need to be running.
@@ -308,6 +408,13 @@ pip install -e . pytest
 pytest tests
 ```
 
+The editable install picks up your edits right away. To reinstall a regular copy from the checkout instead
+(what the old `reinstall.sh` and `reinstall.bat` did with the retired `setup.py install`):
+
+```bash
+python -m pip install --force-reinstall .
+```
+
 `tox -e py` runs the same tests plus a check of the source distribution. CI runs them on Linux with
 Python 3.6 to 3.14, and on Windows and macOS with Python 3.14.
 
@@ -319,8 +426,17 @@ How the code is laid out (`src/eaglewrapper/`):
 | `eagle.py` | `Eagle`: the V1 methods, kept compatible with 1.1.1 |
 | `v2.py` | `EagleV2` and its sections (`item`, `folder`, `tag`, ...), plus pagination |
 | `_library.py` | reads `metadata.json` files from a library folder |
+| `_apis.py` | which Eagle APIs and builds this release covers (`SUPPORTED_APIS`); the code, `setup.py` and the README test read it |
 | `errors.py` | the exceptions |
 
+## Support
+
+EagleWrapper is free and kept up in spare time. If it saved you an afternoon, you can buy me a coffee on
+Ko-fi or chip in on Liberapay. Bug reports and pull requests help just as much.
+
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-natlee__-FF5E5B?logo=ko-fi&logoColor=white)](https://ko-fi.com/natlee_)
+[![Liberapay](https://img.shields.io/badge/Liberapay-natlee-F6C915?logo=liberapay&logoColor=black)](https://liberapay.com/natlee)
+
 ## Contributor
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->

{eaglewrapper-1.2.0 → eaglewrapper-2.0.0}/README.md

@@ -44,6 +44,7 @@ pip install EagleWrapper
 
 Python 3.6 or later. Eagle must be running for everything except the library-folder reader.
 Web API V2, the connection options and the new exceptions arrived in 1.2.0.
+Which release speaks which Eagle API, and what to pin: see [Versioning](#versioning).
 
 ## Quick start
 
@@ -193,8 +194,25 @@ These are the methods of 1.1.1, unchanged, plus `star`, `get_library_icon` and `
 | **No API** | `get_img_info_from_lib_path(library_path, name_start_filters, max_workers, match)` | reads the library folder | list |
 | **Helpers** | `supports_v2()` · `check_success(response_or_dict)` | | bool |
 
-`add_from_path` returns Eagle's whole reply, not a bool, because 1.1.1 did. A dict is always truthy, so check
-`eagle.check_success(reply)` (or use `raise_errors=True`) instead of `if eagle.add_from_path(...)`.
+`add_from_path` returns Eagle's whole reply (a dict such as `{'status': 'success'}`), not a bool, because
+1.1.1 did and scripts may read it. A dict is always truthy, so `if eagle.add_from_path(...)` passes even when Eagle
+refused the file. Check the reply, or let failures raise:
+
+```python
+from eaglewrapper import Eagle, EagleAPIError
+
+eagle = Eagle()
+reply = eagle.add_from_path('/path/to/cat.jpg', 'Cat')
+if eagle.check_success(reply):  # True only for {'status': 'success', ...}
+    print('added')
+else:
+    print('Eagle said no:', reply)
+
+try:
+    Eagle(raise_errors=True).add_from_path('/path/to/cat.jpg', 'Cat')
+except EagleAPIError as e:
+    print('Eagle said no:', e.message)
+```
 
 ## Reading a library folder without Eagle
 
@@ -249,6 +267,87 @@ Moving a V1 script to V2 when your Eagle is 4.0 Build 21 or later:
 | `get_application_info()` | `v2.app.info()` | |
 | `get_thumbnail_path(id)` | none | keep using V1 |
 
+## Versioning
+
+The version number follows Eagle's API. The major number is the newest Eagle API generation a release
+speaks: 1 for V1, Eagle's original `/api/` API, and 2 for Web API V2 (`/api/v2/`). A test keeps the two in
+step. Minor releases wrap more
+of that API (often what a new Eagle build added) or add options to the package, and patch releases fix bugs.
+Code that works with one release keeps working with later releases that have the same major number.
+One slip from the early days: 1.1.0 renamed two arguments of 1.0.0 and changed what `add_from_url` and
+`set_tag_with_id` return.
+
+Eagle numbers its API only as V1 and V2. Whatever it adds inside a generation is tied to the Eagle build
+that brought it (see the [V1 changelog](https://api.eagle.cool/changelog) and the
+[V2 changelog](https://developer.eagle.cool/web-api/changelog)), so each release says which builds it covers:
+
+| EagleWrapper | Eagle APIs | What it wraps |
+|---|---|---|
+| 1.0.0 (April 2023) | V1 | 3 endpoints (add from URL, list items, update item) and the library-folder reader |
+| 1.1.0, 1.1.1 (April 2023) | V1 | all 21 endpoints documented at the time |
+| 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) |
+| 2.0.0 (November 2026) | V1 and Web API V2 | the same as 1.2.0, plus `SUPPORTED_APIS` (below) |
+
+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,
+before this rule was written down, because nothing changed for code written against V1. 2.0.0 puts the
+number back on the rule. It is the 1.2.0 code with this versioning written down and `SUPPORTED_APIS`
+added, so going from 1.2.0 to 2.0.0 needs no change in your code.
+
+The installed package knows what it covers:
+
+```python
+import eaglewrapper
+
+for api in eaglewrapper.SUPPORTED_APIS:
+    print(f'{api.name}: {api.prefix}... needs Eagle {api.since}+, wrapped up to Eagle {api.covered_up_to}')
+```
+
+```text
+V1: /api/... needs Eagle 1.11 Build 21+, wrapped up to Eagle 3.0 Build 23
+Web API V2: /api/v2/... needs Eagle 4.0 Build 21+, wrapped up to Eagle 4.0 Build 22
+```
+
+To see what your Eagle has, `Eagle().get_application_info()` returns its `version` and `buildVersion`,
+and `Eagle().supports_v2()` says whether Web API V2 is there. Endpoints that Eagle adds after the covered
+build are one call away with `eagle.v2.request('GET', 'section/endpoint')`. So are `item/open`,
+`item/select` and `folder/open`: the V2 changelog lists them, but the docs have no page for them yet, so
+they are not wrapped.
+
+What to pin: the major number, `EagleWrapper~=2.0` (that is `>=2.0, <3`). You get fixes and newly
+wrapped endpoints, and you move to another API generation only when you change the pin. The 1.x line gets
+no more releases: if you pinned `~=1.2`, change it to `~=2.0`; nothing else to do. `eagle.v2` needs
+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
+(see [Upgrading from 1.1.1](#upgrading-from-111)).
+
+## Plugins and related projects
+
+Not every job needs a script. A few things worth knowing about before you write one:
+
+From Eagle:
+
+- [Plugin Center](https://community-en.eagle.cool/plugins): plugins you install inside Eagle. The batch job
+  you are about to script may already exist as one.
+- [API Playground](https://developer.eagle.cool/web-api/get-started/playground): with Eagle open, visit
+  `http://localhost:41595/api/v2/playground` to try any Web API V2 endpoint from a form and see Eagle's real
+  reply before you write the Python call. It works on your real library, so writes there are real too.
+- [Plugin API](https://developer.eagle.cool/plugin-api) and the
+  [official plugin examples](https://github.com/eagle-app/eagle-plugin-examples): for code that should run
+  inside Eagle (a window, a background service, support for a new file format, an inspector panel) rather
+  than talk to it from outside. The examples have one small working plugin per type.
+- [AI Search](https://eagle.cool/support/article/ai-search): Eagle's offline search by description or by
+  similar image. `eagle.v2.ai_search` only works with this plugin installed.
+- [Eagle Skill / MCP](https://en.eagle.cool/blog/post/eagle-plugin-mcp-skill): lets an AI agent clean up
+  tags, plan folders and rewrite names and descriptions in your library. Worth a look when the hard part is
+  deciding what to change, not making the calls.
+
+Built on EagleWrapper:
+
+- [yande-and-konachan-to-eagle](https://github.com/NatLee/yande-and-konachan-to-eagle): fetches images and
+  their tags from yande.re and konachan.com and adds them to Eagle with `add_from_url`. A complete,
+  small downloader to copy from.
+
+Built something with EagleWrapper? Open an issue or a pull request and it can go on this list.
+
 ## Development
 
 The tests replace the HTTP calls with mocks, so Eagle does not need to be running.
@@ -258,6 +357,13 @@ pip install -e . pytest
 pytest tests
 ```
 
+The editable install picks up your edits right away. To reinstall a regular copy from the checkout instead
+(what the old `reinstall.sh` and `reinstall.bat` did with the retired `setup.py install`):
+
+```bash
+python -m pip install --force-reinstall .
+```
+
 `tox -e py` runs the same tests plus a check of the source distribution. CI runs them on Linux with
 Python 3.6 to 3.14, and on Windows and macOS with Python 3.14.
 
@@ -269,8 +375,17 @@ How the code is laid out (`src/eaglewrapper/`):
 | `eagle.py` | `Eagle`: the V1 methods, kept compatible with 1.1.1 |
 | `v2.py` | `EagleV2` and its sections (`item`, `folder`, `tag`, ...), plus pagination |
 | `_library.py` | reads `metadata.json` files from a library folder |
+| `_apis.py` | which Eagle APIs and builds this release covers (`SUPPORTED_APIS`); the code, `setup.py` and the README test read it |
 | `errors.py` | the exceptions |
 
+## Support
+
+EagleWrapper is free and kept up in spare time. If it saved you an afternoon, you can buy me a coffee on
+Ko-fi or chip in on Liberapay. Bug reports and pull requests help just as much.
+
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-natlee__-FF5E5B?logo=ko-fi&logoColor=white)](https://ko-fi.com/natlee_)
+[![Liberapay](https://img.shields.io/badge/Liberapay-natlee-F6C915?logo=liberapay&logoColor=black)](https://liberapay.com/natlee)
+
 ## Contributor
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->

{eaglewrapper-1.2.0 → eaglewrapper-2.0.0}/setup.py

@@ -1,23 +1,36 @@
+import os
+import runpy
+
 import setuptools
 
-with open('README.md', 'r', encoding='utf-8') as fh:
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+with open(os.path.join(HERE, 'README.md'), 'r', encoding='utf-8') as fh:
     long_description = fh.read()
 
+# The Eagle APIs this release speaks (names, docs links) come from the package itself.
+# The file is loaded on its own because importing the package would need its dependencies.
+APIS = runpy.run_path(os.path.join(HERE, 'src', 'eaglewrapper', '_apis.py'))
+API_V1, API_V2 = APIS['API_V1'], APIS['API_V2']
+
+REPO = 'https://github.com/NatLee/eagle-wrapper'
+
 setuptools.setup(
     name='EagleWrapper',
     author='Nat Lee',
     author_email='natlee.work@gmail.com',
-    description='A wrapper for the local HTTP API (V1 and Web API V2) of Eagle, an image management app.',
+    description='A wrapper for the local HTTP API ({}) of Eagle, an image management app.'.format(
+        ' and '.join(api.name for api in APIS['SUPPORTED_APIS'])),
     keywords='eagle, eagle api, eagle web api, image management, asset management, wrapper',
     long_description=long_description,
     long_description_content_type='text/markdown',
-    url='https://github.com/NatLee/eagle-wrapper',
+    url=REPO,
     project_urls={
-        'Documentation': 'https://github.com/NatLee/eagle-wrapper',
-        'Bug Reports': 'https://github.com/NatLee/eagle-wrapper/issues',
-        'Source Code': 'https://github.com/NatLee/eagle-wrapper',
-        'Official API Documentation': 'https://api.eagle.cool/',
-        'Eagle Web API V2': 'https://developer.eagle.cool/web-api',
+        'Documentation': REPO,
+        'Bug Reports': REPO + '/issues',
+        'Source Code': REPO,
+        'Official API Documentation': API_V1.docs,
+        'Eagle Web API V2': API_V2.docs,
         # 'Funding': '',
         # 'Say Thanks!': '',
     },
@@ -29,7 +42,8 @@ setuptools.setup(
         'Development Status :: 5 - Production/Stable',
 
         'Intended Audience :: Developers',
-        'Topic :: Software Development :: Build Tools',
+        'Topic :: Multimedia :: Graphics',
+        'Topic :: Software Development :: Libraries :: Python Modules',
 
         'Programming Language :: Python :: 3',
         'Programming Language :: Python :: 3.6',
@@ -49,10 +63,5 @@ setuptools.setup(
     install_requires=['requests', 'loguru'],
     extras_require={
         'dev': ['check-manifest'],
-        # 'test': ['coverage'],
     },
-    entry_points={
-        'console_scripts': [
-        ]
-    }
-)
+)

{eaglewrapper-1.2.0 → eaglewrapper-2.0.0/src/EagleWrapper.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: EagleWrapper
-Version: 1.2.0
+Version: 2.0.0
 Summary: A wrapper for the local HTTP API (V1 and Web API V2) of Eagle, an image management app.
 Home-page: https://github.com/NatLee/eagle-wrapper
 Author: Nat Lee
@@ -13,7 +13,8 @@ Project-URL: Eagle Web API V2, https://developer.eagle.cool/web-api
 Keywords: eagle,eagle api,eagle web api,image management,asset management,wrapper
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.6
 Classifier: Programming Language :: Python :: 3.7
@@ -94,6 +95,7 @@ pip install EagleWrapper
 
 Python 3.6 or later. Eagle must be running for everything except the library-folder reader.
 Web API V2, the connection options and the new exceptions arrived in 1.2.0.
+Which release speaks which Eagle API, and what to pin: see [Versioning](#versioning).
 
 ## Quick start
 
@@ -243,8 +245,25 @@ These are the methods of 1.1.1, unchanged, plus `star`, `get_library_icon` and `
 | **No API** | `get_img_info_from_lib_path(library_path, name_start_filters, max_workers, match)` | reads the library folder | list |
 | **Helpers** | `supports_v2()` · `check_success(response_or_dict)` | | bool |
 
-`add_from_path` returns Eagle's whole reply, not a bool, because 1.1.1 did. A dict is always truthy, so check
-`eagle.check_success(reply)` (or use `raise_errors=True`) instead of `if eagle.add_from_path(...)`.
+`add_from_path` returns Eagle's whole reply (a dict such as `{'status': 'success'}`), not a bool, because
+1.1.1 did and scripts may read it. A dict is always truthy, so `if eagle.add_from_path(...)` passes even when Eagle
+refused the file. Check the reply, or let failures raise:
+
+```python
+from eaglewrapper import Eagle, EagleAPIError
+
+eagle = Eagle()
+reply = eagle.add_from_path('/path/to/cat.jpg', 'Cat')
+if eagle.check_success(reply):  # True only for {'status': 'success', ...}
+    print('added')
+else:
+    print('Eagle said no:', reply)
+
+try:
+    Eagle(raise_errors=True).add_from_path('/path/to/cat.jpg', 'Cat')
+except EagleAPIError as e:
+    print('Eagle said no:', e.message)
+```
 
 ## Reading a library folder without Eagle
 
@@ -299,6 +318,87 @@ Moving a V1 script to V2 when your Eagle is 4.0 Build 21 or later:
 | `get_application_info()` | `v2.app.info()` | |
 | `get_thumbnail_path(id)` | none | keep using V1 |
 
+## Versioning
+
+The version number follows Eagle's API. The major number is the newest Eagle API generation a release
+speaks: 1 for V1, Eagle's original `/api/` API, and 2 for Web API V2 (`/api/v2/`). A test keeps the two in
+step. Minor releases wrap more
+of that API (often what a new Eagle build added) or add options to the package, and patch releases fix bugs.
+Code that works with one release keeps working with later releases that have the same major number.
+One slip from the early days: 1.1.0 renamed two arguments of 1.0.0 and changed what `add_from_url` and
+`set_tag_with_id` return.
+
+Eagle numbers its API only as V1 and V2. Whatever it adds inside a generation is tied to the Eagle build
+that brought it (see the [V1 changelog](https://api.eagle.cool/changelog) and the
+[V2 changelog](https://developer.eagle.cool/web-api/changelog)), so each release says which builds it covers:
+
+| EagleWrapper | Eagle APIs | What it wraps |
+|---|---|---|
+| 1.0.0 (April 2023) | V1 | 3 endpoints (add from URL, list items, update item) and the library-folder reader |
+| 1.1.0, 1.1.1 (April 2023) | V1 | all 21 endpoints documented at the time |
+| 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) |
+| 2.0.0 (November 2026) | V1 and Web API V2 | the same as 1.2.0, plus `SUPPORTED_APIS` (below) |
+
+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,
+before this rule was written down, because nothing changed for code written against V1. 2.0.0 puts the
+number back on the rule. It is the 1.2.0 code with this versioning written down and `SUPPORTED_APIS`
+added, so going from 1.2.0 to 2.0.0 needs no change in your code.
+
+The installed package knows what it covers:
+
+```python
+import eaglewrapper
+
+for api in eaglewrapper.SUPPORTED_APIS:
+    print(f'{api.name}: {api.prefix}... needs Eagle {api.since}+, wrapped up to Eagle {api.covered_up_to}')
+```
+
+```text
+V1: /api/... needs Eagle 1.11 Build 21+, wrapped up to Eagle 3.0 Build 23
+Web API V2: /api/v2/... needs Eagle 4.0 Build 21+, wrapped up to Eagle 4.0 Build 22
+```
+
+To see what your Eagle has, `Eagle().get_application_info()` returns its `version` and `buildVersion`,
+and `Eagle().supports_v2()` says whether Web API V2 is there. Endpoints that Eagle adds after the covered
+build are one call away with `eagle.v2.request('GET', 'section/endpoint')`. So are `item/open`,
+`item/select` and `folder/open`: the V2 changelog lists them, but the docs have no page for them yet, so
+they are not wrapped.
+
+What to pin: the major number, `EagleWrapper~=2.0` (that is `>=2.0, <3`). You get fixes and newly
+wrapped endpoints, and you move to another API generation only when you change the pin. The 1.x line gets
+no more releases: if you pinned `~=1.2`, change it to `~=2.0`; nothing else to do. `eagle.v2` needs
+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
+(see [Upgrading from 1.1.1](#upgrading-from-111)).
+
+## Plugins and related projects
+
+Not every job needs a script. A few things worth knowing about before you write one:
+
+From Eagle:
+
+- [Plugin Center](https://community-en.eagle.cool/plugins): plugins you install inside Eagle. The batch job
+  you are about to script may already exist as one.
+- [API Playground](https://developer.eagle.cool/web-api/get-started/playground): with Eagle open, visit
+  `http://localhost:41595/api/v2/playground` to try any Web API V2 endpoint from a form and see Eagle's real
+  reply before you write the Python call. It works on your real library, so writes there are real too.
+- [Plugin API](https://developer.eagle.cool/plugin-api) and the
+  [official plugin examples](https://github.com/eagle-app/eagle-plugin-examples): for code that should run
+  inside Eagle (a window, a background service, support for a new file format, an inspector panel) rather
+  than talk to it from outside. The examples have one small working plugin per type.
+- [AI Search](https://eagle.cool/support/article/ai-search): Eagle's offline search by description or by
+  similar image. `eagle.v2.ai_search` only works with this plugin installed.
+- [Eagle Skill / MCP](https://en.eagle.cool/blog/post/eagle-plugin-mcp-skill): lets an AI agent clean up
+  tags, plan folders and rewrite names and descriptions in your library. Worth a look when the hard part is
+  deciding what to change, not making the calls.
+
+Built on EagleWrapper:
+
+- [yande-and-konachan-to-eagle](https://github.com/NatLee/yande-and-konachan-to-eagle): fetches images and
+  their tags from yande.re and konachan.com and adds them to Eagle with `add_from_url`. A complete,
+  small downloader to copy from.
+
+Built something with EagleWrapper? Open an issue or a pull request and it can go on this list.
+
 ## Development
 
 The tests replace the HTTP calls with mocks, so Eagle does not need to be running.
@@ -308,6 +408,13 @@ pip install -e . pytest
 pytest tests
 ```
 
+The editable install picks up your edits right away. To reinstall a regular copy from the checkout instead
+(what the old `reinstall.sh` and `reinstall.bat` did with the retired `setup.py install`):
+
+```bash
+python -m pip install --force-reinstall .
+```
+
 `tox -e py` runs the same tests plus a check of the source distribution. CI runs them on Linux with
 Python 3.6 to 3.14, and on Windows and macOS with Python 3.14.
 
@@ -319,8 +426,17 @@ How the code is laid out (`src/eaglewrapper/`):
 | `eagle.py` | `Eagle`: the V1 methods, kept compatible with 1.1.1 |
 | `v2.py` | `EagleV2` and its sections (`item`, `folder`, `tag`, ...), plus pagination |
 | `_library.py` | reads `metadata.json` files from a library folder |
+| `_apis.py` | which Eagle APIs and builds this release covers (`SUPPORTED_APIS`); the code, `setup.py` and the README test read it |
 | `errors.py` | the exceptions |
 
+## Support
+
+EagleWrapper is free and kept up in spare time. If it saved you an afternoon, you can buy me a coffee on
+Ko-fi or chip in on Liberapay. Bug reports and pull requests help just as much.
+
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-natlee__-FF5E5B?logo=ko-fi&logoColor=white)](https://ko-fi.com/natlee_)
+[![Liberapay](https://img.shields.io/badge/Liberapay-natlee-F6C915?logo=liberapay&logoColor=black)](https://liberapay.com/natlee)
+
 ## Contributor
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->

{eaglewrapper-1.2.0 → eaglewrapper-2.0.0}/src/EagleWrapper.egg-info/SOURCES.txt

@@ -2,8 +2,6 @@ LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
-reinstall.bat
-reinstall.sh
 setup.cfg
 setup.py
 doc/add-from-url.png
@@ -15,6 +13,7 @@ src/EagleWrapper.egg-info/dependency_links.txt
 src/EagleWrapper.egg-info/requires.txt
 src/EagleWrapper.egg-info/top_level.txt
 src/eaglewrapper/__init__.py
+src/eaglewrapper/_apis.py
 src/eaglewrapper/_library.py
 src/eaglewrapper/client.py
 src/eaglewrapper/eagle.py
@@ -24,10 +23,12 @@ src/eaglewrapper/v2.py
 tests/__init__.py
 tests/fakes.py
 tests/test_api_requests.py
+tests/test_apis.py
 tests/test_compat.py
 tests/test_connection_options.py
 tests/test_eagle.py
 tests/test_errors.py
 tests/test_library_folder.py
+tests/test_readme.py
 tests/test_v1_additions.py
 tests/test_v2.py

{eaglewrapper-1.2.0 → eaglewrapper-2.0.0}/src/eaglewrapper/__init__.py

@@ -1,11 +1,13 @@
 """A Python wrapper for the local HTTP API of Eagle, the image and design asset manager.
 
 * :class:`Eagle` - the V1 (legacy) API methods, the library-folder reader, and ``.v2``.
-* :class:`EagleV2` - the Web API V2 on its own (Eagle 4.0 Build 21 or later).
+* :class:`EagleV2` - the Web API V2 on its own.
 * :mod:`eaglewrapper.errors` - the exceptions.
+* :data:`SUPPORTED_APIS` - which Eagle APIs and Eagle builds this release covers.
 """
-__version__ = '1.2.0'
+__version__ = '2.0.0'
 
+from ._apis import API_V1, API_V2, SUPPORTED_APIS, EagleAPI
 from .client import EagleClient
 from .eagle import Eagle, ImageData
 from .errors import EagleAPIError, EagleConnectionError, EagleError, EagleResponseError
@@ -14,4 +16,5 @@ from .v2 import EagleV2
 __all__ = [
     'Eagle', 'EagleV2', 'EagleClient', 'ImageData',
     'EagleError', 'EagleAPIError', 'EagleConnectionError', 'EagleResponseError',
+    'EagleAPI', 'API_V1', 'API_V2', 'SUPPORTED_APIS',
 ]