Metadata-Version: 2.4
Name: pylphin
Version: 0.1.0
Summary: Dolphin-inspired PyQt6 file explorer with Breeze icons
Author: D. Saahishnu Ram
License: GPL 2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
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 :: Desktop Environment :: File Managers
Requires-Python: >=3.9
Requires-Dist: mutagen>=1.47.0
Requires-Dist: pyqt6>=6.4.0
Requires-Dist: python-magic-bin>=0.4.14; sys_platform == 'win32'
Requires-Dist: python-magic>=0.4.24; sys_platform == 'linux'
Description-Content-Type: text/markdown

# Pylphin

A fast, keyboard-friendly, Dolphin-inspired file explorer built with **PyQt6** and the **Breeze** icon theme. Designed for Linux and Windows with a consistent dark theme, live drive rescan, quick-look previews, and a clean picker API.

![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)
![License](https://img.shields.io/badge/license-GPL--2.0-green)
![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Windows-lightgrey)

---

## Features

- **Dolphin-style UI** — Breeze Dark theme, breadcrumb navigation, icon/list/details views
- **Quick Look (GlimpseSpeedy)** — Press `Space` to preview images, text, audio, and video without leaving the app
- **Live Drive Sidebar** — Auto-rescanning device list with capacity bars and one-click eject
- **Cross-Platform** — Native feel on Linux and Windows
- **Picker API** — Use Pylphin as a file/folder picker dialog inside your own PyQt6 apps
- **Local-First Icons** — Ships with 100+ Breeze SVGs; no internet required after install
- **MIME-Aware** — Extension mapping + libmagic fallback for accurate file type icons

---

## Installation

### From PyPI

```bash
pip install pylphin
```

### Linux Prerequisites

Pylphin uses `python-magic` for MIME detection on Linux, which requires the system `libmagic` library:

```bash
# Debian / Ubuntu
sudo apt-get install libmagic1

# Fedora / RHEL
sudo dnf install file-libs

# Arch
sudo pacman -S file
```

### Optional Dependencies

For audio metadata display in previews:

```bash
pip install pylphin[audio]
```

---

## Usage

### Standalone File Manager

```bash
# Launch the GUI
pylphin

# Or via module
python -m pylphin
```

### As a Picker Dialog

```python
from pylphin import pick_file, pick_files, pick_folder

# Single file
path = pick_file(extension=".py")
print(path)

# Multiple files
paths = pick_files(extension=[".jpg", ".png"])
print(paths)

# Folder
folder = pick_folder(start_path="/home/user/Documents")
print(folder)
```

### Embedding in Your Own App

```python
from PyQt6.QtWidgets import QApplication
from pylphin import Pylphin

app = QApplication([])
win = Pylphin()
win.show()
app.exec()
```

---

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `Alt + ←` | Back |
| `Alt + →` | Forward |
| `Alt + ↑` | Up one directory |
| `F5` | Reload |
| `F2` | Rename selected |
| `Delete` | Delete selected |
| `Space` | Quick Look preview |
| `Esc` | Close preview / cancel address edit |
| `← / →` | Previous / next file in preview |
| `Backspace` | Navigate back |
| `Ctrl + H` | Toggle hidden files |

---

## Project Structure

```
pylphin/
├── src/pylphin/
│   ├── __init__.py          # Public API
│   ├── __main__.py          # python -m pylphin
│   ├── pylphin.py           # Main application
│   └── assets/
│       └── icons/           # 100+ Breeze SVG icons
├── pyproject.toml
├── README.md
└── LICENSE
```

---

## Platform Notes

| Platform | Details |
|----------|---------|
| **Linux** | ✅ Full support. Drive eject via `udisksctl`/`eject`. Requires `libmagic1`. |
| **Windows** | ✅ Full support. Drive eject via `DeviceIoControl` + PowerShell fallback. Bundled `python-magic-bin`. |
| **macOS** | ❌ Not supported. Uses Windows/Linux-specific APIs. |

---

## License

This project is licensed under the **GNU General Public License v2.0**.

See [LICENSE](LICENSE) for the full text.

The bundled Breeze icons are from the [KDE Breeze Icons](https://github.com/KDE/breeze-icons) project and are licensed under **LGPL-3.0**.

---

## Author

**D. Saahishnu Ram**

---

## Contributing

Issues and pull requests are welcome on [GitHub](https://github.com/yourusername/pylphin).
