Metadata-Version: 2.4
Name: zealpy
Version: 0.1.0
Summary: Lightweight offline documentation browser and CLI for Dash and Zeal docsets
Author: Zealpy Contributors
Author-email: Oleg Shparber <oleg@zealdocs.org>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/RuttiTuttii/zealpy
Project-URL: Repository, https://github.com/RuttiTuttii/zealpy.git
Project-URL: Issues, https://github.com/RuttiTuttii/zealpy/issues
Keywords: zeal,docset,documentation,dash,offline-docs,pydoc
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: COPYING
Dynamic: license-file

# Zealpy 🚀

[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](COPYING)
[![Python Version](https://img.shields.io/badge/python-3.8+-brightgreen.svg)](https://python.org)
[![PyPI](https://img.shields.io/pypi/v/zealpy.svg)](https://pypi.org/project/zealpy/)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20external-success.svg)](pyproject.toml)

**Zealpy** is a lightweight, zero-dependency offline documentation browser and CLI for [Dash](https://kapeli.com/dash) and [Zeal](https://zealdocs.org) docsets.

Written in pure standard library Python, it runs anywhere without compiling C++ code, launches in milliseconds, and provides both a lightning-fast terminal CLI and a modern Dark Mode Web UI.

---

## ✨ Features

- **⚡ Zero External Dependencies**: Runs entirely on Python's standard library (`sqlite3`, `http.server`, `urllib`, `tarfile`, `plistlib`). No heavy frameworks or compiler issues.
- **🔍 Instant Terminal Search**: Query functions, methods, and classes right from your shell with colorized output.
- **🎨 Modern Dark Mode Web UI**: Built-in responsive SPA interface with live search autocomplete, type filter pills, and embedded HTML documentation reader.
- **📦 Official Docset Downloader**: Download and unpack documentation sets for Python, Qt, PyQt, Pandas, NumPy, Flask, Django, PostgreSQL, and 20+ other popular stacks directly from official mirrors.
- **🔄 Auto-detection of Existing Zeal Docsets**: Automatically discovers docsets already installed by desktop Zeal (`%LOCALAPPDATA%/Zeal/Zeal/docsets` on Windows, `~/.local/share/Zeal/Zeal/docsets` on Linux).
- **🛡️ Clean & Exam Safe**: Perfect for offline environments, coding competitions, and exams where external GUI binaries might raise questions, but Python packages are fully permitted.

---

## 🚀 Quick Start

### Installation

```bash
pip install zealpy
```

Or install locally in editable mode:

```bash
git clone https://github.com/RuttiTuttii/zealpy.git
cd zealpy
pip install -e .
```

---

## 💻 CLI Usage

### 1. Launch Documentation Server & Browser

```bash
zealpy serve
```

Starts the local documentation server at `http://127.0.0.1:8080` and opens your browser.

Custom port or no browser popup:
```bash
zealpy serve --port 9090 --no-browser
```

### 2. Search Symbols Directly in Terminal

```bash
# Search across all installed docsets
zealpy search QComboBox

# Filter by docset
zealpy search groupby -d Pandas

# Filter by symbol type (Class, Method, Function, Module)
zealpy search connect -t Method
```

### 3. List Installed Docsets

```bash
zealpy list
```

### 4. Download Official Docsets

Check available docsets:
```bash
zealpy available
```

Download and install:
```bash
zealpy download Python
zealpy download Qt
zealpy download Pandas
zealpy download Flask
```

### 5. Import Local Docset Archive

```bash
zealpy add path/to/MyDocset.docset
# Or archives:
zealpy add path/to/Python.tgz
```

---

## 🐍 Python Library API

Zealpy can also be imported directly inside your Python scripts:

```python
import zealpy

# Quick symbol search
results = zealpy.search("DataFrame.groupby")
for r in results:
    print(f"[{r.type}] {r.name} -> {r.url}")

# Manage docsets programmatically
manager = zealpy.DocsetManager()
python_docs = manager.get("Python_3")
if python_docs:
    print(f"Total symbols: {python_docs.count_entries()}")
    entries = python_docs.search("os.path.join")
    print(entries[0].path)

# Start web server programmatically
zealpy.serve(port=8080)
```

---

## ⌨️ Web UI Keyboard Shortcuts

| Shortcut | Action |
| --- | --- |
| `/` or `Ctrl + K` | Focus search bar |
| `↓` / `↑` | Navigate search results |
| `Enter` | Open selected documentation page |
| `Escape` | Clear search / close dialogs |

---

## 📜 License

This project is licensed under the [GNU General Public License v3.0 or later (GPL-3.0-or-later)](COPYING), preserving the license and open-source heritage of the original [Zeal](https://github.com/zealdocs/zeal) project created by Oleg Shparber.
