eagle-cooler 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. eagle_cooler-0.1.0/PKG-INFO +245 -0
  2. eagle_cooler-0.1.0/README.md +235 -0
  3. eagle_cooler-0.1.0/pyproject.toml +19 -0
  4. eagle_cooler-0.1.0/src/eagle_cooler/__init__.py +5 -0
  5. eagle_cooler-0.1.0/src/eagle_cooler/callback.py +1078 -0
  6. eagle_cooler-0.1.0/src/eagle_cooler/context.py +46 -0
  7. eagle_cooler-0.1.0/src/eagle_cooler/core.py +55 -0
  8. eagle_cooler-0.1.0/src/eagle_cooler/model.py +48 -0
  9. eagle_cooler-0.1.0/src/eagle_cooler/webapi.py +246 -0
eagle_cooler-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,245 @@
1
+ Metadata-Version: 2.3
2
+ Name: eagle-cooler
3
+ Version: 0.1.0
4
+ Summary: Python library for bridging Eagle js environment
5
+ Author: ZackaryW
6
+ Author-email: ZackaryW <gitzackw@gmail.com>
7
+ Requires-Dist: requests>=2.25.0
8
+ Requires-Python: >=3.13
9
+ Description-Content-Type: text/markdown
10
+
11
+ # Eagle Cooler 🦅❄️
12
+
13
+ [![PyPI version](https://badge.fury.io/py/eagle-cooler.svg)](https://badge.fury.io/py/eagle-cooler)
14
+ [![Python Support](https://img.shields.io/pypi/pyversions/eagle-cooler.svg)](https://pypi.org/project/eagle-cooler/)
15
+ [![License](https://img.shields.io/github/license/ZackaryW/py-eagle-cooler.svg)](LICENSE)
16
+
17
+ A modern Python wrapper for the [Eagle.cool](https://eagle.cool) HTTP API. Works independently with Eagle's web API or seamlessly integrates with the Power Eagle plugin system for enhanced functionality.
18
+
19
+ ## ✨ Features
20
+
21
+ - 🚀 **Complete API Coverage** - Full implementation of Eagle's HTTP API
22
+ - 🔐 **Flexible Authentication** - Works standalone with manual token setup or automatically with Power Eagle
23
+ - 📝 **Type Hints** - Better development experience with full type annotations
24
+ - 🎯 **Easy-to-use Interface** - Clean, class-based API design
25
+ - ⚡ **Modern Python** - Built for Python 3.13+ with modern best practices
26
+ - 🔌 **Plugin Ready** - Enhanced integration with Power Eagle plugin ecosystem
27
+ - 🏠 **Standalone Ready** - Can work independently with just Eagle's web API
28
+
29
+ ## 📦 Installation
30
+
31
+ Install the latest stable version from PyPI:
32
+
33
+ ```bash
34
+ # Using uv (recommended)
35
+ uv add eagle-cooler
36
+
37
+ # Using pip
38
+ pip install eagle-cooler
39
+
40
+ # For development
41
+ git clone https://github.com/ZackaryW/py-eagle-cooler.git
42
+ cd py-eagle-cooler
43
+ uv sync --dev
44
+ ```
45
+
46
+ ## 🚀 Quick Start
47
+
48
+ ### Standalone Usage (Web API Only)
49
+
50
+ For basic functionality using Eagle's HTTP API directly:
51
+
52
+ ```python
53
+ from eagle_cooler import EagleWebApi
54
+
55
+ # Get application info
56
+ app_info = EagleWebApi.application.info()
57
+ print(f"Eagle version: {app_info['version']}")
58
+
59
+ # List folders
60
+ folders = EagleWebApi.folder.list()
61
+ print(f"Found {len(folders)} folders")
62
+
63
+ # Create a new folder
64
+ new_folder = EagleWebApi.folder.create("My New Folder")
65
+ print(f"Created: {new_folder['name']}")
66
+
67
+ # List items with filters
68
+ items = EagleWebApi.item.list(limit=10, ext="jpg")
69
+ print(f"Found {len(items)} JPG images")
70
+
71
+ # Add item from URL
72
+ result = EagleWebApi.item.add_from_url(
73
+ url="https://example.com/image.jpg",
74
+ name="Example Image",
75
+ tags=["example", "test"]
76
+ )
77
+
78
+ # Add item from local file
79
+ local_item = EagleWebApi.item.add_from_path(
80
+ path="/path/to/image.jpg",
81
+ name="Local Image",
82
+ tags=["local"]
83
+ )
84
+ ```
85
+
86
+ ### Power Eagle Integration (Enhanced Features)
87
+
88
+ When running in a Power Eagle context, access to enhanced features:
89
+
90
+ ```python
91
+ # In a Power Eagle Python script
92
+ from eagle_cooler import eagleContext, EagleCallback
93
+
94
+ # Get selected items and folders from Power Eagle context
95
+ selected_items = eagleContext.get_selected_items()
96
+ selected_folders = eagleContext.get_selected_folders()
97
+
98
+ # Get just the IDs if needed
99
+ selected_item_ids = eagleContext.get_selected_item_ids()
100
+ selected_folder_ids = eagleContext.get_selected_folder_ids()
101
+
102
+ # Use callback system for advanced plugin operations
103
+ # (extensive callback API available for plugin development)
104
+ ```
105
+
106
+ ## 📚 API Reference
107
+
108
+ ### 🏢 Application
109
+ - `EagleWebApi.application.info()` - Get application information
110
+
111
+ ### 📁 Folders
112
+ - `EagleWebApi.folder.create(name, parent_id=None)` - Create folder
113
+ - `EagleWebApi.folder.rename(folder_id, new_name)` - Rename folder
114
+ - `EagleWebApi.folder.update(folder_id, new_name=None, new_description=None, new_color=None)` - Update folder properties
115
+ - `EagleWebApi.folder.list()` - List all folders
116
+ - `EagleWebApi.folder.list_recent()` - List recent folders
117
+
118
+ ### 📚 Library
119
+ - `EagleWebApi.library.info()` - Get library information
120
+ - `EagleWebApi.library.history()` - Get library history
121
+ - `EagleWebApi.library.switch(library_path)` - Switch to different library
122
+ - `EagleWebApi.library.icon(library_path)` - Get library icon
123
+
124
+ ### 🖼️ Items
125
+ - `EagleWebApi.item.list(limit=None, offset=None, order_by=None, keyword=None, ext=None, tags=None, folders=None)` - List items with filters
126
+ - `EagleWebApi.item.get_info(item_id)` - Get item details
127
+ - `EagleWebApi.item.get_thumbnail(item_id)` - Get item thumbnail
128
+ - `EagleWebApi.item.update(item_id, tags=None, annotation=None, url=None, star=None)` - Update item properties
129
+ - `EagleWebApi.item.add_from_url(url, name, website=None, tags=None, star=None, annotation=None, modification_time=None, folder_id=None, headers=None)` - Add item from URL
130
+ - `EagleWebApi.item.add_from_path(path, name, website=None, annotation=None, tags=None, folder_id=None)` - Add item from file path
131
+ - `EagleWebApi.item.add_from_urls(items, folder_id=None)` - Add multiple items from URLs
132
+ - `EagleWebApi.item.add_bookmark(url, name, base64=None, tags=None, modification_time=None, folder_id=None)` - Add bookmark
133
+ - `EagleWebApi.item.move_to_trash(item_ids)` - Move items to trash
134
+ - `EagleWebApi.item.refresh_thumbnail(item_id)` - Refresh thumbnail
135
+ - `EagleWebApi.item.refresh_palette(item_id)` - Refresh color palette
136
+
137
+ ### 🔧 Context (Power Eagle Mode)
138
+ - `eagleContext.get_selected_item_ids()` - Get selected item IDs from Power Eagle context
139
+ - `eagleContext.get_selected_folder_ids()` - Get selected folder IDs from Power Eagle context
140
+ - `eagleContext.get_selected_items(throw=False)` - Get selected items as typed ItemModel objects
141
+ - `eagleContext.get_selected_folders()` - Get selected folders as typed FolderModel objects
142
+
143
+ ### 📞 Callbacks (Power Eagle Plugins)
144
+ - `EagleCallback` - Callback system for Power Eagle plugin integration (extensive API available)
145
+
146
+ ## 🔌 Usage Modes
147
+
148
+ Eagle Cooler supports two usage modes:
149
+
150
+ ### 🏠 Standalone Mode (Web API)
151
+ - **Limited Capacity**: Basic API operations through Eagle's HTTP interface
152
+ - **Manual Setup**: Requires Eagle application running with HTTP API enabled
153
+ - **Authentication**: Uses direct API calls (no token management)
154
+ - **Features**: Core operations like listing, creating folders, basic item management
155
+
156
+ ### 🚀 Power Eagle Mode (Enhanced)
157
+ - **Full Capacity**: Complete feature set with enhanced functionality
158
+ - **Automatic Setup**: Token and context management handled automatically
159
+ - **Authentication**: Seamless integration with Power Eagle's security context
160
+ - **Features**: All core operations plus callbacks, advanced file operations, and plugin ecosystem integration
161
+
162
+ ```python
163
+ # Standalone mode example
164
+ from eagle_cooler import EagleWebApi
165
+
166
+ # Basic operations available
167
+ folders = EagleWebApi.folder.list()
168
+
169
+ # Power Eagle mode example (when POWEREAGLE_CONTEXT is available)
170
+ from eagle_cooler import EagleWebApi, eagleContext, EagleCallback
171
+
172
+ # Enhanced operations available:
173
+ # 1. Automatic token management
174
+ folders = EagleWebApi.folder.list()
175
+
176
+ # 2. Access to Power Eagle context with typed models
177
+ selected_items = eagleContext.get_selected_items() # Returns list[ItemModel]
178
+ selected_folders = eagleContext.get_selected_folders() # Returns list[FolderModel]
179
+
180
+ # 3. Callback system for advanced plugin operations
181
+ if selected_items:
182
+ for item in selected_items:
183
+ print(f"Selected item: {item['name']} ({item['ext']})")
184
+ # Use callback system to interact with Power Eagle host
185
+ # (extensive callback API available - see METHODS_WITH_RETURN_VALUES)
186
+ ```
187
+
188
+ ## ⚙️ Requirements
189
+
190
+ - **Python**: >= 3.13
191
+ - **Eagle.cool**: Application running with API access enabled
192
+ - **Dependencies**: `requests >= 2.25.0`
193
+ - **For Power Eagle**: `POWEREAGLE_CONTEXT` environment variable set
194
+
195
+ ### Setup Eagle API Access
196
+
197
+ 1. Open Eagle.cool application
198
+ 2. Go to **Preferences** → **Plugin**
199
+ 3. Enable **HTTP API**
200
+ 4. Note the API port (default: 41595)
201
+
202
+ ## 🤝 Contributing
203
+
204
+ We welcome contributions! Here's how to get started:
205
+
206
+ 1. **Fork the repository**
207
+ 2. **Clone your fork**:
208
+ ```bash
209
+ git clone https://github.com/yourusername/py-eagle-cooler.git
210
+ cd py-eagle-cooler
211
+ ```
212
+ 3. **Install development dependencies**:
213
+ ```bash
214
+ uv sync --dev
215
+ ```
216
+ 4. **Make your changes**
217
+ 5. **Run tests** (when available):
218
+ ```bash
219
+ uv run pytest
220
+ ```
221
+ 6. **Submit a pull request**
222
+
223
+ ### Development Setup
224
+
225
+ ```bash
226
+ # Clone the repository
227
+ git clone https://github.com/ZackaryW/py-eagle-cooler.git
228
+ cd py-eagle-cooler
229
+
230
+ # Install with development dependencies
231
+ uv sync --dev
232
+
233
+ # Run the package in development mode
234
+ uv run python -m eagle_cooler
235
+ ```
236
+
237
+ ## 📜 License
238
+
239
+ This project is licensed under the same terms as Power Eagle.
240
+
241
+ ---
242
+
243
+ <p align="center">
244
+ <sub>Built with ❤️ for the Eagle.cool community</sub>
245
+ </p>
eagle_cooler-0.1.0/README.md ADDED
@@ -0,0 +1,235 @@
1
+ # Eagle Cooler 🦅❄️
2
+
3
+ [![PyPI version](https://badge.fury.io/py/eagle-cooler.svg)](https://badge.fury.io/py/eagle-cooler)
4
+ [![Python Support](https://img.shields.io/pypi/pyversions/eagle-cooler.svg)](https://pypi.org/project/eagle-cooler/)
5
+ [![License](https://img.shields.io/github/license/ZackaryW/py-eagle-cooler.svg)](LICENSE)
6
+
7
+ A modern Python wrapper for the [Eagle.cool](https://eagle.cool) HTTP API. Works independently with Eagle's web API or seamlessly integrates with the Power Eagle plugin system for enhanced functionality.
8
+
9
+ ## ✨ Features
10
+
11
+ - 🚀 **Complete API Coverage** - Full implementation of Eagle's HTTP API
12
+ - 🔐 **Flexible Authentication** - Works standalone with manual token setup or automatically with Power Eagle
13
+ - 📝 **Type Hints** - Better development experience with full type annotations
14
+ - 🎯 **Easy-to-use Interface** - Clean, class-based API design
15
+ - ⚡ **Modern Python** - Built for Python 3.13+ with modern best practices
16
+ - 🔌 **Plugin Ready** - Enhanced integration with Power Eagle plugin ecosystem
17
+ - 🏠 **Standalone Ready** - Can work independently with just Eagle's web API
18
+
19
+ ## 📦 Installation
20
+
21
+ Install the latest stable version from PyPI:
22
+
23
+ ```bash
24
+ # Using uv (recommended)
25
+ uv add eagle-cooler
26
+
27
+ # Using pip
28
+ pip install eagle-cooler
29
+
30
+ # For development
31
+ git clone https://github.com/ZackaryW/py-eagle-cooler.git
32
+ cd py-eagle-cooler
33
+ uv sync --dev
34
+ ```
35
+
36
+ ## 🚀 Quick Start
37
+
38
+ ### Standalone Usage (Web API Only)
39
+
40
+ For basic functionality using Eagle's HTTP API directly:
41
+
42
+ ```python
43
+ from eagle_cooler import EagleWebApi
44
+
45
+ # Get application info
46
+ app_info = EagleWebApi.application.info()
47
+ print(f"Eagle version: {app_info['version']}")
48
+
49
+ # List folders
50
+ folders = EagleWebApi.folder.list()
51
+ print(f"Found {len(folders)} folders")
52
+
53
+ # Create a new folder
54
+ new_folder = EagleWebApi.folder.create("My New Folder")
55
+ print(f"Created: {new_folder['name']}")
56
+
57
+ # List items with filters
58
+ items = EagleWebApi.item.list(limit=10, ext="jpg")
59
+ print(f"Found {len(items)} JPG images")
60
+
61
+ # Add item from URL
62
+ result = EagleWebApi.item.add_from_url(
63
+ url="https://example.com/image.jpg",
64
+ name="Example Image",
65
+ tags=["example", "test"]
66
+ )
67
+
68
+ # Add item from local file
69
+ local_item = EagleWebApi.item.add_from_path(
70
+ path="/path/to/image.jpg",
71
+ name="Local Image",
72
+ tags=["local"]
73
+ )
74
+ ```
75
+
76
+ ### Power Eagle Integration (Enhanced Features)
77
+
78
+ When running in a Power Eagle context, access to enhanced features:
79
+
80
+ ```python
81
+ # In a Power Eagle Python script
82
+ from eagle_cooler import eagleContext, EagleCallback
83
+
84
+ # Get selected items and folders from Power Eagle context
85
+ selected_items = eagleContext.get_selected_items()
86
+ selected_folders = eagleContext.get_selected_folders()
87
+
88
+ # Get just the IDs if needed
89
+ selected_item_ids = eagleContext.get_selected_item_ids()
90
+ selected_folder_ids = eagleContext.get_selected_folder_ids()
91
+
92
+ # Use callback system for advanced plugin operations
93
+ # (extensive callback API available for plugin development)
94
+ ```
95
+
96
+ ## 📚 API Reference
97
+
98
+ ### 🏢 Application
99
+ - `EagleWebApi.application.info()` - Get application information
100
+
101
+ ### 📁 Folders
102
+ - `EagleWebApi.folder.create(name, parent_id=None)` - Create folder
103
+ - `EagleWebApi.folder.rename(folder_id, new_name)` - Rename folder
104
+ - `EagleWebApi.folder.update(folder_id, new_name=None, new_description=None, new_color=None)` - Update folder properties
105
+ - `EagleWebApi.folder.list()` - List all folders
106
+ - `EagleWebApi.folder.list_recent()` - List recent folders
107
+
108
+ ### 📚 Library
109
+ - `EagleWebApi.library.info()` - Get library information
110
+ - `EagleWebApi.library.history()` - Get library history
111
+ - `EagleWebApi.library.switch(library_path)` - Switch to different library
112
+ - `EagleWebApi.library.icon(library_path)` - Get library icon
113
+
114
+ ### 🖼️ Items
115
+ - `EagleWebApi.item.list(limit=None, offset=None, order_by=None, keyword=None, ext=None, tags=None, folders=None)` - List items with filters
116
+ - `EagleWebApi.item.get_info(item_id)` - Get item details
117
+ - `EagleWebApi.item.get_thumbnail(item_id)` - Get item thumbnail
118
+ - `EagleWebApi.item.update(item_id, tags=None, annotation=None, url=None, star=None)` - Update item properties
119
+ - `EagleWebApi.item.add_from_url(url, name, website=None, tags=None, star=None, annotation=None, modification_time=None, folder_id=None, headers=None)` - Add item from URL
120
+ - `EagleWebApi.item.add_from_path(path, name, website=None, annotation=None, tags=None, folder_id=None)` - Add item from file path
121
+ - `EagleWebApi.item.add_from_urls(items, folder_id=None)` - Add multiple items from URLs
122
+ - `EagleWebApi.item.add_bookmark(url, name, base64=None, tags=None, modification_time=None, folder_id=None)` - Add bookmark
123
+ - `EagleWebApi.item.move_to_trash(item_ids)` - Move items to trash
124
+ - `EagleWebApi.item.refresh_thumbnail(item_id)` - Refresh thumbnail
125
+ - `EagleWebApi.item.refresh_palette(item_id)` - Refresh color palette
126
+
127
+ ### 🔧 Context (Power Eagle Mode)
128
+ - `eagleContext.get_selected_item_ids()` - Get selected item IDs from Power Eagle context
129
+ - `eagleContext.get_selected_folder_ids()` - Get selected folder IDs from Power Eagle context
130
+ - `eagleContext.get_selected_items(throw=False)` - Get selected items as typed ItemModel objects
131
+ - `eagleContext.get_selected_folders()` - Get selected folders as typed FolderModel objects
132
+
133
+ ### 📞 Callbacks (Power Eagle Plugins)
134
+ - `EagleCallback` - Callback system for Power Eagle plugin integration (extensive API available)
135
+
136
+ ## 🔌 Usage Modes
137
+
138
+ Eagle Cooler supports two usage modes:
139
+
140
+ ### 🏠 Standalone Mode (Web API)
141
+ - **Limited Capacity**: Basic API operations through Eagle's HTTP interface
142
+ - **Manual Setup**: Requires Eagle application running with HTTP API enabled
143
+ - **Authentication**: Uses direct API calls (no token management)
144
+ - **Features**: Core operations like listing, creating folders, basic item management
145
+
146
+ ### 🚀 Power Eagle Mode (Enhanced)
147
+ - **Full Capacity**: Complete feature set with enhanced functionality
148
+ - **Automatic Setup**: Token and context management handled automatically
149
+ - **Authentication**: Seamless integration with Power Eagle's security context
150
+ - **Features**: All core operations plus callbacks, advanced file operations, and plugin ecosystem integration
151
+
152
+ ```python
153
+ # Standalone mode example
154
+ from eagle_cooler import EagleWebApi
155
+
156
+ # Basic operations available
157
+ folders = EagleWebApi.folder.list()
158
+
159
+ # Power Eagle mode example (when POWEREAGLE_CONTEXT is available)
160
+ from eagle_cooler import EagleWebApi, eagleContext, EagleCallback
161
+
162
+ # Enhanced operations available:
163
+ # 1. Automatic token management
164
+ folders = EagleWebApi.folder.list()
165
+
166
+ # 2. Access to Power Eagle context with typed models
167
+ selected_items = eagleContext.get_selected_items() # Returns list[ItemModel]
168
+ selected_folders = eagleContext.get_selected_folders() # Returns list[FolderModel]
169
+
170
+ # 3. Callback system for advanced plugin operations
171
+ if selected_items:
172
+ for item in selected_items:
173
+ print(f"Selected item: {item['name']} ({item['ext']})")
174
+ # Use callback system to interact with Power Eagle host
175
+ # (extensive callback API available - see METHODS_WITH_RETURN_VALUES)
176
+ ```
177
+
178
+ ## ⚙️ Requirements
179
+
180
+ - **Python**: >= 3.13
181
+ - **Eagle.cool**: Application running with API access enabled
182
+ - **Dependencies**: `requests >= 2.25.0`
183
+ - **For Power Eagle**: `POWEREAGLE_CONTEXT` environment variable set
184
+
185
+ ### Setup Eagle API Access
186
+
187
+ 1. Open Eagle.cool application
188
+ 2. Go to **Preferences** → **Plugin**
189
+ 3. Enable **HTTP API**
190
+ 4. Note the API port (default: 41595)
191
+
192
+ ## 🤝 Contributing
193
+
194
+ We welcome contributions! Here's how to get started:
195
+
196
+ 1. **Fork the repository**
197
+ 2. **Clone your fork**:
198
+ ```bash
199
+ git clone https://github.com/yourusername/py-eagle-cooler.git
200
+ cd py-eagle-cooler
201
+ ```
202
+ 3. **Install development dependencies**:
203
+ ```bash
204
+ uv sync --dev
205
+ ```
206
+ 4. **Make your changes**
207
+ 5. **Run tests** (when available):
208
+ ```bash
209
+ uv run pytest
210
+ ```
211
+ 6. **Submit a pull request**
212
+
213
+ ### Development Setup
214
+
215
+ ```bash
216
+ # Clone the repository
217
+ git clone https://github.com/ZackaryW/py-eagle-cooler.git
218
+ cd py-eagle-cooler
219
+
220
+ # Install with development dependencies
221
+ uv sync --dev
222
+
223
+ # Run the package in development mode
224
+ uv run python -m eagle_cooler
225
+ ```
226
+
227
+ ## 📜 License
228
+
229
+ This project is licensed under the same terms as Power Eagle.
230
+
231
+ ---
232
+
233
+ <p align="center">
234
+ <sub>Built with ❤️ for the Eagle.cool community</sub>
235
+ </p>
eagle_cooler-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,19 @@
1
+ [project]
2
+ name = "eagle-cooler"
3
+ version = "0.1.0"
4
+ description = "Python library for bridging Eagle js environment"
5
+ readme = "README.md"
6
+ authors = [
7
+ { name = "ZackaryW", email = "gitzackw@gmail.com" }
8
+ ]
9
+ requires-python = ">=3.13"
10
+ dependencies = [
11
+ "requests>=2.25.0"
12
+ ]
13
+
14
+ [project.scripts]
15
+ eagle-cooler = "eagle_cooler:main"
16
+
17
+ [build-system]
18
+ requires = ["uv_build>=0.8.17,<0.9.0"]
19
+ build-backend = "uv_build"
eagle_cooler-0.1.0/src/eagle_cooler/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ from eagle_cooler.context import eagleContext
2
+ from .webapi import EagleWebApi
3
+ from .callback import EagleCallback, METHODS_WITH_RETURN_VALUES
4
+
5
+ __all__ = ["eagleContext", "EagleWebApi", "EagleCallback", "METHODS_WITH_RETURN_VALUES"]