eagle-cooler 0.1.0__py3-none-any.whl

eagle_cooler/context.py

@@ -0,0 +1,46 @@
+
+from eagle_cooler import EagleWebApi
+
+from eagle_cooler.model import FolderModel, ItemModel
+from .core import EagleCoolerCore
+
+class EagleContext:
+    def get_selected_folder_ids(self) -> list[str]:
+        """Get selected folder IDs from the context if available"""
+        return EagleCoolerCore.selected_folder_ids()
+
+    def get_selected_item_ids(self) -> list[str]:
+        """Get selected item IDs from the context if available"""
+        return EagleCoolerCore.selected_item_ids()
+    
+    def get_selected_folders(self) -> list[FolderModel]:
+        folder_ids = self.get_selected_folder_ids()
+        if not folder_ids:
+            return []
+        
+        all_folders = EagleWebApi.folder.list()
+        return [folder for folder in all_folders if folder['id'] in folder_ids]
+
+    def get_selected_items(self, throw : bool = False) -> list[ItemModel]:
+        item_ids = self.get_selected_item_ids()
+        if not item_ids:
+            return []
+
+        selected_items = []    
+        for selected_item in item_ids:
+            try:
+                item_info = EagleWebApi.item.get_info(selected_item)
+                if item_info:
+                    selected_items.append(item_info)
+                    continue
+            except Exception as e:
+                if throw:
+                    raise e
+                
+                continue
+
+        return selected_items
+
+eagleContext = EagleContext()
+            
+__all__ = ["eagleContext"]

eagle_cooler/core.py

@@ -0,0 +1,55 @@
+import json
+import os
+import requests
+from typing import Optional
+
+class EagleCoolerCore:
+    __fullBridgeContext = None
+    __token = None
+    __applicationInfo = None
+    
+    @classmethod
+    def __load(cls):
+        # Load context when class is defined
+        try:
+            context_env = os.environ.get("POWEREAGLE_CONTEXT")
+            if context_env:
+                cls.__fullBridgeContext = json.loads(context_env)
+                cls.__token = cls.__fullBridgeContext.get("apiToken")
+                return  # Successfully loaded, exit early
+        except Exception as e:
+            print(f"Failed to load Power Eagle context: {e}")
+          
+        # Fallback to Eagle API if Power Eagle context failed
+        try:
+            response = requests.get("http://localhost:41595/api/application/info", timeout=5)
+            if response.status_code == 200:
+                cls.__applicationInfo = response.json()
+                token = cls.__applicationInfo.get("data", {}).get("preferences", {}).get("developer", {}).get("apiToken")
+                if token:
+                    cls.__token = token
+        except Exception as api_error:
+            print(f"Failed to get token from Eagle API: {api_error}")
+            cls.__token = None
+
+    @classmethod
+    def token(cls) -> Optional[str]:
+        """Get API token"""
+        return cls.__token
+    
+    @classmethod
+    def selected_item_ids(cls) -> Optional[list]:
+        """Get selected items from the context if available"""
+        if cls.__fullBridgeContext:
+            return cls.__fullBridgeContext.get("selected").get("items")
+        return None
+    
+    @classmethod
+    def selected_folder_ids(cls) -> Optional[list]:
+        """Get selected folders from the context if available"""
+        if cls.__fullBridgeContext:
+            return cls.__fullBridgeContext.get("selected").get("folders")
+        return None
+    
+EagleCoolerCore._EagleCoolerCore__load()
+

eagle_cooler/model.py

@@ -0,0 +1,48 @@
+from typing import TypedDict, Any
+
+
+class FolderModel(TypedDict):
+    """TypedDict model for Eagle folder structure"""
+    id: str
+    name: str
+    description: str
+    children: list[str]  # List of child folder IDs
+    modificationTime: int  # Unix timestamp in milliseconds
+    tags: list[str]
+    extendTags: list[str]
+    pinyin: str
+    password: str
+    passwordTips: str
+
+
+class OCRModel(TypedDict):
+    """TypedDict model for OCR data"""
+    done: str
+    text: str
+
+
+class DetectionModel(TypedDict):
+    """TypedDict model for object detection data"""
+    done: str
+    objects: list[Any]  # Object detection results
+
+
+class ItemModel(TypedDict):
+    """TypedDict model for Eagle item structure"""
+    id: str
+    name: str
+    size: int  # File size in bytes
+    btime: int  # Birth time (creation time) in milliseconds
+    mtime: int  # File modification time in milliseconds
+    ext: str  # File extension
+    tags: list[str]
+    folders: list[str]  # List of folder IDs this item belongs to
+    isDeleted: bool
+    url: str
+    annotation: str
+    modificationTime: int  # Eagle modification time in milliseconds
+    noPreview: bool
+    lastModified: int  # Last modified time in milliseconds
+    ocr: OCRModel
+    detection: DetectionModel
+

eagle_cooler/webapi.py

@@ -0,0 +1,246 @@
+
+
+import requests
+from typing import Optional, Dict, Any, List
+from .core import EagleCoolerCore
+
+
+class EagleWebApi:
+    """Python implementation of Eagle API client for HTTP requests to Eagle application"""
+    
+    _token: Optional[str] = None
+
+    @classmethod
+    def _make_request(cls, path: str, method: str = "GET", data: Optional[Dict[str, Any]] = None, 
+                     params: Optional[Dict[str, Any]] = None) -> Any:
+        """Makes internal HTTP request to Eagle API"""
+        token = EagleCoolerCore.token()
+        if not token:
+            raise Exception("No API token found")
+            
+        url = f"http://localhost:41595/api/{path}"
+        
+        # Add token to params
+        if params is None:
+            params = {}
+        params["token"] = token
+        
+        # Remove None values from params and data
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+        if data:
+            data = {k: v for k, v in data.items() if v is not None}
+            
+        try:
+            if method.upper() == "POST":
+                response = requests.post(url, params=params, json=data)
+            else:
+                response = requests.get(url, params=params)
+                
+            response.raise_for_status()
+            result = response.json()
+            return result.get("data")
+        except Exception as e:
+            print(f"Request failed: {e}")
+            raise e
+    
+    class _Application:
+        """_Application-related API methods"""
+        
+        @staticmethod
+        def info() -> Any:
+            """Gets application information"""
+            return EagleWebApi._make_request("application/info")
+    
+    class _Folder:
+        """_Folder-related API methods"""
+        
+        @staticmethod
+        def create(name: str, parent_id: Optional[str] = None) -> Any:
+            """Creates a new folder"""
+            return EagleWebApi._make_request("folder/create", "POST", {
+                "folderName": name,
+                "parent": parent_id
+            })
+        
+        @staticmethod
+        def rename(folder_id: str, new_name: str) -> Any:
+            """Renames a folder"""
+            return EagleWebApi._make_request("folder/rename", "POST", {
+                "folderId": folder_id,
+                "newName": new_name
+            })
+        
+        @staticmethod
+        def update(folder_id: str, new_name: Optional[str] = None, 
+                  new_description: Optional[str] = None, new_color: Optional[str] = None) -> Any:
+            """Updates folder properties"""
+            return EagleWebApi._make_request("folder/update", "POST", {
+                "folderId": folder_id,
+                "newName": new_name,
+                "newDescription": new_description,
+                "newColor": new_color
+            })
+        
+        @staticmethod
+        def list() -> Any:
+            """Lists all folders"""
+            return EagleWebApi._make_request("folder/list")
+        
+        @staticmethod
+        def list_recent() -> Any:
+            """Lists recent folders"""
+            return EagleWebApi._make_request("folder/listRecent")
+    
+    class _Library:
+        """_Library-related API methods"""
+        
+        @staticmethod
+        def info() -> Any:
+            """Gets library information"""
+            return EagleWebApi._make_request("library/info")
+        
+        @staticmethod
+        def history() -> Any:
+            """Gets library history"""
+            return EagleWebApi._make_request("library/history")
+        
+        @staticmethod
+        def switch(library_path: str) -> Any:
+            """Switches to a different library"""
+            return EagleWebApi._make_request("library/switch", "POST", {
+                "libraryPath": library_path
+            })
+        
+        @staticmethod
+        def icon(library_path: str) -> Any:
+            """Gets library icon"""
+            return EagleWebApi._make_request("library/icon", params={
+                "libraryPath": library_path
+            })
+    
+    class _Item:
+        """_Item-related API methods"""
+        
+        @staticmethod
+        def update(item_id: str, tags: Optional[List[str]] = None, annotation: Optional[str] = None,
+                  url: Optional[str] = None, star: Optional[int] = None) -> Any:
+            """Updates item properties"""
+            return EagleWebApi._make_request("item/update", "POST", {
+                "id": item_id,
+                "tags": tags,
+                "annotation": annotation,
+                "url": url,
+                "star": star
+            })
+        
+        @staticmethod
+        def refresh_thumbnail(item_id: str) -> Any:
+            """Refreshes item thumbnail"""
+            return EagleWebApi._make_request("item/refreshThumbnail", "POST", {
+                "id": item_id
+            })
+        
+        @staticmethod
+        def refresh_palette(item_id: str) -> Any:
+            """Refreshes item color palette"""
+            return EagleWebApi._make_request("item/refreshPalette", "POST", {
+                "id": item_id
+            })
+        
+        @staticmethod
+        def move_to_trash(item_ids: List[str]) -> Any:
+            """Moves items to trash"""
+            return EagleWebApi._make_request("item/moveToTrash", "POST", {
+                "itemIds": item_ids
+            })
+        
+        @staticmethod
+        def list(limit: Optional[int] = None, offset: Optional[int] = None,
+                order_by: Optional[str] = None, keyword: Optional[str] = None,
+                ext: Optional[str] = None, tags: Optional[List[str]] = None,
+                folders: Optional[List[str]] = None) -> Any:
+            """Lists items with filters"""
+            return EagleWebApi._make_request("item/list", params={
+                "limit": limit,
+                "offset": offset,
+                "orderBy": order_by,
+                "keyword": keyword,
+                "ext": ext,
+                "tags": tags,
+                "folders": folders
+            })
+        
+        @staticmethod
+        def get_thumbnail(item_id: str) -> Any:
+            """Gets item thumbnail"""
+            return EagleWebApi._make_request("item/thumbnail", params={
+                "id": item_id
+            })
+        
+        @staticmethod
+        def get_info(item_id: str) -> Any:
+            """Gets item information"""
+            return EagleWebApi._make_request("item/info", params={
+                "id": item_id
+            })
+        
+        @staticmethod
+        def add_bookmark(url: str, name: str, base64: Optional[str] = None,
+                        tags: Optional[List[str]] = None, modification_time: Optional[int] = None,
+                        folder_id: Optional[str] = None) -> Any:
+            """Adds bookmark item"""
+            return EagleWebApi._make_request("item/addBookmark", "POST", {
+                "url": url,
+                "name": name,
+                "base64": base64,
+                "tags": tags,
+                "modificationTime": modification_time,
+                "folderId": folder_id
+            })
+        
+        @staticmethod
+        def add_from_url(url: str, name: str, website: Optional[str] = None,
+                        tags: Optional[List[str]] = None, star: Optional[int] = None,
+                        annotation: Optional[str] = None, modification_time: Optional[int] = None,
+                        folder_id: Optional[str] = None, headers: Optional[Dict[str, Any]] = None) -> Any:
+            """Adds item from URL"""
+            return EagleWebApi._make_request("item/addFromUrl", "POST", {
+                "url": url,
+                "name": name,
+                "website": website,
+                "tags": tags,
+                "star": star,
+                "annotation": annotation,
+                "modificationTime": modification_time,
+                "folderId": folder_id,
+                "headers": headers
+            })
+        
+        @staticmethod
+        def add_from_path(path: str, name: str, website: Optional[str] = None,
+                         annotation: Optional[str] = None, tags: Optional[List[str]] = None,
+                         folder_id: Optional[str] = None) -> Any:
+            """Adds item from file path"""
+            return EagleWebApi._make_request("item/addFromPath", "POST", {
+                "path": path,
+                "name": name,
+                "website": website,
+                "annotation": annotation,
+                "tags": tags,
+                "folderId": folder_id
+            })
+        
+        @staticmethod
+        def add_from_urls(items: List[Dict[str, Any]], folder_id: Optional[str] = None) -> Any:
+            """Adds multiple items from URLs"""
+            return EagleWebApi._make_request("item/addFromURLs", "POST", {
+                "items": items,
+                "folderId": folder_id
+            })
+    
+    # Create class-level aliases for easier access
+    application = _Application()
+    folder = _Folder()
+    library = _Library()
+    item = _Item()

eagle_cooler-0.1.0.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.3
+Name: eagle-cooler
+Version: 0.1.0
+Summary: Python library for bridging Eagle js environment
+Author: ZackaryW
+Author-email: ZackaryW <gitzackw@gmail.com>
+Requires-Dist: requests>=2.25.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Eagle Cooler 🦅❄️
+
+[![PyPI version](https://badge.fury.io/py/eagle-cooler.svg)](https://badge.fury.io/py/eagle-cooler)
+[![Python Support](https://img.shields.io/pypi/pyversions/eagle-cooler.svg)](https://pypi.org/project/eagle-cooler/)
+[![License](https://img.shields.io/github/license/ZackaryW/py-eagle-cooler.svg)](LICENSE)
+
+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.
+
+## ✨ Features
+
+- 🚀 **Complete API Coverage** - Full implementation of Eagle's HTTP API
+- 🔐 **Flexible Authentication** - Works standalone with manual token setup or automatically with Power Eagle
+- 📝 **Type Hints** - Better development experience with full type annotations
+- 🎯 **Easy-to-use Interface** - Clean, class-based API design
+- ⚡ **Modern Python** - Built for Python 3.13+ with modern best practices
+- 🔌 **Plugin Ready** - Enhanced integration with Power Eagle plugin ecosystem
+- 🏠 **Standalone Ready** - Can work independently with just Eagle's web API
+
+## 📦 Installation
+
+Install the latest stable version from PyPI:
+
+```bash
+# Using uv (recommended)
+uv add eagle-cooler
+
+# Using pip
+pip install eagle-cooler
+
+# For development
+git clone https://github.com/ZackaryW/py-eagle-cooler.git
+cd py-eagle-cooler
+uv sync --dev
+```
+
+## 🚀 Quick Start
+
+### Standalone Usage (Web API Only)
+
+For basic functionality using Eagle's HTTP API directly:
+
+```python
+from eagle_cooler import EagleWebApi
+
+# Get application info
+app_info = EagleWebApi.application.info()
+print(f"Eagle version: {app_info['version']}")
+
+# List folders
+folders = EagleWebApi.folder.list()
+print(f"Found {len(folders)} folders")
+
+# Create a new folder
+new_folder = EagleWebApi.folder.create("My New Folder")
+print(f"Created: {new_folder['name']}")
+
+# List items with filters
+items = EagleWebApi.item.list(limit=10, ext="jpg")
+print(f"Found {len(items)} JPG images")
+
+# Add item from URL
+result = EagleWebApi.item.add_from_url(
+    url="https://example.com/image.jpg",
+    name="Example Image",
+    tags=["example", "test"]
+)
+
+# Add item from local file
+local_item = EagleWebApi.item.add_from_path(
+    path="/path/to/image.jpg",
+    name="Local Image",
+    tags=["local"]
+)
+```
+
+### Power Eagle Integration (Enhanced Features)
+
+When running in a Power Eagle context, access to enhanced features:
+
+```python
+# In a Power Eagle Python script
+from eagle_cooler import eagleContext, EagleCallback
+
+# Get selected items and folders from Power Eagle context
+selected_items = eagleContext.get_selected_items()
+selected_folders = eagleContext.get_selected_folders()
+
+# Get just the IDs if needed
+selected_item_ids = eagleContext.get_selected_item_ids()
+selected_folder_ids = eagleContext.get_selected_folder_ids()
+
+# Use callback system for advanced plugin operations
+# (extensive callback API available for plugin development)
+```
+
+## 📚 API Reference
+
+### 🏢 Application
+- `EagleWebApi.application.info()` - Get application information
+
+### 📁 Folders
+- `EagleWebApi.folder.create(name, parent_id=None)` - Create folder
+- `EagleWebApi.folder.rename(folder_id, new_name)` - Rename folder
+- `EagleWebApi.folder.update(folder_id, new_name=None, new_description=None, new_color=None)` - Update folder properties
+- `EagleWebApi.folder.list()` - List all folders
+- `EagleWebApi.folder.list_recent()` - List recent folders
+
+### 📚 Library
+- `EagleWebApi.library.info()` - Get library information
+- `EagleWebApi.library.history()` - Get library history
+- `EagleWebApi.library.switch(library_path)` - Switch to different library
+- `EagleWebApi.library.icon(library_path)` - Get library icon
+
+### 🖼️ Items
+- `EagleWebApi.item.list(limit=None, offset=None, order_by=None, keyword=None, ext=None, tags=None, folders=None)` - List items with filters
+- `EagleWebApi.item.get_info(item_id)` - Get item details
+- `EagleWebApi.item.get_thumbnail(item_id)` - Get item thumbnail
+- `EagleWebApi.item.update(item_id, tags=None, annotation=None, url=None, star=None)` - Update item properties
+- `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
+- `EagleWebApi.item.add_from_path(path, name, website=None, annotation=None, tags=None, folder_id=None)` - Add item from file path
+- `EagleWebApi.item.add_from_urls(items, folder_id=None)` - Add multiple items from URLs
+- `EagleWebApi.item.add_bookmark(url, name, base64=None, tags=None, modification_time=None, folder_id=None)` - Add bookmark
+- `EagleWebApi.item.move_to_trash(item_ids)` - Move items to trash
+- `EagleWebApi.item.refresh_thumbnail(item_id)` - Refresh thumbnail
+- `EagleWebApi.item.refresh_palette(item_id)` - Refresh color palette
+
+### 🔧 Context (Power Eagle Mode)
+- `eagleContext.get_selected_item_ids()` - Get selected item IDs from Power Eagle context
+- `eagleContext.get_selected_folder_ids()` - Get selected folder IDs from Power Eagle context  
+- `eagleContext.get_selected_items(throw=False)` - Get selected items as typed ItemModel objects
+- `eagleContext.get_selected_folders()` - Get selected folders as typed FolderModel objects
+
+### 📞 Callbacks (Power Eagle Plugins)
+- `EagleCallback` - Callback system for Power Eagle plugin integration (extensive API available)
+
+## 🔌 Usage Modes
+
+Eagle Cooler supports two usage modes:
+
+### 🏠 Standalone Mode (Web API)
+- **Limited Capacity**: Basic API operations through Eagle's HTTP interface
+- **Manual Setup**: Requires Eagle application running with HTTP API enabled
+- **Authentication**: Uses direct API calls (no token management)
+- **Features**: Core operations like listing, creating folders, basic item management
+
+### 🚀 Power Eagle Mode (Enhanced)
+- **Full Capacity**: Complete feature set with enhanced functionality
+- **Automatic Setup**: Token and context management handled automatically
+- **Authentication**: Seamless integration with Power Eagle's security context
+- **Features**: All core operations plus callbacks, advanced file operations, and plugin ecosystem integration
+
+```python
+# Standalone mode example
+from eagle_cooler import EagleWebApi
+
+# Basic operations available
+folders = EagleWebApi.folder.list()
+
+# Power Eagle mode example (when POWEREAGLE_CONTEXT is available)
+from eagle_cooler import EagleWebApi, eagleContext, EagleCallback
+
+# Enhanced operations available:
+# 1. Automatic token management
+folders = EagleWebApi.folder.list()
+
+# 2. Access to Power Eagle context with typed models
+selected_items = eagleContext.get_selected_items()  # Returns list[ItemModel]
+selected_folders = eagleContext.get_selected_folders()  # Returns list[FolderModel]
+
+# 3. Callback system for advanced plugin operations
+if selected_items:
+    for item in selected_items:
+        print(f"Selected item: {item['name']} ({item['ext']})")
+        # Use callback system to interact with Power Eagle host
+        # (extensive callback API available - see METHODS_WITH_RETURN_VALUES)
+```
+
+## ⚙️ Requirements
+
+- **Python**: >= 3.13
+- **Eagle.cool**: Application running with API access enabled
+- **Dependencies**: `requests >= 2.25.0`
+- **For Power Eagle**: `POWEREAGLE_CONTEXT` environment variable set
+
+### Setup Eagle API Access
+
+1. Open Eagle.cool application
+2. Go to **Preferences** → **Plugin**
+3. Enable **HTTP API**
+4. Note the API port (default: 41595)
+
+## 🤝 Contributing
+
+We welcome contributions! Here's how to get started:
+
+1. **Fork the repository**
+2. **Clone your fork**:
+   ```bash
+   git clone https://github.com/yourusername/py-eagle-cooler.git
+   cd py-eagle-cooler
+   ```
+3. **Install development dependencies**:
+   ```bash
+   uv sync --dev
+   ```
+4. **Make your changes**
+5. **Run tests** (when available):
+   ```bash
+   uv run pytest
+   ```
+6. **Submit a pull request**
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/ZackaryW/py-eagle-cooler.git
+cd py-eagle-cooler
+
+# Install with development dependencies
+uv sync --dev
+
+# Run the package in development mode
+uv run python -m eagle_cooler
+```
+
+## 📜 License
+
+This project is licensed under the same terms as Power Eagle.
+
+---
+
+<p align="center">
+  <sub>Built with ❤️ for the Eagle.cool community</sub>
+</p>

eagle_cooler-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+eagle_cooler/__init__.py,sha256=DJU-5HsVAnYftHWy4Ue6HCSt_U4Ex-j7n8UOQzxBX0I,231
+eagle_cooler/callback.py,sha256=Eg6hZAtr6uKVES7xgV3hoTejMqtRFbu8qM9KWr7tyNo,36119
+eagle_cooler/context.py,sha256=ICNi8vfep2UH9TKMniKYy3IvHgbMGynyVJhWPmeV-Ik,1462
+eagle_cooler/core.py,sha256=JXBf3hUgPpWKfPWyAn7EE60nKPR7QSfk7w8y9y0PA8o,1945
+eagle_cooler/model.py,sha256=BSjxgPw9_5t7J5Lcjt2VaH6KSdz21MgKemGGyCKZXAY,1257
+eagle_cooler/webapi.py,sha256=COCCh1o_9saf5huCV7AGvoDSLouafVe3aor5wUq1uOQ,9091
+eagle_cooler-0.1.0.dist-info/WHEEL,sha256=Pi5uDq5Fdo_Rr-HD5h9BiPn9Et29Y9Sh8NhcJNnFU1c,79
+eagle_cooler-0.1.0.dist-info/entry_points.txt,sha256=pDVCjWW7abbqDCWZdMaowSdiRl4TkDQ5eTajXU1YEck,52
+eagle_cooler-0.1.0.dist-info/METADATA,sha256=B1YbxPqYG1NfYXDn1hahC9PFnVql5cbS614YZIBk-ck,8582
+eagle_cooler-0.1.0.dist-info/RECORD,,

eagle_cooler-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.17
+Root-Is-Purelib: true
+Tag: py3-none-any

eagle_cooler-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+eagle-cooler = eagle_cooler:main
+