zealpy 0.1.0__py3-none-any.whl

zealpy/__init__.py

@@ -0,0 +1,36 @@
+"""
+zealpy
+~~~~~~
+
+Lightweight offline documentation browser and search engine for Dash / Zeal docsets.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__author__ = "Zealpy Contributors"
+__license__ = "GPL-3.0-or-later"
+
+from zealpy.docset import Docset, DocsetEntry, DocsetManager
+from zealpy.server import run_server
+
+
+def search(query: str, docset: str = None, limit: int = 50):
+    """Quick helper to search symbols across docsets."""
+    manager = DocsetManager()
+    return manager.search(query, docset_name=docset, total_limit=limit)
+
+
+def serve(port: int = 8080, host: str = "127.0.0.1", open_browser: bool = True):
+    """Starts the local documentation server."""
+    run_server(host=host, port=port, open_browser=open_browser)
+
+
+__all__ = [
+    "Docset",
+    "DocsetEntry",
+    "DocsetManager",
+    "search",
+    "serve",
+    "__version__",
+]

zealpy/__main__.py

@@ -0,0 +1,4 @@
+from zealpy.cli import main
+
+if __name__ == "__main__":
+    main()

zealpy/cli.py

@@ -0,0 +1,252 @@
+"""
+zealpy.cli
+~~~~~~~~~~
+
+Command-line interface for zealpy.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+from zealpy import __version__
+from zealpy.docset import DocsetManager
+from zealpy.feeds import (
+    POPULAR_DOCSETS,
+    download_docset,
+    install_from_file,
+    list_available_docsets,
+)
+from zealpy.server import run_server
+
+# ANSI Colors for terminal output
+BOLD = "\033[1m"
+DIM = "\033[2m"
+CYAN = "\033[36m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+BLUE = "\033[34m"
+MAGENTA = "\033[35m"
+RESET = "\033[0m"
+
+
+def format_type_badge(type_str: str) -> str:
+    """Returns colorized type badge."""
+    t = type_str.lower()
+    if "class" in t:
+        return f"{MAGENTA}[Class]{RESET}"
+    if "method" in t:
+        return f"{BLUE}[Method]{RESET}"
+    if "func" in t:
+        return f"{GREEN}[Function]{RESET}"
+    if "mod" in t or "pkg" in t:
+        return f"{YELLOW}[Module]{RESET}"
+    return f"{CYAN}[{type_str}]{RESET}"
+
+
+def cmd_serve(args: argparse.Namespace) -> None:
+    """Starts the local documentation server."""
+    run_server(
+        host=args.host,
+        port=args.port,
+        docset_dir=args.docset_dir,
+        open_browser=not args.no_browser,
+    )
+
+
+def cmd_search(args: argparse.Namespace) -> None:
+    """Searches symbols in terminal."""
+    extra = [args.docset_dir] if args.docset_dir else None
+    manager = DocsetManager(extra_paths=extra)
+
+    results = manager.search(
+        query=args.query,
+        docset_name=args.docset,
+        entry_type=args.type,
+        total_limit=args.limit,
+    )
+
+    if not results:
+        print(f"No symbols found matching '{args.query}'.")
+        return
+
+    print(f"\nFound {BOLD}{len(results)}{RESET} symbol(s) for '{args.query}':\n")
+    for r in results:
+        badge = format_type_badge(r.type)
+        print(f"  {badge:<18} {BOLD}{r.name:<32}{RESET} {DIM}({r.docset}){RESET}")
+        if args.verbose:
+            print(f"    {DIM}Path: {r.path}{RESET}")
+    print()
+
+
+def cmd_list(args: argparse.Namespace) -> None:
+    """Lists all installed docsets."""
+    extra = [args.docset_dir] if args.docset_dir else None
+    manager = DocsetManager(extra_paths=extra)
+
+    if not manager.docsets:
+        print("\nNo docsets found locally.")
+        print("To download docsets, run: zealpy available")
+        print("Or: zealpy download <name>\n")
+        return
+
+    print(f"\n{BOLD}Installed Docsets ({len(manager.docsets)}):{RESET}\n")
+    for name, ds in sorted(manager.docsets.items()):
+        entries = ds.count_entries()
+        print(f"  * {BOLD}{ds.name:<24}{RESET} [{entries:>6} symbols]  {DIM}{ds.path}{RESET}")
+    print()
+
+
+def cmd_available(args: argparse.Namespace) -> None:
+    """Lists popular docsets available for download."""
+    items = list_available_docsets()
+    print(f"\n{BOLD}Available Official Docsets ({len(items)}):{RESET}\n")
+    print(f"  {'Name':<18} {'Description'}")
+    print(f"  {'-'*18} {'-'*45}")
+    for item in items:
+        print(f"  {CYAN}{item['name']:<18}{RESET} {item['title']}")
+    print(f"\nInstall any docset using: {BOLD}zealpy download <name>{RESET}\n")
+
+
+def cmd_download(args: argparse.Namespace) -> None:
+    """Downloads a docset from official mirrors."""
+    name = args.name.strip()
+    print(f"\nDownloading docset {BOLD}{name}{RESET}...")
+
+    def progress(read_bytes: int, total_bytes: int) -> None:
+        mb_read = read_bytes / (1024 * 1024)
+        mb_total = total_bytes / (1024 * 1024)
+        percent = (read_bytes / total_bytes) * 100 if total_bytes > 0 else 0
+        sys.stdout.write(f"\r  Progress: {mb_read:.1f} MB / {mb_total:.1f} MB ({percent:.0f}%)")
+        sys.stdout.flush()
+
+    try:
+        path = download_docset(name, target_dir=args.docset_dir, progress_callback=progress)
+        print(f"\n\n{GREEN}Successfully installed {name}!{RESET}")
+        print(f"Installed at: {path}\n")
+    except Exception as e:
+        print(f"\n{YELLOW}Failed to download docset:{RESET} {e}\n", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_add(args: argparse.Namespace) -> None:
+    """Imports a local docset or archive."""
+    src = Path(args.path)
+    print(f"\nImporting docset from {src}...")
+    try:
+        path = install_from_file(src, target_dir=args.docset_dir)
+        print(f"{GREEN}Successfully imported!{RESET}")
+        print(f"Location: {path}\n")
+    except Exception as e:
+        print(f"Failed to import: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_info(args: argparse.Namespace) -> None:
+    """Shows detailed information about a docset."""
+    extra = [args.docset_dir] if args.docset_dir else None
+    manager = DocsetManager(extra_paths=extra)
+    ds = manager.get(args.name)
+
+    if not ds:
+        print(f"Docset '{args.name}' not found.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"\n{BOLD}Docset: {ds.name}{RESET}")
+    print(f"  Identifier: {ds.identifier}")
+    print(f"  Path:       {ds.path}")
+    print(f"  Database:   {ds.db_path}")
+    print(f"  Total:      {ds.count_entries()} symbols\n")
+
+    types = ds.get_types()
+    if types:
+        print(f"  {BOLD}Symbol Types:{RESET}")
+        for t, count in types[:12]:
+            print(f"    * {t:<20} {count:>6}")
+    print()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Builds argument parser for zealpy CLI."""
+    parser = argparse.ArgumentParser(
+        prog="zealpy",
+        description="Zealpy: Lightweight Offline Documentation Browser and Search Engine for Dash / Zeal docsets.",
+        epilog="Examples:\n"
+               "  zealpy serve                   # Start local documentation server\n"
+               "  zealpy search QComboBox        # Search symbol across docsets\n"
+               "  zealpy search groupby -d Pandas\n"
+               "  zealpy download Python         # Download official Python docs\n"
+               "  zealpy list                    # List installed docsets\n",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument("-v", "--version", action="version", version=f"zealpy {__version__}")
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # serve
+    p_serve = subparsers.add_parser("serve", help="Start local web server and documentation viewer")
+    p_serve.add_argument("-p", "--port", type=int, default=8080, help="Port to listen on (default: 8080)")
+    p_serve.add_argument("-H", "--host", default="127.0.0.1", help="Host address (default: 127.0.0.1)")
+    p_serve.add_argument("--no-browser", action="store_true", help="Do not open browser automatically")
+    p_serve.add_argument("-d", "--docset-dir", help="Path to custom docsets directory")
+    p_serve.set_defaults(func=cmd_serve)
+
+    # search
+    p_search = subparsers.add_parser("search", help="Search symbol/function across docsets")
+    p_search.add_argument("query", help="Symbol or function name to search for")
+    p_search.add_argument("-d", "--docset", help="Filter by docset name")
+    p_search.add_argument("-t", "--type", help="Filter by symbol type (Class, Method, Function, etc.)")
+    p_search.add_argument("-n", "--limit", type=int, default=25, help="Maximum number of results")
+    p_search.add_argument("-V", "--verbose", action="store_true", help="Show full entry paths")
+    p_search.add_argument("--docset-dir", help="Path to custom docsets directory")
+    p_search.set_defaults(func=cmd_search)
+
+    # list
+    p_list = subparsers.add_parser("list", help="List all locally installed docsets")
+    p_list.add_argument("-d", "--docset-dir", help="Path to custom docsets directory")
+    p_list.set_defaults(func=cmd_list)
+
+    # available
+    p_avail = subparsers.add_parser("available", help="List popular docsets available for download")
+    p_avail.set_defaults(func=cmd_available)
+
+    # download
+    p_down = subparsers.add_parser("download", help="Download and install an official docset")
+    p_down.add_argument("name", help="Name of docset (e.g. Python, Qt, Pandas, Flask)")
+    p_down.add_argument("-d", "--docset-dir", help="Target installation directory")
+    p_down.set_defaults(func=cmd_download)
+
+    # add
+    p_add = subparsers.add_parser("add", help="Import a local .docset folder or archive (.tgz, .zip)")
+    p_add.add_argument("path", help="Path to .docset folder or archive")
+    p_add.add_argument("-d", "--docset-dir", help="Target installation directory")
+    p_add.set_defaults(func=cmd_add)
+
+    # info
+    p_info = subparsers.add_parser("info", help="Show metadata and statistics for a docset")
+    p_info.add_argument("name", help="Name of docset")
+    p_info.add_argument("-d", "--docset-dir", help="Path to custom docsets directory")
+    p_info.set_defaults(func=cmd_info)
+
+    return parser
+
+
+def main() -> None:
+    """Main CLI entrypoint."""
+    parser = build_parser()
+    if len(sys.argv) == 1:
+        parser.print_help()
+        sys.exit(0)
+
+    args = parser.parse_args()
+    if hasattr(args, "func"):
+        args.func(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

zealpy/docset.py

@@ -0,0 +1,330 @@
+"""
+zealpy.docset
+~~~~~~~~~~~~~
+
+Docset parser and search engine for Dash / Zeal documentation sets.
+"""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import sqlite3
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Iterator, List, Optional, Tuple
+
+
+@dataclass
+class DocsetEntry:
+    """Represents an indexed symbol / entry inside a docset."""
+    name: str
+    type: str
+    path: str
+    docset: str
+
+    @property
+    def url(self) -> str:
+        """URL path for local HTTP server serving."""
+        # Clean up possible anchor or leading slashes
+        clean_path = self.path.lstrip("/")
+        return f"/docs/{self.docset}/{clean_path}"
+
+
+class Docset:
+    """Represents a single .docset bundle."""
+
+    def __init__(self, path: Path | str) -> None:
+        self.path = Path(path).resolve()
+        if not self.path.is_dir() or not self.path.name.endswith(".docset"):
+            raise ValueError(f"Not a valid .docset directory: {self.path}")
+
+        self.contents_dir = self.path / "Contents"
+        self.resources_dir = self.contents_dir / "Resources"
+        self.documents_dir = self.resources_dir / "Documents"
+        self.db_path = self.resources_dir / "docSet.dsidx"
+        self.plist_path = self.contents_dir / "Info.plist"
+
+        self.identifier = self.path.stem
+        self.name = self.path.stem
+        self.feed_url: Optional[str] = None
+        self._table_type: Optional[str] = None
+
+        self._load_plist()
+
+    def _load_plist(self) -> None:
+        """Loads metadata from Info.plist if present."""
+        if self.plist_path.is_file():
+            try:
+                with open(self.plist_path, "rb") as fp:
+                    data = plistlib.load(fp)
+                    self.identifier = data.get("CFBundleIdentifier", self.identifier)
+                    self.name = (
+                        data.get("DocSetPlatformFamily")
+                        or data.get("CFBundleName")
+                        or data.get("CFBundleIdentifier")
+                        or self.name
+                    )
+                    self.feed_url = data.get("DashDocSetFeedURL")
+            except Exception:
+                pass
+
+    def _get_connection(self) -> sqlite3.Connection:
+        """Opens a read-only SQLite connection to the index."""
+        if not self.db_path.is_file():
+            raise FileNotFoundError(f"Database not found: {self.db_path}")
+        uri = f"file:{self.db_path.as_posix()}?mode=ro"
+        conn = sqlite3.connect(uri, uri=True, check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _detect_schema(self, conn: sqlite3.Connection) -> str:
+        """Detects whether index uses searchIndex or CoreData format."""
+        if self._table_type:
+            return self._table_type
+
+        cursor = conn.cursor()
+        cursor.execute("SELECT name FROM sqlite_master WHERE type='table'")
+        tables = {row[0].lower() for row in cursor.fetchall()}
+
+        if "searchindex" in tables:
+            self._table_type = "searchIndex"
+        elif "zloadingentry" in tables:
+            self._table_type = "zloadingentry"
+        elif "ztoken" in tables:
+            self._table_type = "ztoken"
+        else:
+            self._table_type = "unknown"
+
+        return self._table_type
+
+    def count_entries(self) -> int:
+        """Returns the total number of indexed symbols."""
+        if not self.db_path.is_file():
+            return 0
+        try:
+            with self._get_connection() as conn:
+                schema = self._detect_schema(conn)
+                cursor = conn.cursor()
+                if schema == "searchIndex":
+                    cursor.execute("SELECT COUNT(*) FROM searchIndex")
+                elif schema == "zloadingentry":
+                    cursor.execute("SELECT COUNT(*) FROM zloadingentry")
+                elif schema == "ztoken":
+                    cursor.execute("SELECT COUNT(*) FROM ztoken")
+                else:
+                    return 0
+                return cursor.fetchone()[0]
+        except Exception:
+            return 0
+
+    def get_types(self) -> List[Tuple[str, int]]:
+        """Returns list of (type, count) found in the docset."""
+        if not self.db_path.is_file():
+            return []
+        try:
+            with self._get_connection() as conn:
+                schema = self._detect_schema(conn)
+                cursor = conn.cursor()
+                if schema == "searchIndex":
+                    cursor.execute(
+                        "SELECT type, COUNT(*) FROM searchIndex GROUP BY type ORDER BY COUNT(*) DESC"
+                    )
+                elif schema == "zloadingentry":
+                    cursor.execute(
+                        "SELECT ZTYPE, COUNT(*) FROM zloadingentry GROUP BY ZTYPE ORDER BY COUNT(*) DESC"
+                    )
+                else:
+                    return []
+                return [(row[0] or "Unknown", row[1]) for row in cursor.fetchall()]
+        except Exception:
+            return []
+
+    def search(
+        self,
+        query: str,
+        entry_type: Optional[str] = None,
+        limit: int = 50,
+    ) -> List[DocsetEntry]:
+        """Searches symbols matching the query with intelligent ranking."""
+        if not self.db_path.is_file() or not query.strip():
+            return []
+
+        query = query.strip()
+        results: List[DocsetEntry] = []
+
+        try:
+            with self._get_connection() as conn:
+                schema = self._detect_schema(conn)
+                cursor = conn.cursor()
+
+                if schema == "searchIndex":
+                    sql = """
+                        SELECT name, type, path,
+                            CASE
+                                WHEN name = ? THEN 1
+                                WHEN name LIKE ? || '%' THEN 2
+                                WHEN name LIKE '%' || ? || '%' THEN 3
+                                ELSE 4
+                            END AS rank
+                        FROM searchIndex
+                        WHERE name LIKE '%' || ? || '%'
+                    """
+                    params: list = [query, query, query, query]
+                    if entry_type:
+                        sql += " AND type = ?"
+                        params.append(entry_type)
+                    sql += " ORDER BY rank ASC, LENGTH(name) ASC, name ASC LIMIT ?"
+                    params.append(limit)
+
+                    cursor.execute(sql, params)
+                    for row in cursor.fetchall():
+                        results.append(
+                            DocsetEntry(
+                                name=row["name"],
+                                type=row["type"] or "Unknown",
+                                path=row["path"],
+                                docset=self.identifier,
+                            )
+                        )
+
+                elif schema == "zloadingentry":
+                    sql = """
+                        SELECT ZNAME AS name, ZTYPE AS type, ZPATH AS path,
+                            CASE
+                                WHEN ZNAME = ? THEN 1
+                                WHEN ZNAME LIKE ? || '%' THEN 2
+                                WHEN ZNAME LIKE '%' || ? || '%' THEN 3
+                                ELSE 4
+                            END AS rank
+                        FROM zloadingentry
+                        WHERE ZNAME LIKE '%' || ? || '%'
+                    """
+                    params = [query, query, query, query]
+                    if entry_type:
+                        sql += " AND ZTYPE = ?"
+                        params.append(entry_type)
+                    sql += " ORDER BY rank ASC, LENGTH(ZNAME) ASC, ZNAME ASC LIMIT ?"
+                    params.append(limit)
+
+                    cursor.execute(sql, params)
+                    for row in cursor.fetchall():
+                        results.append(
+                            DocsetEntry(
+                                name=row["name"],
+                                type=row["type"] or "Unknown",
+                                path=row["path"],
+                                docset=self.identifier,
+                            )
+                        )
+        except Exception as e:
+            # Fallback for unexpected DB error
+            print(f"Error querying {self.name}: {e}", file=sys.stderr)
+
+        return results
+
+
+class DocsetManager:
+    """Discovers and manages docsets across system and custom directories."""
+
+    def __init__(self, extra_paths: Optional[List[Path | str]] = None) -> None:
+        self.extra_paths = [Path(p).resolve() for p in (extra_paths or [])]
+        self.docsets: Dict[str, Docset] = {}
+        self.rescan()
+
+    @staticmethod
+    def get_default_storage_dir() -> Path:
+        """Returns the primary storage directory for zealpy docsets (~/.zealpy/docsets)."""
+        base = Path.home() / ".zealpy" / "docsets"
+        base.mkdir(parents=True, exist_ok=True)
+        return base
+
+    @classmethod
+    def get_search_paths(cls, extra_paths: Optional[List[Path]] = None) -> List[Path]:
+        """Returns all directories checked for docsets, including native Zeal paths."""
+        paths: List[Path] = []
+
+        if extra_paths:
+            paths.extend(extra_paths)
+
+        # Local workspace paths
+        paths.append(Path.cwd() / "docsets")
+        paths.append(Path.cwd())
+
+        # zealpy storage
+        paths.append(cls.get_default_storage_dir())
+
+        # Native Zeal paths for cross-compatibility
+        if sys.platform == "win32":
+            local_appdata = os.environ.get("LOCALAPPDATA")
+            if local_appdata:
+                paths.append(Path(local_appdata) / "Zeal" / "Zeal" / "docsets")
+        elif sys.platform == "darwin":
+            paths.append(Path.home() / "Library" / "Application Support" / "Zeal" / "Zeal" / "docsets")
+        else:
+            paths.append(Path.home() / ".local" / "share" / "Zeal" / "Zeal" / "docsets")
+
+        # Return existing unique directories
+        unique_paths: List[Path] = []
+        for p in paths:
+            if p.is_dir() and p not in unique_paths:
+                unique_paths.append(p)
+        return unique_paths
+
+    def rescan(self) -> None:
+        """Scans all search paths and registers found docsets."""
+        self.docsets.clear()
+        for folder in self.get_search_paths(self.extra_paths):
+            if folder.name.endswith(".docset") and folder.is_dir():
+                try:
+                    ds = Docset(folder)
+                    self.docsets[ds.identifier] = ds
+                except Exception:
+                    pass
+                continue
+
+            # Check subdirectories
+            for entry in folder.iterdir():
+                if entry.is_dir() and entry.name.endswith(".docset"):
+                    try:
+                        ds = Docset(entry)
+                        # Keep latest or first seen
+                        if ds.identifier not in self.docsets:
+                            self.docsets[ds.identifier] = ds
+                    except Exception:
+                        pass
+
+    def get(self, name: str) -> Optional[Docset]:
+        """Gets docset by identifier or name (case-insensitive)."""
+        if name in self.docsets:
+            return self.docsets[name]
+        lower_name = name.lower()
+        for k, v in self.docsets.items():
+            if k.lower() == lower_name or v.name.lower() == lower_name:
+                return v
+        return None
+
+    def search(
+        self,
+        query: str,
+        docset_name: Optional[str] = None,
+        entry_type: Optional[str] = None,
+        limit_per_docset: int = 25,
+        total_limit: int = 100,
+    ) -> List[DocsetEntry]:
+        """Searches across all docsets or a specific docset."""
+        results: List[DocsetEntry] = []
+        if docset_name:
+            ds = self.get(docset_name)
+            if ds:
+                return ds.search(query, entry_type=entry_type, limit=total_limit)
+            return []
+
+        for ds in self.docsets.values():
+            ds_results = ds.search(query, entry_type=entry_type, limit=limit_per_docset)
+            results.extend(ds_results)
+            if len(results) >= total_limit:
+                break
+
+        return results[:total_limit]