ptdu 0.1.0__py3-none-any.whl

ptdu/utils.py

@@ -0,0 +1,80 @@
+"""Utility classes for PTDU."""
+
+from __future__ import annotations
+
+
+class SizeCalculator:
+    """Utility class for size calculations and formatting."""
+
+    # Size units in bytes
+    UNITS: list[tuple[str, int]] = [
+        ("B", 1),
+        ("KB", 1024),
+        ("MB", 1024**2),
+        ("GB", 1024**3),
+        ("TB", 1024**4),
+        ("PB", 1024**5),
+    ]
+
+    @classmethod
+    def format_size(cls, size_bytes: int) -> str:
+        """Format byte size to human-readable string.
+
+        Args:
+            size_bytes: Size in bytes
+
+        Returns:
+            Human-readable size string (e.g., "1.5 MB", "512 B")
+        """
+        if size_bytes < 0:
+            raise ValueError("Size cannot be negative")
+
+        if size_bytes == 0:
+            return "0 B"
+
+        # Find appropriate unit
+        for unit_name, unit_bytes in reversed(cls.UNITS):
+            if size_bytes >= unit_bytes:
+                value = size_bytes / unit_bytes
+                # Use integer for bytes, one decimal for KB, two for larger
+                if unit_name == "B":
+                    return f"{int(value)} {unit_name}"
+                elif unit_name == "KB":
+                    return f"{value:.1f} {unit_name}"
+                else:
+                    return f"{value:.2f} {unit_name}"
+
+        return f"{size_bytes} B"
+
+    @classmethod
+    def format_percentage(cls, part: int, total: int) -> str:
+        """Calculate and format percentage.
+
+        Args:
+            part: The partial size
+            total: The total size
+
+        Returns:
+            Percentage string (e.g., "45.2%")
+        """
+        if total <= 0:
+            return "0.0%"
+
+        percentage = (part / total) * 100
+        return f"{percentage:.1f}%"
+
+    @classmethod
+    def calculate_percentage(cls, part: int, total: int) -> float:
+        """Calculate percentage as float.
+
+        Args:
+            part: The partial size
+            total: The total size
+
+        Returns:
+            Percentage value (0-100)
+        """
+        if total <= 0:
+            return 0.0
+
+        return (part / total) * 100

ptdu-0.1.0.dist-info/METADATA

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: ptdu
+Version: 0.1.0
+Summary: Python Tkinter Disk Usage analyzer - an ncdu-like tool with vim keybindings
+Project-URL: Homepage, https://github.com/cosmez/ptdu
+Project-URL: Repository, https://github.com/cosmez/ptdu
+Project-URL: Issues, https://github.com/cosmez/ptdu/issues
+Author: Cosme Zamudio
+License: MIT
+License-File: LICENSE
+Keywords: analyzer,disk,ncdu,tkinter,tui,usage,vim
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Requires-Dist: send2trash>=2.1.0
+Description-Content-Type: text/markdown
+
+# PTDU - Python Tkinter Disk Usage
+
+PTDU is a graphical disk usage analyzer built with Python and Tkinter, inspired by ncdu (NCurses Disk Usage). It provides an interactive, navigable tree view of directory sizes with full recursive scanning, vim-like keyboard navigation, SQLite caching, and comprehensive error handling.
+
+## Features
+
+- **Interactive Tree View**: Navigate directories with an intuitive tree interface
+- **Full Recursive Scan**: Complete directory tree scanning for accurate size information
+- **Background Scanning**: All filesystem operations run in separate threads
+- **Vim-like Navigation**: Keyboard-first interface (j/k navigation, h/l expand/collapse)
+- **Human-readable Sizes**: Automatic conversion (B, KB, MB, GB, TB)
+- **SQLite Caching**: Persistent cache for faster subsequent scans
+- **Virtual Scrolling**: Optimized handling of large directories (100k+ items)
+- **Export**: Save scan results to JSON or CSV
+- **Safe Delete**: Move to trash with confirmation
+- **Cross-platform**: Linux, macOS, and Windows support
+
+## Requirements
+
+- Python 3.8+
+- Tkinter (usually included with Python)
+- send2trash (optional, for safer file deletion)
+
+## Installation
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/cosmez/ptdu.git
+cd ptdu
+
+# Install in editable mode
+pip install -e .
+```
+
+### Using pip
+
+```bash
+pip install ptdu
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Analyze current directory
+ptdu
+
+# Analyze specific directory
+ptdu /path/to/directory
+
+# Show help
+ptdu --help
+```
+
+### Command-Line Options
+
+```bash
+ptdu [path] [options]
+
+Options:
+  path                  Directory to analyze (default: current directory)
+  --follow-symlinks     Follow symbolic links when scanning
+  --exclude, -e         Additional patterns to exclude (multiple allowed)
+  --max-depth, -d       Maximum scan depth
+  --no-cache            Disable SQLite caching
+  --clear-cache         Clear cache before starting
+  --version             Show version information
+  --help                Show help message
+```
+
+### Examples
+
+```bash
+# Analyze home directory, excluding node_modules and .git
+ptdu ~ -e node_modules -e .git
+
+# Scan with limited depth for faster results
+ptdu /var -d 3
+
+# Clear cache and rescan
+ptdu --clear-cache /path/to/dir
+
+# Follow symbolic links
+ptdu --follow-symlinks /path/to/dir
+```
+
+## Keyboard Shortcuts
+
+### Navigation
+
+| Key | Action |
+|-----|--------|
+| `j` or `↓` | Move down |
+| `k` or `↑` | Move up |
+| `h` or `←` | Collapse directory |
+| `l` or `→` | Expand directory |
+| `Enter` | Toggle expand/collapse |
+| `g` | Jump to top |
+| `G` | Jump to bottom |
+| `u` | Go to parent directory |
+
+### Actions
+
+| Key | Action |
+|-----|--------|
+| `q` | Quit application |
+| `r` | Rescan current directory |
+| `d` | Delete selected item (with confirmation) |
+| `b` | Toggle breadcrumb/path bar |
+| `o` | Open folder in file manager |
+| `e` | Export scan results (JSON/CSV) |
+
+### View Options
+
+| Key | Action |
+|-----|--------|
+| `.` | Toggle hidden files (dotfiles) |
+| `s` | Cycle sort mode (Size → Name → Items) |
+| `Ctrl + Plus` | Increase font size |
+| `Ctrl + Minus` | Decrease font size |
+| `Ctrl + 0` | Reset font size |
+
+## Display
+
+### Columns
+
+1. **Name** - File or directory name with icon (📁/📂/📄)
+2. **Size** - Human-readable size
+3. **Size Bar** - Visual representation of relative size
+4. **Percent** - Percentage of parent directory
+5. **Items** - Number of items (directories only)
+
+### Color Coding
+
+- **Blue** - Directories
+- **Black** - Regular files
+- **Gray** - Hidden files (starting with `.`)
+- **Orange** - Medium files (10-100 MB)
+- **Red** - Large files (>100 MB)
+
+## Caching
+
+PTDU automatically caches scan results to speed up subsequent scans:
+
+- Cache location: `~/.cache/ptdu/cache.db`
+- Automatic invalidation when directories are modified
+- Thread-safe operations
+
+To disable caching:
+```bash
+ptdu --no-cache /path/to/dir
+```
+
+To clear the cache:
+```bash
+ptdu --clear-cache
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Type Checking
+
+```bash
+mypy --strict ptdu/
+```
+
+### Running the Application
+
+```bash
+# Run in development mode
+python -m ptdu.main
+
+# Or use the installed command
+ptdu
+```
+
+## Project Structure
+
+```
+ptdu/
+├── ptdu/                   # Main package
+│   ├── __init__.py        # Package exports
+│   ├── cache.py           # SQLite caching
+│   ├── errors.py          # Error handling
+│   ├── fonts.py           # OS-aware font configuration
+│   ├── main.py            # Entry point with CLI args
+│   ├── models.py          # DirNode data model
+│   ├── performance.py     # Virtual scrolling, memory optimization
+│   ├── scanner.py         # Directory scanning
+│   ├── threads.py         # Background threading
+│   ├── treeview.py        # Directory tree view widget
+│   ├── ui.py              # Main window
+│   └── utils.py           # SizeCalculator utility
+├── tests/                 # Test suite
+│   ├── __init__.py
+│   ├── test_models.py
+│   ├── test_scanner.py
+│   ├── test_threads.py
+│   ├── test_treeview.py
+│   ├── test_ui.py
+│   └── test_utils.py
+├── docs/                  # Documentation
+│   ├── user_guide.md      # User documentation
+│   └── developer.md       # Developer documentation
+├── README.md              # This file
+└── pyproject.toml         # Project configuration
+```
+
+## Modules Overview
+
+### `ptdu.models`
+- **DirNode**: Tree node representing files and directories
+- Parent-child relationships with size propagation
+- Expand/collapse state tracking
+
+### `ptdu.scanner`
+- **Scanner**: High-performance directory scanner using `os.scandir()`
+- **ScanResult**: Dataclass for scanned entries
+- **MemoryMonitor**: Memory usage tracking
+- Pattern-based filtering (skip/exclude)
+- Recursive scanning with configurable depth
+
+### `ptdu.cache`
+- **ScanCache**: SQLite-based caching with mtime invalidation
+- Thread-safe operations with locking
+- Automatic cache validation
+
+### `ptdu.performance`
+- **VirtualScroller**: Efficient handling of large directories
+- **MemoryOptimizer**: Memory usage optimization
+- **LargeDirectoryHandler**: Special handling for huge directories
+
+### `ptdu.errors`
+- **ErrorHandler**: Centralized error handling with dialogs
+- **PathValidator**: Path validation and sanitization
+- User-friendly error messages with suggestions
+
+### `ptdu.threads`
+- **ScanThread**: Background scanning thread
+- **ScanThreadManager**: Thread lifecycle management
+- Queue-based message passing
+
+### `ptdu.treeview`
+- **DirectoryTreeview**: Custom Treeview with styling
+- Size bars, color coding, icon display
+- Node mapping for tree operations
+
+### `ptdu.ui`
+- **MainWindow**: Main application window
+- Keyboard shortcut handling
+- Integration with all components
+
+### `ptdu.fonts`
+- **FontManager**: OS-aware font detection
+- Dynamic font size adjustment
+- Cross-platform font selection
+
+### `ptdu.utils`
+- **SizeCalculator**: Human-readable size formatting
+- Percentage calculations
+
+## Performance
+
+PTDU is optimized for large directories:
+
+- **Virtual Scrolling**: Renders only visible items (100k+ items supported)
+- **Memory Monitoring**: Configurable thresholds with warnings
+- **Depth Limiting**: `--max-depth` for limiting recursion
+- **Caching**: Persistent SQLite cache reduces re-scan time
+
+Typical performance:
+- SSD: 50k-100k files/second
+- HDD: 5k-10k files/second
+
+## Error Handling
+
+Comprehensive error handling includes:
+
+- Permission denied dialogs with retry/skip/abort options
+- Long path warnings (>4000 characters)
+- Scan error handling with continue options
+- Delete error handling with retry
+- Cache error handling (non-critical, continues without cache)
+
+## Documentation
+
+- **User Guide**: `docs/user_guide.md` - Complete user documentation
+- **Developer Docs**: `docs/developer.md` - Architecture and API documentation
+
+## License
+
+MIT License

ptdu-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+ptdu/__init__.py,sha256=aldEgsi3EE8D-GscpFk7-HwJ8O4sO1kvrF5fayKXNSk,945
+ptdu/cache.py,sha256=_c9zBNFAH8Och-ZWg1HK2h4kgIaAnXK1w8cMTLyympg,11596
+ptdu/errors.py,sha256=Yv-4rpM6BPnF-hAcpnrpdcu7gZyuw1RJR1d8E8rA30U,16676
+ptdu/fonts.py,sha256=tSAm-4ps_CcbgfFr9atdb76i0fc0aN-0l-fhxc85Mr4,6975
+ptdu/main.py,sha256=lhIBZaIKDIsIrqWwizfmTSxCDn5uMzs8j-h5bvstc2E,3104
+ptdu/models.py,sha256=jUg2qw4SHOCbId_aq9e4o1SAWrOdKqMYPEkpM0oj3z4,3477
+ptdu/performance.py,sha256=vxamlKuDlTjijV-7Uwv4lRQk5xlCGQdV2fYoLxGDN7Q,9208
+ptdu/scanner.py,sha256=vZihN5wUzDNisV5p34ibjkDrZVoJaqjmbI22zv1QOSE,14835
+ptdu/threads.py,sha256=oTzPsx4CaXRWnZ0KVP-AkZu4ZXm9cq8CK9bFGLaZXXQ,7039
+ptdu/treeview.py,sha256=buOG8aW627CnjnkxcoURkrc4ostZovVyraJw5yoAy2A,12598
+ptdu/ui.py,sha256=NrQdbD6mI-HPZhFhDzxIVJNnHUa8SoMW4T2JJ5p0q7I,42052
+ptdu/utils.py,sha256=cdF-ayUwJvjHSlSMPxBV6A_DL9j6hdXZXHxNcn_bcA4,2096
+ptdu-0.1.0.dist-info/METADATA,sha256=Jw5OeLqSoSXmF9y82ajwegfz8NbKI9rNvAgLgu1gVd8,9454
+ptdu-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ptdu-0.1.0.dist-info/entry_points.txt,sha256=o4TYqm432nS64rDR1OrrN4RGM_JjuDDvdUrmCtWjNAc,40
+ptdu-0.1.0.dist-info/licenses/LICENSE,sha256=HIYkq8inF0pvCg6jWFbZJBIXjqahJmHyby8IConQm_Q,1070
+ptdu-0.1.0.dist-info/RECORD,,

ptdu-0.1.0.dist-info/WHEEL

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

ptdu-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ptdu = ptdu.main:main

ptdu-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cosme Zamudio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.