python-fx 0.3.2__tar.gz → 0.4.0__tar.gz

{python_fx-0.3.2 → python_fx-0.4.0}/CHANGELOG.md

@@ -6,6 +6,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Changed
+- Allow dynamic versions for dependency
+- Remove support for python 3.8
 
 ## [0.3.2] - 2024-08-12
 ### Changed

python_fx-0.4.0/CLAUDE.md

@@ -0,0 +1,121 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Pyfx is a Python-native JSON viewer TUI (Terminal User Interface) inspired by fx. It provides an interactive terminal-based interface for browsing and querying JSON data with JSONPath support.
+
+## Development Commands
+
+### Core Development Workflow
+- `make install` - Full build pipeline: clean, lint, test, build, and install
+- `make build` - Build the project (includes clean, lint, test)
+- `make test` - Run all tests via tox (includes clean, lint)
+- `make lint` - Format code with autopep8
+- `make clean` - Remove build artifacts
+
+### Testing
+- `tox` - Run tests across multiple Python versions (3.8-3.11)
+- `tox -e py311` - Run tests for specific Python version
+- `tox -e style_check` - Run flake8 style checks
+- `pytest` - Run tests directly (after installing dev dependencies)
+- `pytest --cov=pyfx --cov-report=term-missing` - Run tests with coverage
+
+### Dependency Management
+- `pipenv install --dev` - Install development dependencies
+- `pipenv requirements > requirements.txt` - Update requirements.txt
+- `make lock` - Generate both requirements.txt and dev-requirements.txt
+
+### Installation and Running
+- `pip install python-fx` - Install from PyPI
+- `pyfx data.json` - Open JSON file
+- `cat data.json | pyfx` - Read JSON from pipe
+- `pyfx -x` - Read JSON from clipboard
+- `pyfx --debug` - Enable debug logging
+
+## Architecture
+
+### High-Level Architecture
+Pyfx follows an MVC-like pattern with additional service and mediator layers:
+
+- **Model** (`src/pyfx/model/`) - Data processing and JSONPath queries
+- **View** (`src/pyfx/view/`) - UI components built on urwid
+- **Service** (`src/pyfx/service/`) - Business logic dispatcher and client
+- **Config** (`src/pyfx/config/`) - Configuration management (themes, keymaps)
+
+### Key Components
+
+#### App Layer (`app.py`)
+- `PyfxApp` - Main application entry point and dependency injection container
+- Orchestrates all components and manages the UI lifecycle
+
+#### Model Layer
+- `Model` - Handles JSONPath queries and autocomplete functionality
+- `autocomplete/` - JSONPath query autocompletion logic
+
+#### View Layer
+- **Core UI Framework**:
+  - `ViewFrame` - Main window frame management
+  - `ViewMediator` - Component communication mediator
+  - `View` - urwid MainLoop wrapper
+
+- **Components** (`view/components/`):
+  - `JSONBrowser` - Main JSON tree viewer
+  - `QueryBar` - JSONPath query input
+  - `AutoCompletePopUp` - Query autocompletion popup
+  - `HelpPopUp` - Help system
+  - `WarningBar` - Error/warning display
+
+- **JSON Rendering** (`view/json_lib/`):
+  - `JSONNodeFactory` - Creates appropriate widgets for JSON types
+  - `array/`, `object/`, `primitive/` - Type-specific rendering logic
+  - `JSONListBox`, `JSONListWalker` - Core list display widgets
+
+#### Service Layer
+- `Dispatcher` - Message routing between components
+- `Client` - Async operation handling with ThreadPoolExecutor
+
+#### Configuration System
+- YAML-based configuration for themes and keymaps
+- Predefined configurations: `basic`, `emacs`, `vim` keymaps
+- Theme system with customizable colors for JSON types
+
+### Data Flow
+1. CLI loads JSON data from file/pipe/clipboard
+2. `PyfxApp` initializes all components with dependency injection
+3. `Model` processes JSONPath queries against data
+4. `ViewMediator` coordinates communication between UI components
+5. `JSONBrowser` renders JSON using type-specific widgets from `json_lib`
+6. User interactions trigger events through `KeyMapper` and `Dispatcher`
+
+### Key Design Patterns
+- **Mediator Pattern**: `ViewMediator` decouples component communication
+- **Factory Pattern**: `JSONNodeFactory` creates appropriate widgets
+- **Command Pattern**: `Dispatcher` handles service requests
+- **Observer Pattern**: Components register with mediator for updates
+
+## Development Notes
+
+### ANTLR Grammar
+- JSONPath parsing uses ANTLR v4 grammar (`model/common/jsonpath/JSONPath.g4`)
+- Generated parsers are committed to avoid build dependencies
+- ANTLR version must match Python runtime version
+
+### Testing Structure
+- `tests/unit_tests/` - Component-level unit tests
+- `tests/intergration_tests/` - Integration tests for UI interactions
+- `tests/e2e_tests/` - End-to-end CLI testing
+- `tests/fixtures/` - Test data and configuration files
+
+### Urwid Framework
+- Built on urwid for terminal UI
+- Custom widgets extend urwid base classes
+- Keyboard input handled through urwid's event system
+- Screen management for proper terminal control
+
+### Configuration
+- Default config location: `~/.config/pyfx/config.yml`
+- Fallback to: `src/pyfx/config/yaml/config.yml`
+- Supports custom themes and keymaps
+- YAML schema validation with yamale

{python_fx-0.3.2 → python_fx-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: python-fx
-Version: 0.3.2
+Version: 0.4.0
 Summary: A python-native fx-alike terminal JSON viewer.
 Author-email: Yutian Wu <yutianwu@umich.edu>
 License: MIT
@@ -13,32 +13,32 @@ Classifier: Operating System :: POSIX
 Classifier: Operating System :: MacOS :: MacOS X
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Topic :: Utilities
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
-Requires-Dist: antlr4-python3-runtime==4.13.2
-Requires-Dist: asciimatics==1.15.0; python_version >= "3.8"
-Requires-Dist: click==8.1.7; python_version >= "3.7"
-Requires-Dist: dacite==1.8.1; python_version >= "3.6"
-Requires-Dist: first==2.0.2
-Requires-Dist: jsonpath-ng==1.6.1
-Requires-Dist: loguru==0.7.2; python_version >= "3.5"
-Requires-Dist: overrides==7.7.0; python_version >= "3.6"
-Requires-Dist: pillow==10.4.0; python_version >= "3.8"
-Requires-Dist: ply==3.11
-Requires-Dist: pyfiglet==1.0.2; python_version >= "3.9"
-Requires-Dist: pyperclip==1.9.0
-Requires-Dist: pyyaml==6.0.2; python_version >= "3.8"
-Requires-Dist: typing-extensions==4.12.2; python_version >= "3.8"
-Requires-Dist: urwid==2.6.15; python_version >= "3.8"
-Requires-Dist: wcwidth==0.2.13
-Requires-Dist: yamale==5.2.1; python_version >= "3.8"
+Requires-Dist: antlr4-python3-runtime<5,>=4.13
+Requires-Dist: asciimatics<2,>=1.15
+Requires-Dist: click<9,>=8.1.7
+Requires-Dist: first<3,==2.0
+Requires-Dist: dacite<2,==1.8
+Requires-Dist: jsonpath-ng<2,==1.6
+Requires-Dist: loguru<0.8,>=0.7.2
+Requires-Dist: overrides<8,>=7.7.0
+Requires-Dist: pillow<11,>=10.4
+Requires-Dist: ply<4,>=3.11
+Requires-Dist: pyfiglet<2,>=1.0
+Requires-Dist: pyperclip>=1.9
+Requires-Dist: pyyaml<7,>=6.0.2
+Requires-Dist: typing-extensions<5,>=4.12.2
+Requires-Dist: urwid<3,>=2.6
+Requires-Dist: wcwidth<0.3,>=0.2.13
+Requires-Dist: yamale<6,>=5.2
+Dynamic: license-file
 
 # Pyfx
 ![Build Status](https://github.com/cielong/pyfx/actions/workflows/ci.yml/badge.svg?branch=main)
 ![Documentation Status](https://readthedocs.org/projects/python-fx/badge/?version=latest)
 ![PyPI version](https://badge.fury.io/py/python-fx.svg)
-![Python](https://img.shields.io/badge/python-3.8-green.svg)
 ![Python](https://img.shields.io/badge/python-3.9-green.svg)
 ![Python](https://img.shields.io/badge/python-3.10-green.svg)
 ![Python](https://img.shields.io/badge/python-3.11-green.svg)
@@ -69,7 +69,7 @@ A python-native JSON Viewer TUI, inspired by [fx](https://github.com/antonmedv/f
 
 ## Prerequisites
 * OS: MacOS / Linux
-* python: >= 3.8
+* python: >= 3.9
 * pip
 
 ## Installation

{python_fx-0.3.2 → python_fx-0.4.0}/README.md

@@ -2,7 +2,6 @@
 ![Build Status](https://github.com/cielong/pyfx/actions/workflows/ci.yml/badge.svg?branch=main)
 ![Documentation Status](https://readthedocs.org/projects/python-fx/badge/?version=latest)
 ![PyPI version](https://badge.fury.io/py/python-fx.svg)
-![Python](https://img.shields.io/badge/python-3.8-green.svg)
 ![Python](https://img.shields.io/badge/python-3.9-green.svg)
 ![Python](https://img.shields.io/badge/python-3.10-green.svg)
 ![Python](https://img.shields.io/badge/python-3.11-green.svg)
@@ -33,7 +32,7 @@ A python-native JSON Viewer TUI, inspired by [fx](https://github.com/antonmedv/f
 
 ## Prerequisites
 * OS: MacOS / Linux
-* python: >= 3.8
+* python: >= 3.9
 * pip
 
 ## Installation

python_fx-0.4.0/dev-requirements.txt

@@ -0,0 +1,81 @@
+alabaster==1.0.0; python_version >= '3.10'
+autopep8==2.3.1; python_version >= '3.8'
+babel==2.18.0; python_version >= '3.8'
+backports.tarfile==1.2.0; python_version >= '3.8'
+build==1.4.0; python_version >= '3.9'
+cachetools==7.0.5; python_version >= '3.10'
+certifi==2026.2.25; python_version >= '3.7'
+charset-normalizer==3.4.6; python_version >= '3.7'
+click==8.3.1; python_version >= '3.10'
+colorama==0.4.6; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6'
+coverage[toml]==7.13.5; python_version >= '3.10'
+distlib==0.4.0
+docutils==0.22.4; python_version >= '3.9'
+filelock==3.25.2; python_version >= '3.10'
+flake8==7.1.1; python_full_version >= '3.8.1'
+id==1.6.1; python_version >= '3.9'
+idna==3.11; python_version >= '3.8'
+imagesize==2.0.0; python_version >= '3.10' and python_version < '3.15'
+importlib-metadata==8.7.1; python_version >= '3.9'
+iniconfig==2.3.0; python_version >= '3.10'
+jaraco.classes==3.4.0; python_version >= '3.8'
+jaraco.context==6.1.1; python_version >= '3.9'
+jaraco.functools==4.4.0; python_version >= '3.9'
+jinja2==3.1.6; python_version >= '3.7'
+keyring==25.7.0; python_version >= '3.9'
+markdown-it-py==4.0.0; python_version >= '3.10'
+markupsafe==3.0.3; python_version >= '3.9'
+mccabe==0.7.0; python_version >= '3.6'
+mdurl==0.1.2; python_version >= '3.7'
+more-itertools==10.8.0; python_version >= '3.9'
+nh3==0.3.3; python_version >= '3.8'
+packaging==26.0; python_version >= '3.8'
+parameterized==0.9.0; python_version >= '3.7'
+pillow==12.1.1; python_version >= '3.10'
+platformdirs==4.9.4; python_version >= '3.10'
+pluggy==1.6.0; python_version >= '3.9'
+pycodestyle==2.12.1; python_version >= '3.8'
+pyflakes==3.2.0; python_version >= '3.8'
+pygments==2.19.2; python_version >= '3.8'
+pyproject-api==1.10.0; python_version >= '3.10'
+pyproject-hooks==1.2.0; python_version >= '3.7'
+pytest==9.0.2; python_version >= '3.10'
+pytest-cov==7.0.0; python_version >= '3.9'
+python-discovery==1.1.3; python_version >= '3.8'
+readme-renderer==44.0; python_version >= '3.9'
+requests==2.32.5; python_version >= '3.9'
+requests-toolbelt==1.0.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'
+rfc3986==2.0.0; python_version >= '3.7'
+rich==14.3.3; python_full_version >= '3.8.0'
+roman-numerals==4.1.0; python_version >= '3.10'
+setuptools==82.0.1; python_version >= '3.9'
+snowballstemmer==3.0.1; python_version not in '3.0, 3.1, 3.2'
+sphinx==9.0.4; python_version >= '3.11'
+sphinx-click==6.2.0; python_version >= '3.10'
+sphinxcontrib-applehelp==2.0.0; python_version >= '3.9'
+sphinxcontrib-devhelp==2.0.0; python_version >= '3.9'
+sphinxcontrib-htmlhelp==2.1.0; python_version >= '3.9'
+sphinxcontrib-jsmath==1.0.1; python_version >= '3.5'
+sphinxcontrib-qthelp==2.0.0; python_version >= '3.9'
+sphinxcontrib-serializinghtml==2.0.0; python_version >= '3.9'
+tomli==2.0.1; python_version >= '3.7'
+tomli-w==1.2.0; python_version >= '3.9'
+tox==4.50.0; python_version >= '3.10'
+tox-gh-actions==3.5.0; python_version >= '3.7'
+twine==6.2.0; python_version >= '3.9'
+urllib3==2.6.3; python_version >= '3.9'
+virtualenv==21.2.0; python_version >= '3.8'
+zipp==3.23.0; python_version >= '3.9'
+antlr4-python3-runtime==4.13.2
+asciimatics==1.15.0; python_version >= '3.8'
+dacite==1.9.2; python_version >= '3.7'
+first==2.0.2
+jsonpath-ng==1.8.0
+loguru==0.7.3; python_version >= '3.5' and python_version < '4.0'
+overrides==7.7.0; python_version >= '3.6'
+pyfiglet==1.0.4; python_version >= '3.9'
+pyperclip==1.11.0
+pyyaml==6.0.3; python_version >= '3.8'
+urwid==3.0.5; python_full_version >= '3.9.0'
+wcwidth==0.6.0; python_version >= '3.8'
+yamale==6.1.0; python_version >= '3.8'

{python_fx-0.3.2 → python_fx-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-fx"
-dynamic = ["version", "dependencies"]
+dynamic = ["version"]
 authors = [
 	{ name = "Yutian Wu", email = "yutianwu@umich.edu" }
 ]
@@ -8,7 +8,7 @@ license = { text = "MIT" }
 readme = "README.md"
 description = "A python-native fx-alike terminal JSON viewer."
 keywords = ["fx", "pyfx", "json viewer", "tui"]
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 classifiers = [
 	"Development Status :: 4 - Beta",
 	"Programming Language :: Python :: 3 :: Only",
@@ -18,6 +18,25 @@ classifiers = [
 	"License :: OSI Approved :: MIT License",
 	"Topic :: Utilities"
 ]
+dependencies = [
+	"antlr4-python3-runtime>=4.13,<5",
+	"asciimatics>=1.15,<2",
+	"click>=8.1.7,<9",
+	"first==2.0,<3",
+	"dacite==1.8,<2",
+	"jsonpath-ng==1.6,<2",
+	"loguru>=0.7.2,<0.8",
+	"overrides>=7.7.0,<8",
+	"pillow>=10.4,<11",
+	"ply>=3.11,<4",
+	"pyfiglet>=1.0,<2",
+	"pyperclip>=1.9",
+	"pyyaml>=6.0.2,<7",
+	"typing-extensions>=4.12.2,<5",
+	"urwid>=2.6,<3",
+	"wcwidth>=0.2.13,<0.3",
+	"yamale>=5.2,<6",
+]
 
 [project.urls]
 repository = "https://github.com/cielong/pyfx"

python_fx-0.4.0/requirements.txt

@@ -0,0 +1,15 @@
+antlr4-python3-runtime==4.13.2
+asciimatics==1.15.0; python_version >= '3.8'
+click==8.3.1; python_version >= '3.10'
+dacite==1.9.2; python_version >= '3.7'
+first==2.0.2
+jsonpath-ng==1.8.0
+loguru==0.7.3; python_version >= '3.5' and python_version < '4.0'
+overrides==7.7.0; python_version >= '3.6'
+pillow==12.1.1; python_version >= '3.10'
+pyfiglet==1.0.4; python_version >= '3.9'
+pyperclip==1.11.0
+pyyaml==6.0.3; python_version >= '3.8'
+urwid==3.0.5; python_full_version >= '3.9.0'
+wcwidth==0.6.0; python_version >= '3.8'
+yamale==6.1.0; python_version >= '3.8'

python_fx-0.4.0/src/pyfx/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{python_fx-0.3.2 → python_fx-0.4.0}/src/pyfx/app.py

@@ -10,7 +10,8 @@ from pyfx.config import parse
 from pyfx.config import themes_path
 from pyfx.config.config_parser import load
 from pyfx.error import PyfxException
-from pyfx.model import Model
+from pyfx.model.model_manager import ModelManager
+from pyfx.model.model_manager import ModelResult
 from pyfx.service.client import Client
 from pyfx.service.dispatcher import Dispatcher
 from pyfx.view import View
@@ -53,10 +54,12 @@ class PyfxApp:
 
         # backend part
         self._dispatcher = Dispatcher()
-        # model
-        self._model = Model(self._data)
-        self._dispatcher.register("query", self._model.query)
-        self._dispatcher.register("complete", self._model.complete)
+        # model manager
+        self._model_manager = ModelManager(
+            result_callback=self.__handle_model_result,
+            progress_callback=None)
+        self._dispatcher.register("query", self._model_manager.query)
+        self._dispatcher.register("complete", self._model_manager.complete)
 
         # UI part
         self._keymapper = self.__convert_keymap(self._config.ui.keymap)
@@ -194,9 +197,19 @@ class PyfxApp:
                       "exit with {}", e)
         finally:
             self._thread_pool_executor.shutdown(wait=True)
+            self._model_manager.shutdown(wait=True)
             self._screen.clear()
 
-    def __init(self):
+    def process_input(self, keys):
+        """
+        Test-used method to process a list of keypress with proper model initialization
+        """
+        init_success = self.__init(blocking=True)
+        if not init_success:
+            return False, "Model failed to load within timeout"
+        return self.__process_input(keys)
+
+    def __init(self, blocking=False):
         """Post-initializes Pyfx, it must be called before `__run()`.
 
         .. note::
@@ -207,13 +220,22 @@ class PyfxApp:
            processing data to construct essential widgets.
         """
         logger.debug("Initializing Pyfx...")
-        self._json_browser.refresh_view(self._data)
+        # Start async model loading
+        self._model_manager.load(self._data)
+        if not blocking:
+            return True
+        return self._model_manager.wait_until_ready(timeout=5.0)
 
     def __run(self):
         """Starts the UI loop."""
         logger.debug("Running Pyfx...")
         self._view.run()
 
+    def __process_input(self, keys):
+        """Test-used method to process a list of keypress with proper model initialization."""
+        logger.debug("Running Pyfx...")
+        return self._view.process_input(keys)
+
     def __init_logger(self, is_debug_mode):
         logger.configure(
             handlers=[{
@@ -266,3 +288,14 @@ class PyfxApp:
             # avoid potential error during e2e test
             pass
         return screen
+
+    def __handle_model_result(self, result: ModelResult):
+        """Handle async model results"""
+        if not result.success:
+            logger.error("Model operation failed: {}", result.error)
+            return
+
+        if result.operation_name == "Load":
+            logger.debug("Model loading completed, refreshing view")
+            # Use urwid alarm to safely update UI from background thread
+            self._mediator.notify('backend', 'refresh', 'json_browser', result.data)

{python_fx-0.3.2 → python_fx-0.4.0}/src/pyfx/model/model.py

@@ -13,10 +13,16 @@ class Model:
      * performs auto-completion with given JSONPath query
     """
 
-    def __init__(self, data):
+    def __init__(self):
+        self._data = None
+        self._current = None
+
+    def load(self, data):
         self._data = data
         self._current = data
 
+        return self._current
+
     def query(self, text):
         if self._data is None:
             logger.debug("Data is None.")

python_fx-0.4.0/src/pyfx/model/model_manager.py

@@ -0,0 +1,210 @@
+import threading
+import queue
+from typing import Any, Optional, Callable
+from concurrent.futures import ThreadPoolExecutor, Future
+from dataclasses import dataclass
+from enum import Enum
+from loguru import logger
+
+from pyfx.model import Model
+
+
+class ModelState(Enum):
+    CREATED = "created"
+    LOADING = "loading"
+    READY = "ready"
+    SHUTDOWN = "shutdown"
+
+
+@dataclass
+class ModelResult:
+    """Result wrapper for threaded model operations"""
+
+    success: bool
+    operation_name: str
+    data: Any = None
+    error: Optional[str] = None
+    operation_id: Optional[str] = None
+
+
+@dataclass
+class ProgressUpdate:
+    """Progress update for long-running operations"""
+
+    operation_id: str
+    progress: float  # 0.0 to 1.0
+    message: str
+    completed: bool = False
+
+
+class ModelManager:
+    """
+    Thread-safe wrapper around Model that runs operations in background thread.
+
+    Provides async interface for JSON processing while maintaining thread safety
+    between model operations and UI updates.
+    """
+
+    def __init__(self, result_callback, progress_callback, max_workers: int = 2):
+        self._executor = ThreadPoolExecutor(
+            max_workers=max_workers, thread_name_prefix="pyfx-model"
+        )
+
+        # Thread-safe communication
+        self._result_queue = queue.Queue()
+        self._progress_queue = queue.Queue()
+        self._operation_counter = 0
+        self._operation_lock = threading.Lock()
+
+        # Callbacks for UI updates
+        self._result_callback: Optional[Callable[[ModelResult], None]] = result_callback
+        self._progress_callback: Optional[Callable[[ProgressUpdate], None]] = progress_callback
+
+        # Current operation tracking
+        self._current_futures: dict[str, Future] = {}
+
+        self._state = ModelState.CREATED
+        self._model: Model = Model()
+
+    def load(self, data: Any) -> str:
+        """Load data asynchronously"""
+
+        def _load_task(operation_id, operation_name):
+            try:
+                self._report_progress(operation_id, 0.0, "Initializing model...")
+
+                self._state = ModelState.LOADING
+                result = self._model.load(data)
+
+                self._state = ModelState.READY
+                self._report_progress(operation_id, 1.0, "Model ready", completed=True)
+
+                model_result = ModelResult(
+                    operation_id=operation_id,
+                    operation_name=operation_name,
+                    success=True,
+                    data=result,
+                )
+                self._report_result(model_result)
+            except Exception as e:
+                logger.opt(exception=True).error("Load task failed: {}", e)
+                self._state = ModelState.SHUTDOWN
+                raise
+
+        return self._submit_task("Load", _load_task)
+
+    def query(self, text: str):
+        """Execute JSONPath query synchronously"""
+        if self._state != ModelState.READY:
+            logger.warning(
+                "Model not ready for queries, current state: {}", self._state
+            )
+            return None
+
+        return self._model.query(text)
+
+    def complete(self, text: str):
+        """Execute autocompletion synchronously"""
+        if self._state != ModelState.READY:
+            logger.warning(
+                "Model not ready for completion, current state: {}", self._state
+            )
+            return False, "", []
+
+        return self._model.complete(text)
+
+    def cancel_operation(self, task_id: str) -> bool:
+        """Cancel a running operation"""
+        if task_id not in self._current_futures:
+            return False
+
+        future = self._current_futures[task_id]
+        if not future.cancel():
+            return False
+
+        del self._current_futures[task_id]
+        return True
+
+    def wait_until_ready(self, timeout: float = 10.0) -> bool:
+        """Block until model is ready or timeout occurs"""
+        import time
+        start_time = time.time()
+
+        while self._state != ModelState.READY:
+            if time.time() - start_time > timeout:
+                logger.warning("Model loading timeout after {}s", timeout)
+                return False
+
+            time.sleep(0.01)  # Small sleep to avoid busy waiting
+
+        return True
+
+    def shutdown(self, wait: bool = True):
+        """Shutdown the model manager"""
+        self._state = ModelState.SHUTDOWN
+
+        # Cancel all pending operations
+        for operation_id in list(self._current_futures.keys()):
+            self.cancel_operation(operation_id)
+
+        # Shutdown executor
+        self._executor.shutdown(wait=wait)
+
+    def _submit_task(self, task_name, task):
+        task_id = self.__generate_task_id()
+
+        def wrapped_task():
+            try:
+                task(task_id, task_name)
+            except Exception as e:
+                logger.opt(exception=True).error("{} failed: {}", task_name, e)
+                self._report_error(
+                    task_id, task_name, f"{task_name} failed: {str(e)}"
+                )
+
+        future = self._executor.submit(wrapped_task)
+        self._current_futures[task_id] = future
+        return task_id
+
+    def __generate_task_id(self) -> str:
+        """Generate unique operation ID"""
+        with self._operation_lock:
+            self._operation_counter += 1
+            return f"op_{self._operation_counter}"
+
+    def _report_progress(
+        self, operation_id: str, progress: float, message: str, completed: bool = False
+    ):
+        """Report progress update"""
+        update = ProgressUpdate(
+            operation_id=operation_id,
+            progress=progress,
+            message=message,
+            completed=completed,
+        )
+
+        try:
+            self._progress_queue.put_nowait(update)
+            if self._progress_callback:
+                self._progress_callback(update)
+        except queue.Full:
+            logger.warning("Progress queue full, dropping update")
+
+    def _report_result(self, result: ModelResult):
+        """Report operation result"""
+        try:
+            self._result_queue.put_nowait(result)
+            if self._result_callback:
+                self._result_callback(result)
+        except queue.Full:
+            logger.warning("Result queue full, dropping result")
+
+    def _report_error(self, operation_id: str, operation_name: str, error_msg: str):
+        """Report operation error"""
+        result = ModelResult(
+            operation_id=operation_id,
+            success=False,
+            operation_name=operation_name,
+            error=error_msg,
+        )
+        self._report_result(result)