Skip to content

README_Python.md

Latest commit

 

History

History
191 lines (145 loc) · 6.86 KB

README_Python.md

File metadata and controls

191 lines (145 loc) · 6.86 KB

Yandex Disk Menu - Python Version

A modern Python implementation of the Yandex Disk file manager integration with enhanced error handling, batch processing, and multi-platform support.

📚 Documentation: For installation examples and troubleshooting, see Usage Guide. For project overview, see Main README.

🐍 Python-Specific Features

Advanced Processing

  • Batch Operations: Intelligent batch processing with two strategies:
    • One-by-One: Publish/save operations with progress notifications and link collection
    • All-at-Once: Optimized file copy/move operations for maximum efficiency
  • Error Recovery: Continue processing remaining items when some fail
  • Rollback Support: Automatic rollback of operations when errors occur
  • Conflict Resolution: Smart auto-renaming with _number suffix pattern

Modern Architecture

  • Type Safety: Full type hints for better IDE support and reliability
  • Modular Design: Clean separation of concerns with dedicated classes
  • Configuration Management: .env file-based configuration with dotenv
  • CLI Framework: Built on Click for robust command-line interface
  • Cross-Platform: Automatic X11/Wayland clipboard detection via pyclip

Enhanced Reliability

  • Comprehensive Logging: Detailed operation tracking with verbose mode
  • Service Readiness: Waits for yandex-disk daemon before operations
  • Input Validation: Robust file path and parameter validation
  • Graceful Degradation: Fallback mechanisms for missing dependencies

🔧 Technical Requirements

Overview

  • Desktop Environment:
    • KDE with Dolphin file manager (primary support)
    • GNOME/GTK [Beta] with Files/Nautilus, Nemo, Caja, or Thunar
  • yandex-disk daemon installed and running
  • Notifications: kdialog (KDE) or notify-send (GNOME and others)
  • Clipboard utilities:
    • xclip - For X11 environments
    • wl-clipboard - For Wayland environments
  • Python 3.8+
  • Python venv - python3-venv package (naming varies by distribution)

Python Runtime

  • Python 3.8+ with type hints support
  • Virtual Environment: Isolated dependency management
  • Platform: Linux (X11/Wayland session support)

Python Dependencies (managed via requirements.txt)

click >= 8.0.0          # CLI framework with decorators
pyclip >= 0.7.0         # Cross-platform clipboard (X11/Wayland auto-detect)
python-dotenv >= 1.0.0  # Environment variable management

System Integration

  • yandex-disk daemon: Core cloud storage functionality
  • Notifications: Desktop-aware (kdialog/notify-send)
  • File Managers: See file manager support matrix

📦 Installation: See Usage Guide for complete installation examples and file manager-specific setup.

🏗️ Architecture Overview

Core Components

Main Script (ydmenu.py)

  • CLI entry point with Click decorators
  • Command routing and parameter validation
  • Error handling and logging coordination

YandexDiskMenu Class

  • Core business logic and file operations
  • yandex-disk daemon interaction
  • Clipboard and notification management

Environment Wrapper (ydmenu-py-env)

  • Virtual environment activation
  • Production deployment wrapper
  • PATH resolution and error handling

Setup Script (setup.py)

  • Installation and configuration management
  • Desktop file generation from templates
  • Environment variable setup

Data Flow

File Manager → ydmenu-py-env → venv/bin/python ydmenu.py → YandexDiskMenu Class
                                                          ↓
                                                   yandex-disk daemon
                                                          ↓
                                                   Yandex Cloud Storage

Configuration Management

Environment Variables (via .env)

YA_DISK_ROOT="~/Public"              # Parent directory for Yandex Disk
YADISK_MENU_VERSION="1.6.4"          # Version tracking

Runtime Configuration

  • Auto-discovery of yandex-disk paths
  • Desktop environment detection
  • Session type detection (X11/Wayland)

🔍 Development

Developer-facing details have moved to the dedicated Developer Guide: see doc/DEVELOPMENT.md.

🚀 Advanced Usage

Command Line Interface

# Direct Python usage (development)
./ydmenu.py --help
./ydmenu.py --verbose PublishToYandexCom file.txt

# Production usage (via wrapper)
ydmenu-py-env PublishToYandex file.txt
ydmenu-py-env ClipboardToStream

Batch Processing Examples

# Multiple file publishing
ydmenu-py-env PublishToYandexCom file1.txt file2.txt file3.txt

# Directory operations  
ydmenu-py-env FileAddToStream /path/to/directory

# Mixed operations with error recovery
ydmenu-py-env FileMoveToStream file1.txt missing_file.txt file3.txt
# → Continues with file3.txt even if missing_file.txt fails

Verbose Mode and Logging

# Enable verbose output
ydmenu-py-env --verbose PublishToYandex file.txt

# Check logs
tail -f $YA_DISK_ROOT/yaMedia-python.log

🔄 Migration from Shell Version

Key Differences

Feature Shell Version Python Version
Error Handling Basic Comprehensive with recovery
Batch Processing Limited Full support with strategies
Logging Simple Detailed with levels
Configuration Environment vars .env + environment vars
Testing None 112 unit tests
Type Safety None Full type hints

Migration Path

  1. Install Python version: make install && make configure-skip-env
  2. Test functionality: Verify both versions work
  3. Gradual transition: Use Python for new workflows
  4. Remove shell version: When satisfied with Python version

Compatibility

  • Shared configuration: Both versions use same environment variables
  • Shared logging directory: Different log files, same location
  • Shared menu structure: Similar user experience

🧪 Testing and Quality Assurance

For full testing, CI/CD, and quality control details, see doc/DEVELOPMENT.md.

🔗 Related Documentation

💡 Contributing: When modifying Python code, always run make test to ensure compatibility and maintain test coverage. See development workflow guidelines in project documentation.