484 lines
13 KiB
Markdown
484 lines
13 KiB
Markdown
# EU-Utility New Features Documentation
|
|
|
|
This document describes the 5 major new features added to EU-Utility.
|
|
|
|
## Table of Contents
|
|
|
|
1. [Auto-Updater System](#1-auto-updater-system)
|
|
2. [Plugin Marketplace](#2-plugin-marketplace)
|
|
3. [Cloud Sync](#3-cloud-sync)
|
|
4. [Statistics Dashboard](#4-statistics-dashboard)
|
|
5. [Import/Export System](#5-importexport-system)
|
|
|
|
---
|
|
|
|
## 1. Auto-Updater System
|
|
|
|
**Plugin:** `auto_updater.py`
|
|
|
|
The Auto-Updater provides automatic update checking, downloading, and installation with rollback support.
|
|
|
|
### Features
|
|
|
|
- **Automatic Update Checks**: Configurable interval-based checking
|
|
- **Semantic Versioning**: Full support for version comparison (e.g., `1.2.3-beta+build123`)
|
|
- **Secure Downloads**: SHA256 checksum verification
|
|
- **Automatic Rollback**: Restores previous version if update fails
|
|
- **Update History**: Tracks all update attempts with success/failure status
|
|
- **Multiple Channels**: Support for stable, beta, and alpha release channels
|
|
|
|
### Configuration
|
|
|
|
```python
|
|
config = {
|
|
"check_interval_hours": 24, # How often to check for updates
|
|
"auto_check": True, # Enable automatic checking
|
|
"auto_install": False, # Auto-install updates (disabled by default)
|
|
"update_server": "https://api.eu-utility.app/updates",
|
|
"backup_dir": "data/backups",
|
|
"channel": "stable", # stable, beta, alpha
|
|
}
|
|
```
|
|
|
|
### Usage
|
|
|
|
```python
|
|
from plugins.auto_updater import AutoUpdaterPlugin
|
|
|
|
# Get the plugin
|
|
updater = plugin_api.get_plugin("auto_updater")
|
|
|
|
# Manual update check
|
|
update_info = updater.check_for_updates()
|
|
if update_info:
|
|
print(f"Update available: {update_info.version}")
|
|
print(f"Release notes: {update_info.release_notes}")
|
|
|
|
# Full update process (check, download, install)
|
|
success = updater.update()
|
|
|
|
# Or step by step
|
|
download_path = updater.download_update(update_info)
|
|
if download_path:
|
|
success = updater.install_update(download_path, update_info)
|
|
|
|
# Get update history
|
|
history = updater.get_update_history()
|
|
```
|
|
|
|
### API Reference
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `check_for_updates()` | Check for available updates |
|
|
| `download_update(info)` | Download an update package |
|
|
| `install_update(path, info)` | Install a downloaded update |
|
|
| `update()` | Full update process (check + download + install) |
|
|
| `get_update_history()` | Get history of update attempts |
|
|
| `set_channel(channel)` | Set update channel (stable/beta/alpha) |
|
|
| `add_listener(callback)` | Listen for status changes |
|
|
|
|
---
|
|
|
|
## 2. Plugin Marketplace
|
|
|
|
**Plugin:** `plugin_marketplace.py`
|
|
|
|
Browse, install, and manage community-contributed plugins from a centralized marketplace.
|
|
|
|
### Features
|
|
|
|
- **Plugin Discovery**: Browse by category, rating, or popularity
|
|
- **Search**: Find plugins by name, description, tags, or author
|
|
- **One-Click Install**: Simple installation with dependency resolution
|
|
- **Auto-Updates**: Check for and install plugin updates
|
|
- **Ratings & Reviews**: Community-driven quality indicators
|
|
- **Offline Cache**: Cached plugin list for offline browsing
|
|
|
|
### Configuration
|
|
|
|
```python
|
|
config = {
|
|
"marketplace_url": "https://marketplace.eu-utility.app/api",
|
|
"cache_duration_minutes": 60,
|
|
"plugins_dir": "plugins",
|
|
"auto_check_updates": True,
|
|
}
|
|
```
|
|
|
|
### Usage
|
|
|
|
```python
|
|
from plugins.plugin_marketplace import PluginMarketplacePlugin
|
|
|
|
# Get the plugin
|
|
marketplace = plugin_api.get_plugin("plugin_marketplace")
|
|
|
|
# Browse all plugins
|
|
plugins = marketplace.fetch_plugins()
|
|
for plugin in plugins:
|
|
print(f"{plugin.name} by {plugin.author} - {plugin.rating}★")
|
|
|
|
# Search
|
|
results = marketplace.search_plugins("clipboard", category="utilities")
|
|
|
|
# Get featured plugins
|
|
featured = marketplace.get_featured_plugins(limit=10)
|
|
|
|
# Install a plugin
|
|
success = marketplace.install_plugin("plugin_id")
|
|
|
|
# Check for updates
|
|
updates = marketplace.check_installed_updates()
|
|
for update in updates:
|
|
marketplace.update_plugin(update.id)
|
|
|
|
# Get installed plugins
|
|
installed = marketplace.get_installed_plugins()
|
|
```
|
|
|
|
### API Reference
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `fetch_plugins()` | Get all available plugins |
|
|
| `search_plugins(query, category)` | Search for plugins |
|
|
| `get_plugin_by_id(id)` | Get specific plugin details |
|
|
| `get_featured_plugins(limit)` | Get popular plugins |
|
|
| `get_categories()` | List available categories |
|
|
| `install_plugin(id)` | Install a plugin |
|
|
| `uninstall_plugin(id)` | Remove a plugin |
|
|
| `update_plugin(id)` | Update a plugin |
|
|
| `check_installed_updates()` | Check for available updates |
|
|
| `submit_rating(id, rating, review)` | Rate a plugin |
|
|
|
|
---
|
|
|
|
## 3. Cloud Sync
|
|
|
|
**Plugin:** `cloud_sync.py`
|
|
|
|
Synchronize settings, configurations, and data across multiple devices.
|
|
|
|
### Features
|
|
|
|
- **Multi-Provider Support**: Dropbox, Google Drive, OneDrive, WebDAV, Custom
|
|
- **Automatic Sync**: Sync on changes or at intervals
|
|
- **Conflict Resolution**: Multiple strategies (ask, local, remote, newest)
|
|
- **Encryption**: Optional data encryption for privacy
|
|
- **Selective Sync**: Choose what to sync (settings, plugins, history)
|
|
- **Bidirectional Sync**: Merge local and remote changes
|
|
|
|
### Configuration
|
|
|
|
```python
|
|
config = {
|
|
"enabled": False,
|
|
"provider": "custom",
|
|
"auto_sync": True,
|
|
"sync_interval_minutes": 30,
|
|
"sync_on_change": True,
|
|
"conflict_resolution": "ask", # ask, local, remote, newest
|
|
"encrypt_data": True,
|
|
"sync_plugins": True,
|
|
"sync_settings": True,
|
|
"sync_history": False,
|
|
}
|
|
```
|
|
|
|
### Usage
|
|
|
|
```python
|
|
from plugins.cloud_sync import CloudSyncPlugin, CloudProvider, SyncConfig
|
|
|
|
# Get the plugin
|
|
sync = plugin_api.get_plugin("cloud_sync")
|
|
|
|
# Configure
|
|
config = SyncConfig(
|
|
enabled=True,
|
|
provider="custom",
|
|
auto_sync=True,
|
|
encrypt_data=True,
|
|
)
|
|
sync.set_sync_config(config)
|
|
|
|
# Configure provider
|
|
sync.set_provider_config(CloudProvider.CUSTOM, {
|
|
"upload_url": "https://my-server.com/sync/upload",
|
|
"download_url": "https://my-server.com/sync/download",
|
|
"api_key": "your-api-key",
|
|
})
|
|
|
|
# Manual sync operations
|
|
sync.sync_up() # Upload to cloud
|
|
sync.sync_down() # Download from cloud
|
|
sync.sync_bidirectional() # Merge changes
|
|
|
|
# Get sync status
|
|
print(f"Status: {sync.get_status()}")
|
|
print(f"Last sync: {sync.get_last_sync()}")
|
|
|
|
# Get sync history
|
|
history = sync.get_sync_history()
|
|
```
|
|
|
|
### API Reference
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `sync_up()` | Upload local data to cloud |
|
|
| `sync_down()` | Download cloud data to local |
|
|
| `sync_bidirectional()` | Two-way sync |
|
|
| `set_sync_config(config)` | Update sync settings |
|
|
| `set_provider_config(provider, config)` | Configure cloud provider |
|
|
| `get_status()` | Get current sync status |
|
|
| `get_last_sync()` | Get timestamp of last sync |
|
|
| `get_sync_history()` | Get sync operation history |
|
|
|
|
---
|
|
|
|
## 4. Statistics Dashboard
|
|
|
|
**Plugin:** `stats_dashboard.py`
|
|
|
|
Comprehensive analytics and monitoring for EU-Utility usage and performance.
|
|
|
|
### Features
|
|
|
|
- **Real-time Metrics**: CPU, memory, disk usage monitoring
|
|
- **Time-Series Data**: Historical tracking of all metrics
|
|
- **Event Logging**: Track application events and user actions
|
|
- **Performance Timing**: Measure operation durations
|
|
- **Custom Metrics**: Counters, gauges, and histograms
|
|
- **Health Monitoring**: System health status and alerts
|
|
- **Exportable Reports**: Generate and export statistics reports
|
|
|
|
### Configuration
|
|
|
|
```python
|
|
config = {
|
|
"data_dir": "data/stats",
|
|
"retention_days": 30,
|
|
"collection_interval_seconds": 60,
|
|
"enable_system_metrics": True,
|
|
"enable_plugin_metrics": True,
|
|
"enable_usage_metrics": True,
|
|
}
|
|
```
|
|
|
|
### Usage
|
|
|
|
```python
|
|
from plugins.stats_dashboard import StatsDashboardPlugin
|
|
|
|
# Get the plugin
|
|
stats = plugin_api.get_plugin("stats_dashboard")
|
|
|
|
# Record metrics
|
|
stats.record_counter("clipboard_copies", 1)
|
|
stats.record_gauge("active_connections", 5)
|
|
stats.record_histogram("response_time", 150.5)
|
|
|
|
# Time an operation
|
|
with stats.time_operation("database_query"):
|
|
# Your code here
|
|
pass
|
|
|
|
# Record events
|
|
stats.record_event("plugin", "plugin_loaded", {"plugin": "my_plugin"})
|
|
|
|
# Get metric statistics
|
|
cpu_stats = stats.get_metric("cpu_percent").get_stats(3600) # Last hour
|
|
print(f"Average CPU: {cpu_stats['mean']:.1f}%")
|
|
|
|
# Get system health
|
|
health = stats.get_system_health()
|
|
print(f"Status: {health['status']}")
|
|
|
|
# Generate report
|
|
report = stats.generate_report()
|
|
filepath = stats.export_report(format="json")
|
|
|
|
# Dashboard summary
|
|
summary = stats.get_dashboard_summary()
|
|
```
|
|
|
|
### API Reference
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `record_counter(name, value, labels)` | Increment a counter |
|
|
| `record_gauge(name, value, labels)` | Set a gauge value |
|
|
| `record_histogram(name, value, labels)` | Record to histogram |
|
|
| `record_timing(name, duration_ms)` | Record timing |
|
|
| `time_operation(name)` | Context manager for timing |
|
|
| `record_event(source, type, details)` | Log an event |
|
|
| `get_metric(name)` | Get a time series |
|
|
| `get_system_health()` | Get health status |
|
|
| `generate_report()` | Generate statistics report |
|
|
| `export_report(filepath, format)` | Export report to file |
|
|
|
|
---
|
|
|
|
## 5. Import/Export System
|
|
|
|
**Plugin:** `import_export.py`
|
|
|
|
Comprehensive data export and import functionality in multiple formats.
|
|
|
|
### Features
|
|
|
|
- **Multiple Formats**: JSON, CSV, XML, YAML, ZIP
|
|
- **Export Profiles**: Predefined profiles (full, settings_only, minimal, etc.)
|
|
- **Import Modes**: Merge, replace, or skip existing data
|
|
- **Backup Creation**: Full system backups
|
|
- **Validation**: Validate import files before importing
|
|
- **Progress Callbacks**: Track export/import progress
|
|
- **Automatic Backups**: Create backup before import
|
|
|
|
### Configuration
|
|
|
|
```python
|
|
config = {
|
|
"export_dir": "data/exports",
|
|
"import_dir": "data/imports",
|
|
"default_format": "json",
|
|
"backup_before_import": True,
|
|
}
|
|
```
|
|
|
|
### Usage
|
|
|
|
```python
|
|
from plugins.import_export import ImportExportPlugin, ExportFormat, ImportMode
|
|
|
|
# Get the plugin
|
|
ie = plugin_api.get_plugin("import_export")
|
|
|
|
# Export with profile
|
|
result = ie.export_data(
|
|
profile="full", # full, settings_only, plugins_only, minimal
|
|
format=ExportFormat.JSON,
|
|
)
|
|
print(f"Exported to: {result.filepath}")
|
|
|
|
# Quick exports
|
|
ie.export_settings("my_settings.json")
|
|
ie.export_plugins("my_plugins.json")
|
|
|
|
# Create backup
|
|
backup = ie.create_backup("pre_update_backup")
|
|
|
|
# Import data
|
|
result = ie.import_data(
|
|
filepath="export.json",
|
|
mode=ImportMode.MERGE, # merge, replace, skip
|
|
)
|
|
print(f"Imported: {result.items_imported}")
|
|
|
|
# Restore from backup
|
|
ie.restore_backup("backup_file.zip", mode=ImportMode.REPLACE)
|
|
|
|
# List backups
|
|
backups = ie.list_backups()
|
|
|
|
# Validate import file
|
|
validation = ie.validate_import_file("export.json")
|
|
print(f"Valid: {validation['valid']}")
|
|
|
|
# Custom export profile
|
|
from plugins.import_export import ExportProfile
|
|
profile = ie.create_custom_profile(
|
|
name="my_profile",
|
|
include_settings=True,
|
|
include_plugins=True,
|
|
include_history=False,
|
|
)
|
|
ie.export_data(profile, ExportFormat.ZIP)
|
|
```
|
|
|
|
### API Reference
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `export_data(profile, format, filepath)` | Export data |
|
|
| `export_settings(filepath)` | Quick export settings |
|
|
| `export_plugins(filepath)` | Quick export plugins |
|
|
| `create_backup(name)` | Create full backup |
|
|
| `import_data(filepath, mode)` | Import data |
|
|
| `restore_backup(path, mode)` | Restore from backup |
|
|
| `list_backups()` | List available backups |
|
|
| `validate_import_file(filepath)` | Validate import file |
|
|
| `get_export_profiles()` | Get available profiles |
|
|
| `create_custom_profile(name, **kwargs)` | Create custom profile |
|
|
|
|
---
|
|
|
|
## Integration Examples
|
|
|
|
### Combining Features
|
|
|
|
```python
|
|
# Example: Auto-backup before update
|
|
updater = plugin_api.get_plugin("auto_updater")
|
|
ie = plugin_api.get_plugin("import_export")
|
|
|
|
# Add pre-update backup
|
|
updater.add_listener(lambda status, info:
|
|
ie.create_backup(f"pre_update_{info.version}") if status.value == "downloading" else None
|
|
)
|
|
|
|
# Example: Sync stats to cloud
|
|
stats = plugin_api.get_plugin("stats_dashboard")
|
|
sync = plugin_api.get_plugin("cloud_sync")
|
|
|
|
# Export stats and sync
|
|
report_path = stats.export_report()
|
|
# Add to sync config...
|
|
|
|
# Example: Marketplace with stats tracking
|
|
marketplace = plugin_api.get_plugin("plugin_marketplace")
|
|
|
|
# Track plugin installations
|
|
marketplace.add_listener(lambda event, plugin_id:
|
|
stats.record_event("marketplace", event, {"plugin": plugin_id})
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Architecture Notes
|
|
|
|
All new plugins follow the EU-Utility plugin architecture:
|
|
|
|
1. **Inherit from BasePlugin**: All plugins extend `core.base_plugin.BasePlugin`
|
|
2. **Implement on_start/on_stop**: Lifecycle methods for initialization
|
|
3. **Use existing services**: Integrate with clipboard, plugin API
|
|
4. **Minimal dependencies**: Only use standard library where possible
|
|
5. **Configuration persistence**: Store config in `data/` directory
|
|
6. **Event-driven**: Support listeners/callbacks for extensibility
|
|
|
|
### File Structure
|
|
|
|
```
|
|
plugins/
|
|
├── auto_updater.py # Auto-update system
|
|
├── plugin_marketplace.py # Plugin browser/installer
|
|
├── cloud_sync.py # Cloud synchronization
|
|
├── stats_dashboard.py # Analytics dashboard
|
|
├── import_export.py # Data export/import
|
|
└── test_plugin.py # Original test plugin
|
|
```
|
|
|
|
### Dependencies
|
|
|
|
All plugins use only Python standard library except:
|
|
- `psutil` (optional): For system metrics in stats_dashboard
|
|
- `pyyaml` (optional): For YAML export/import
|
|
|
|
Install optional dependencies:
|
|
```bash
|
|
pip install psutil pyyaml
|
|
```
|