pylearn-reader 1.0.0__tar.gz

pylearn_reader-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Tritle
+
+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.

pylearn_reader-1.0.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: pylearn-reader
+Version: 1.0.0
+Summary: Interactive Python learning desktop app with PDF book reader and code editor
+Author: Nate Tritle
+License-Expression: MIT
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: PyQt6>=6.6.0
+Requires-Dist: PyQt6-QScintilla>=2.14.0
+Requires-Dist: PyMuPDF>=1.23.0
+Requires-Dist: Pygments>=2.17.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-qt>=4.2.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Dynamic: license-file

pylearn_reader-1.0.0/README.md

@@ -0,0 +1,210 @@
+# PyLearn
+
+[![CI](https://github.com/fritz99-lang/pylearn/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/fritz99-lang/pylearn/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-green.svg)](https://www.python.org/)
+[![mypy](https://img.shields.io/badge/type--checked-mypy-blue.svg)](https://mypy-lang.org/)
+
+An interactive desktop app for learning programming from PDF books. Split-pane interface with a book reader on the left and a code editor + console on the right — read the book, write code, and run it all in one place.
+
+## Screenshots
+
+**Light mode** — reading with Book menu open:
+
+![Light mode](docs/screenshots/light-mode.png)
+
+**Dark mode** — reading with code execution:
+
+![Dark mode](docs/screenshots/dark-mode.png)
+
+**Sepia mode** — reading view:
+
+![Sepia mode](docs/screenshots/sepia-mode.png)
+
+**Sepia mode** — running code (Zen of Python):
+
+![Code execution](docs/screenshots/sepia-code-execution.png)
+
+## Features
+
+- **PDF Book Reader** — Parses PDF books into structured, styled HTML with headings, body text, and syntax-highlighted code blocks
+- **Code Editor** — QScintilla-powered editor with syntax highlighting, line numbers, auto-indent, and configurable font/tab settings
+- **Code Execution** — Run Python code directly from the editor with output displayed in an integrated console (30s timeout, sandboxed subprocess)
+- **Table of Contents** — Auto-generated chapter navigation from PDF structure
+- **Progress Tracking** — SQLite database tracks chapter completion status, bookmarks, and notes per book
+- **Bookmarks & Notes** — Save bookmarks and attach notes to any page
+- **Multiple Book Profiles** — Supports Python, C++, and HTML/CSS books with per-book font classification profiles
+- **Themes** — Light, dark, and sepia themes for the reader panel
+- **External Editor** — Launch code in Notepad++ or your preferred external editor
+- **Parsed Content Caching** — PDF parsing results cached as JSON for fast subsequent loads
+
+## Requirements
+
+- Python 3.12+
+- Windows, macOS, or Linux
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/fritz99-lang/pylearn.git
+cd pylearn
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate    # Linux/macOS
+.venv\Scripts\activate       # Windows
+
+# Install the app
+pip install -e .
+
+# Or with dev tools (pytest, mypy)
+pip install -e ".[dev]"
+```
+
+You can also install directly from GitHub without cloning:
+
+```bash
+pip install git+https://github.com/fritz99-lang/pylearn.git
+```
+
+### Platform Notes
+
+| Platform | Notes |
+|----------|-------|
+| **Windows** | Works out of the box with Python 3.12+ |
+| **Linux** | Install system deps first: `sudo apt-get install libegl1 libxkbcommon0` |
+| **macOS** | May need Xcode command line tools: `xcode-select --install` |
+
+## Setup
+
+1. **Copy the example config files:**
+
+   ```bash
+   cp config/app_config.json.example config/app_config.json
+   cp config/books.json.example config/books.json
+   cp config/editor_config.json.example config/editor_config.json
+   ```
+
+2. **Register your books** by editing `config/books.json`:
+
+   ```json
+   {
+     "books": [
+       {
+         "book_id": "learning_python",
+         "title": "Learning Python",
+         "pdf_path": "/path/to/your/book.pdf",
+         "profile_name": "learning_python"
+       }
+     ]
+   }
+   ```
+
+   Available `profile_name` values: `learning_python`, `cpp_generic`, or leave empty for auto-detection.
+
+3. **Launch the app:**
+
+   ```bash
+   python -m pylearn
+   ```
+
+## Usage
+
+| Area | What it does |
+|------|-------------|
+| **Left panel** | Book reader — navigate chapters via the table of contents sidebar |
+| **Right panel (top)** | Code editor — write or paste code from the book |
+| **Right panel (bottom)** | Console — see output from running your code |
+| **Toolbar** | Theme switching, bookmarks, notes, progress tracking |
+
+## Keyboard Shortcuts
+
+| Category | Shortcut | Action |
+|----------|----------|--------|
+| **Navigation** | `Alt+Left` / `Alt+Right` | Previous / next chapter |
+| | `Ctrl+M` | Mark chapter complete |
+| | `Ctrl+T` | Toggle TOC panel |
+| **Search** | `Ctrl+F` | Find in current chapter |
+| | `Ctrl+Shift+F` | Search all books |
+| **Code** | `F5` | Run code |
+| | `Shift+F5` | Stop execution |
+| | `Ctrl+S` | Save code to file |
+| | `Ctrl+O` | Load code from file |
+| | `Ctrl+E` | Open in external editor |
+| **View** | `Ctrl+=` / `Ctrl+-` | Increase / decrease font size |
+| | `Ctrl+1` / `2` / `3` | Focus TOC / reader / editor |
+| **Notes** | `Ctrl+B` | Add bookmark |
+| | `Ctrl+N` | Add note |
+| **Help** | `Ctrl+/` | Show shortcuts dialog |
+
+## Configuration
+
+All config files live in `config/` and are JSON:
+
+- **`app_config.json`** — Window size, theme, splitter positions, last opened book
+- **`books.json`** — Registered books with PDF paths and profile names
+- **`editor_config.json`** — Editor font size, tab width, line numbers, execution timeout
+
+## Development
+
+```bash
+# Run all tests (702 tests)
+pytest tests/ -v
+
+# Skip slow tests
+pytest tests/ -v -m "not slow"
+
+# Type checking
+mypy src/pylearn/
+
+# Pre-parse books to cache
+python scripts/parse_books.py
+
+# Analyze PDF font metadata (useful for creating new book profiles)
+python scripts/analyze_pdf_fonts.py path/to/book.pdf
+```
+
+## Project Structure
+
+```
+src/pylearn/
+  parser/       PDF parsing, font analysis, content classification, caching
+  renderer/     HTML rendering, syntax highlighting, themes
+  executor/     Subprocess-based code execution with sandboxing
+  ui/           PyQt6 widgets (main window, reader, editor, console, dialogs)
+  core/         Config, database, models, constants
+  utils/        Text utilities, error handling
+config/         User-specific JSON config (not committed; see *.json.example)
+data/           SQLite database + parsed PDF cache (not committed)
+tests/          702 tests (500+ unit + 150+ integration)
+scripts/        Utility scripts for PDF analysis and book parsing
+```
+
+## Troubleshooting
+
+**App won't start**
+- Make sure PyQt6 is installed: `pip install PyQt6 PyQt6-QScintilla`
+- Verify Python 3.12+: `python --version`
+- On Linux, install system deps: `sudo apt-get install libegl1 libxkbcommon0`
+
+**PDF not found**
+- Check the `pdf_path` in `config/books.json` — use absolute paths
+- Verify the file exists at the specified path
+
+**Book not parsing correctly**
+- Delete the cached JSON in `data/` and re-launch to force a re-parse
+- Check if a matching `profile_name` exists in `book_profiles.py`
+- Run `python scripts/analyze_pdf_fonts.py path/to/book.pdf` to inspect font metadata
+
+**Code execution timeout**
+- Default timeout is 30 seconds
+- Increase it in `config/editor_config.json` by setting `"execution_timeout"` to a higher value
+
+## Acknowledgments
+
+Built in partnership with [Claude Code](https://claude.ai/claude-code) (Anthropic) — architecture, implementation, testing, and code review.
+
+## License
+
+[MIT](LICENSE) - Copyright (c) 2026 Nathan Tritle

pylearn_reader-1.0.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pylearn-reader"
+version = "1.0.0"
+description = "Interactive Python learning desktop app with PDF book reader and code editor"
+license = "MIT"
+authors = [{name = "Nate Tritle"}]
+requires-python = ">=3.12"
+dependencies = [
+    "PyQt6>=6.6.0",
+    "PyQt6-QScintilla>=2.14.0",
+    "PyMuPDF>=1.23.0",
+    "Pygments>=2.17.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-qt>=4.2.0",
+    "mypy>=1.8.0",
+]
+
+[project.scripts]
+pylearn = "pylearn.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = ["slow: marks tests as slow (deselect with '-m \"not slow\"')"]
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "pylearn.ui.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+warn_return_any = false
+disable_error_code = ["union-attr", "arg-type", "override", "name-defined", "assignment", "valid-type", "misc", "operator"]
+
+[[tool.mypy.overrides]]
+module = [
+    "fitz",
+    "fitz.*",
+    "PyQt6.Qsci",
+    "PyQt6.Qsci.*",
+    "pygments",
+    "pygments.*",
+]
+ignore_missing_imports = true

pylearn_reader-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pylearn_reader-1.0.0/src/pylearn/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2026 Nate Tritle. Licensed under the MIT License.
+"""PyLearn - Interactive Python Learning Desktop App."""

pylearn_reader-1.0.0/src/pylearn/__main__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 Nate Tritle. Licensed under the MIT License.
+"""Allow running as: python -m pylearn"""
+
+from pylearn.main import main
+
+main()

pylearn_reader-1.0.0/src/pylearn/app.py

@@ -0,0 +1,37 @@
+# Copyright (c) 2026 Nate Tritle. Licensed under the MIT License.
+"""QApplication setup and configuration."""
+
+from __future__ import annotations
+
+import sys
+
+from PyQt6.QtWidgets import QApplication
+from PyQt6.QtGui import QFont
+
+from pylearn.core.constants import APP_NAME
+from pylearn.ui.main_window import MainWindow
+from pylearn.utils.error_handler import setup_logging, install_global_exception_handler
+
+
+def create_app(debug: bool = False) -> tuple[QApplication, MainWindow]:
+    """Create and configure the application."""
+    setup_logging(debug=debug)
+    install_global_exception_handler()
+
+    app = QApplication(sys.argv)
+    app.setApplicationName(APP_NAME)
+    app.setStyle("Fusion")
+
+    # Default font
+    font = QFont("Segoe UI", 10)
+    app.setFont(font)
+
+    window = MainWindow()
+    return app, window
+
+
+def run_app(debug: bool = False) -> int:
+    """Create and run the application."""
+    app, window = create_app(debug=debug)
+    window.show()
+    return app.exec()

pylearn_reader-1.0.0/src/pylearn/core/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2026 Nate Tritle. Licensed under the MIT License.
+"""PyLearn core business logic."""

pylearn_reader-1.0.0/src/pylearn/core/config.py

@@ -0,0 +1,306 @@
+# Copyright (c) 2026 Nate Tritle. Licensed under the MIT License.
+"""JSON configuration loading and saving."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from pylearn.core.constants import (
+    APP_CONFIG_PATH,
+    BOOKS_CONFIG_PATH,
+    EDITOR_CONFIG_PATH,
+    DEFAULT_WINDOW_WIDTH,
+    DEFAULT_WINDOW_HEIGHT,
+    DEFAULT_FONT_SIZE,
+    DEFAULT_EDITOR_FONT_SIZE,
+    DEFAULT_TAB_WIDTH,
+    DEFAULT_EXECUTION_TIMEOUT,
+    DEFAULT_THEME,
+    READER_SPLITTER_RATIO,
+    EDITOR_CONSOLE_RATIO,
+    TOC_WIDTH,
+)
+
+
+logger = logging.getLogger("pylearn.config")
+
+
+def _safe_int(value: Any, default: int) -> int:
+    """Convert value to int, returning default on failure."""
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return default
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                return data
+        except (json.JSONDecodeError, UnicodeDecodeError, OSError) as e:
+            logger.error(f"Corrupt config file {path}: {e} — using defaults")
+    return {}
+
+
+def _save_json(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    try:
+        tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+        tmp.replace(path)
+    except OSError:
+        try:
+            path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+        except OSError:
+            pass
+    finally:
+        tmp.unlink(missing_ok=True)
+
+
+class AppConfig:
+    """Application-level configuration."""
+
+    def __init__(self) -> None:
+        self._data: dict[str, Any] = {}
+        self.load()
+
+    def load(self) -> None:
+        self._data = _load_json(APP_CONFIG_PATH)
+
+    def save(self) -> None:
+        _save_json(APP_CONFIG_PATH, self._data)
+
+    @property
+    def window_width(self) -> int:
+        return _safe_int(self._data.get("window_width", DEFAULT_WINDOW_WIDTH), DEFAULT_WINDOW_WIDTH)
+
+    @window_width.setter
+    def window_width(self, value: int) -> None:
+        self._data["window_width"] = value
+
+    @property
+    def window_height(self) -> int:
+        return _safe_int(self._data.get("window_height", DEFAULT_WINDOW_HEIGHT), DEFAULT_WINDOW_HEIGHT)
+
+    @window_height.setter
+    def window_height(self, value: int) -> None:
+        self._data["window_height"] = value
+
+    @property
+    def window_x(self) -> int | None:
+        return self._data.get("window_x")
+
+    @window_x.setter
+    def window_x(self, value: int) -> None:
+        self._data["window_x"] = value
+
+    @property
+    def window_y(self) -> int | None:
+        return self._data.get("window_y")
+
+    @window_y.setter
+    def window_y(self, value: int) -> None:
+        self._data["window_y"] = value
+
+    @property
+    def window_maximized(self) -> bool:
+        return bool(self._data.get("window_maximized", False))
+
+    @window_maximized.setter
+    def window_maximized(self, value: bool) -> None:
+        self._data["window_maximized"] = value
+
+    @property
+    def theme(self) -> str:
+        return str(self._data.get("theme", DEFAULT_THEME))
+
+    @theme.setter
+    def theme(self, value: str) -> None:
+        self._data["theme"] = value
+
+    @property
+    def reader_font_size(self) -> int:
+        val = _safe_int(self._data.get("reader_font_size", DEFAULT_FONT_SIZE), DEFAULT_FONT_SIZE)
+        return max(6, min(72, val))
+
+    @reader_font_size.setter
+    def reader_font_size(self, value: int) -> None:
+        self._data["reader_font_size"] = max(6, min(72, value))
+
+    @property
+    def last_book_id(self) -> str | None:
+        return self._data.get("last_book_id")
+
+    @last_book_id.setter
+    def last_book_id(self, value: str) -> None:
+        self._data["last_book_id"] = value
+
+    @property
+    def splitter_sizes(self) -> list[int]:
+        return list(self._data.get("splitter_sizes", READER_SPLITTER_RATIO))
+
+    @splitter_sizes.setter
+    def splitter_sizes(self, value: list[int]) -> None:
+        self._data["splitter_sizes"] = value
+
+    @property
+    def editor_console_sizes(self) -> list[int]:
+        return list(self._data.get("editor_console_sizes", EDITOR_CONSOLE_RATIO))
+
+    @editor_console_sizes.setter
+    def editor_console_sizes(self, value: list[int]) -> None:
+        self._data["editor_console_sizes"] = value
+
+    @property
+    def toc_width(self) -> int:
+        return _safe_int(self._data.get("toc_width", TOC_WIDTH), TOC_WIDTH)
+
+    @toc_width.setter
+    def toc_width(self, value: int) -> None:
+        self._data["toc_width"] = value
+
+    @property
+    def toc_visible(self) -> bool:
+        return bool(self._data.get("toc_visible", True))
+
+    @toc_visible.setter
+    def toc_visible(self, value: bool) -> None:
+        self._data["toc_visible"] = value
+
+
+class BooksConfig:
+    """Book registry configuration."""
+
+    def __init__(self) -> None:
+        self._data: dict[str, Any] = {}
+        self.load()
+
+    def load(self) -> None:
+        self._data = _load_json(BOOKS_CONFIG_PATH)
+        # Ensure "books" is a list (guard against corrupted JSON)
+        if not isinstance(self._data.get("books"), list):
+            self._data["books"] = []
+        # Migrate: ensure all entries have required keys
+        for book in self._data.get("books", []):
+            book.setdefault("language", "python")
+            book.setdefault("profile_name", "")
+
+    def save(self) -> None:
+        _save_json(BOOKS_CONFIG_PATH, self._data)
+
+    @property
+    def books(self) -> list[dict[str, Any]]:
+        return list(self._data.get("books", []))
+
+    def add_book(self, book_id: str, title: str, pdf_path: str,
+                 language: str = "python", profile_name: str = "") -> None:
+        books = self.books
+        for b in books:
+            if b["book_id"] == book_id:
+                b.update(title=title, pdf_path=pdf_path,
+                         language=language, profile_name=profile_name)
+                self._data["books"] = books
+                return
+        books.append({
+            "book_id": book_id,
+            "title": title,
+            "pdf_path": pdf_path,
+            "language": language,
+            "profile_name": profile_name,
+        })
+        self._data["books"] = books
+
+    def get_book(self, book_id: str) -> dict | None:
+        for b in self.books:
+            if b["book_id"] == book_id:
+                return b
+        return None
+
+    def remove_book(self, book_id: str) -> None:
+        self._data["books"] = [b for b in self.books if b["book_id"] != book_id]
+
+
+class EditorConfig:
+    """Code editor configuration."""
+
+    def __init__(self) -> None:
+        self._data: dict[str, Any] = {}
+        self.load()
+
+    def load(self) -> None:
+        self._data = _load_json(EDITOR_CONFIG_PATH)
+
+    def save(self) -> None:
+        _save_json(EDITOR_CONFIG_PATH, self._data)
+
+    @property
+    def font_size(self) -> int:
+        val = _safe_int(self._data.get("font_size", DEFAULT_EDITOR_FONT_SIZE), DEFAULT_EDITOR_FONT_SIZE)
+        return max(6, min(72, val))
+
+    @font_size.setter
+    def font_size(self, value: int) -> None:
+        self._data["font_size"] = max(6, min(72, value))
+
+    @property
+    def tab_width(self) -> int:
+        val = _safe_int(self._data.get("tab_width", DEFAULT_TAB_WIDTH), DEFAULT_TAB_WIDTH)
+        return max(1, min(16, val))
+
+    @tab_width.setter
+    def tab_width(self, value: int) -> None:
+        self._data["tab_width"] = max(1, min(16, value))
+
+    @property
+    def show_line_numbers(self) -> bool:
+        return bool(self._data.get("show_line_numbers", True))
+
+    @show_line_numbers.setter
+    def show_line_numbers(self, value: bool) -> None:
+        self._data["show_line_numbers"] = value
+
+    @property
+    def auto_indent(self) -> bool:
+        return bool(self._data.get("auto_indent", True))
+
+    @auto_indent.setter
+    def auto_indent(self, value: bool) -> None:
+        self._data["auto_indent"] = value
+
+    @property
+    def word_wrap(self) -> bool:
+        return bool(self._data.get("word_wrap", False))
+
+    @word_wrap.setter
+    def word_wrap(self, value: bool) -> None:
+        self._data["word_wrap"] = value
+
+    @property
+    def execution_timeout(self) -> int:
+        val = _safe_int(self._data.get("execution_timeout", DEFAULT_EXECUTION_TIMEOUT), DEFAULT_EXECUTION_TIMEOUT)
+        return max(5, min(300, val))
+
+    @execution_timeout.setter
+    def execution_timeout(self, value: int) -> None:
+        self._data["execution_timeout"] = max(5, min(300, value))
+
+    @property
+    def external_editor_path(self) -> str:
+        return str(self._data.get("external_editor_path", "notepad++.exe"))
+
+    @external_editor_path.setter
+    def external_editor_path(self, value: str) -> None:
+        self._data["external_editor_path"] = value
+
+    @property
+    def external_editor_enabled(self) -> bool:
+        return bool(self._data.get("external_editor_enabled", True))
+
+    @external_editor_enabled.setter
+    def external_editor_enabled(self, value: bool) -> None:
+        self._data["external_editor_enabled"] = value