risforge 0.2.0__tar.gz → 0.3.0__tar.gz

{risforge-0.2.0/src/risforge.egg-info → risforge-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: risforge
-Version: 0.2.0
+Version: 0.3.0
 Summary: Clean, deduplicate, and enrich RIS bibliographic files for systematic reviews.
 Author-email: Amyr <amyrhexa@gmail.com>
 License: MIT
@@ -32,6 +32,11 @@ Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: gui
+Requires-Dist: PySide6>=6.5; extra == "gui"
+Provides-Extra: gui-dev
+Requires-Dist: risforge[gui]; extra == "gui-dev"
+Requires-Dist: pytest-qt>=4.4; extra == "gui-dev"
 Dynamic: license-file
 
 # risforge
@@ -90,6 +95,8 @@ overlapping database exports — whether that's one export or several.
   enriched.
 - **Library or CLI** — use it as `import risforge` in a script/notebook,
   or as a single `risforge` command.
+- **Optional desktop GUI** — a cross-platform PySide6 app (`risforge-gui`)
+  for drag-and-drop use, with no command line required.
 
 ## Installation
 
@@ -99,6 +106,18 @@ pip install risforge
 
 Requires Python 3.10+.
 
+There's also an optional desktop GUI, for researchers who'd rather not use
+the command line:
+
+```bash
+pip install "risforge[gui]"
+risforge-gui
+```
+
+It's a thin PySide6 interface over this same package -- see
+[docs/gui.md](docs/gui.md) for the full walkthrough. The base install above
+never pulls in GUI dependencies.
+
 ## Quick start
 
 ### Command line

{risforge-0.2.0 → risforge-0.3.0}/README.md

@@ -54,6 +54,8 @@ overlapping database exports — whether that's one export or several.
   enriched.
 - **Library or CLI** — use it as `import risforge` in a script/notebook,
   or as a single `risforge` command.
+- **Optional desktop GUI** — a cross-platform PySide6 app (`risforge-gui`)
+  for drag-and-drop use, with no command line required.
 
 ## Installation
 
@@ -63,6 +65,18 @@ pip install risforge
 
 Requires Python 3.10+.
 
+There's also an optional desktop GUI, for researchers who'd rather not use
+the command line:
+
+```bash
+pip install "risforge[gui]"
+risforge-gui
+```
+
+It's a thin PySide6 interface over this same package -- see
+[docs/gui.md](docs/gui.md) for the full walkthrough. The base install above
+never pulls in GUI dependencies.
+
 ## Quick start
 
 ### Command line

{risforge-0.2.0 → risforge-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "risforge"
-version = "0.2.0"
+version = "0.3.0"
 description = "Clean, deduplicate, and enrich RIS bibliographic files for systematic reviews."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -50,6 +50,13 @@ dev = [
     "build>=1.2",
     "twine>=5.0",
 ]
+gui = [
+    "PySide6>=6.5",
+]
+gui-dev = [
+    "risforge[gui]",
+    "pytest-qt>=4.4",
+]
 
 [project.urls]
 Homepage = "https://github.com/amyr/risforge"
@@ -60,6 +67,9 @@ Changelog = "https://github.com/amyr/risforge/blob/main/CHANGELOG.md"
 [project.scripts]
 risforge = "risforge.cli:main"
 
+[project.gui-scripts]
+risforge-gui = "risforge_gui.app:main"
+
 [tool.setuptools.packages.find]
 where = ["src"]
 
@@ -68,3 +78,6 @@ where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.coverage.run]
+concurrency = ["thread"]

{risforge-0.2.0 → risforge-0.3.0}/src/risforge/__init__.py

@@ -51,7 +51,7 @@ from risforge.exceptions import RisForgeError, RisParsingError
 from risforge.merging import MergeResult, merge_ris_files
 from risforge.pipeline import PipelineResult, risforge, run_pipeline
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "clean_ris_file",

{risforge-0.2.0 → risforge-0.3.0}/src/risforge/enrichment.py

@@ -40,6 +40,7 @@ import json
 import logging
 import re
 import time
+from collections.abc import Callable
 from difflib import SequenceMatcher
 from pathlib import Path
 from typing import Any
@@ -375,6 +376,7 @@ class RisEnricher:
         output_path: str | Path,
         fail_report_path: str | Path = "failed_records.json",
         request_delay_seconds: float = 0.1,
+        progress_callback: Callable[[int, int], None] | None = None,
     ) -> dict[str, Any]:
         """Enrich every record in a RIS file and write the result.
 
@@ -387,6 +389,14 @@ class RisEnricher:
             request_delay_seconds: Delay between records, to stay
                 within provider rate limits beyond the built-in retry
                 policy.
+            progress_callback: Optional callback invoked as
+                ``progress_callback(processed_count, total_count)``
+                after each record is processed. Added for callers
+                (such as a GUI) that want to report determinate
+                progress during a potentially slow, network-bound
+                operation, without polling or duplicating this loop
+                elsewhere. Never called when omitted -- zero behavior
+                change for existing callers.
 
         Returns:
             The accumulated ``self.stats`` dict.
@@ -403,9 +413,12 @@ class RisEnricher:
             logger.error("Failed to parse RIS file: %s", error)
             return self.stats
 
+        total = len(records)
         enriched_records = []
-        for record in records:
+        for index, record in enumerate(records):
             enriched_records.append(self.enrich_record(record))
+            if progress_callback is not None:
+                progress_callback(index + 1, total)
             if request_delay_seconds:
                 time.sleep(request_delay_seconds)
 

{risforge-0.2.0 → risforge-0.3.0}/src/risforge/pipeline.py

@@ -24,7 +24,7 @@ pre-0.2.0 API -- including callers who used the original
 from __future__ import annotations
 
 import logging
-from collections.abc import Sequence
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
@@ -93,6 +93,8 @@ def risforge(
     email: str,
     merge_path: str | Path | None = None,
     fail_report_path: str | Path = "failed_records.json",
+    on_stage: Callable[[str, str], None] | None = None,
+    enrichment_progress: Callable[[int, int], None] | None = None,
 ) -> PipelineResult:
     """Run the full merge(optional) -> clean -> enrich pipeline end to end.
 
@@ -118,6 +120,19 @@ def risforge(
             Ignored for a single input, since no merge step runs.
         fail_report_path: Where a JSON report of unresolved records is
             written, if any.
+        on_stage: Optional callback invoked as ``on_stage(stage,
+            status)`` around each phase, with ``stage`` one of
+            ``"merge"`` (only when multiple inputs are given),
+            ``"clean"``, or ``"enrich"``, and ``status`` one of
+            ``"started"`` or ``"completed"``. Added for callers (such
+            as a GUI) that want to reflect pipeline progress without
+            polling the filesystem or reimplementing this function's
+            control flow. Never called when omitted.
+        enrichment_progress: Optional callback forwarded to
+            :meth:`risforge.enrichment.RisEnricher.enrich_file` as
+            ``progress_callback``, invoked as
+            ``enrichment_progress(processed_count, total_count)``
+            after each record. Never called when omitted.
 
     Returns:
         A :class:`PipelineResult` summarizing every phase that ran.
@@ -139,7 +154,11 @@ def risforge(
             Path(merge_path) if merge_path is not None else _default_merge_path(dedup_path)
         )
         logger.info("Phase 0: Merging %d input files into %s", len(paths), resolved_merge_path)
+        if on_stage is not None:
+            on_stage("merge", "started")
         merge_result = merge_ris_files(paths, resolved_merge_path)
+        if on_stage is not None:
+            on_stage("merge", "completed")
         logger.info(
             "Phase 0 complete: merged %d record(s) from %d file(s).",
             merge_result.record_count,
@@ -150,18 +169,27 @@ def risforge(
         clean_input = paths[0]
 
     logger.info("Phase 1: Deduplicating %s", clean_input)
+    if on_stage is not None:
+        on_stage("clean", "started")
     records, errors = clean_ris_file(clean_input, dedup_path)
+    if on_stage is not None:
+        on_stage("clean", "completed")
     logger.info("Phase 1 complete: generated %d clean records.", len(records))
     if errors:
         logger.warning("Encountered %d parsing errors during Phase 1.", len(errors))
 
     logger.info("Phase 2: Initializing metadata enrichment via APIs")
+    if on_stage is not None:
+        on_stage("enrich", "started")
     enricher = RisEnricher(email=email)
     stats = enricher.enrich_file(
         input_path=dedup_path,
         output_path=enriched_path,
         fail_report_path=fail_report_path,
+        progress_callback=enrichment_progress,
     )
+    if on_stage is not None:
+        on_stage("enrich", "completed")
     logger.info(
         "Phase 2 complete: enriched %d/%d records.",
         stats.get("enriched", 0),

{risforge-0.2.0 → risforge-0.3.0/src/risforge.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: risforge
-Version: 0.2.0
+Version: 0.3.0
 Summary: Clean, deduplicate, and enrich RIS bibliographic files for systematic reviews.
 Author-email: Amyr <amyrhexa@gmail.com>
 License: MIT
@@ -32,6 +32,11 @@ Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: gui
+Requires-Dist: PySide6>=6.5; extra == "gui"
+Provides-Extra: gui-dev
+Requires-Dist: risforge[gui]; extra == "gui-dev"
+Requires-Dist: pytest-qt>=4.4; extra == "gui-dev"
 Dynamic: license-file
 
 # risforge
@@ -90,6 +95,8 @@ overlapping database exports — whether that's one export or several.
   enriched.
 - **Library or CLI** — use it as `import risforge` in a script/notebook,
   or as a single `risforge` command.
+- **Optional desktop GUI** — a cross-platform PySide6 app (`risforge-gui`)
+  for drag-and-drop use, with no command line required.
 
 ## Installation
 
@@ -99,6 +106,18 @@ pip install risforge
 
 Requires Python 3.10+.
 
+There's also an optional desktop GUI, for researchers who'd rather not use
+the command line:
+
+```bash
+pip install "risforge[gui]"
+risforge-gui
+```
+
+It's a thin PySide6 interface over this same package -- see
+[docs/gui.md](docs/gui.md) for the full walkthrough. The base install above
+never pulls in GUI dependencies.
+
 ## Quick start
 
 ### Command line

risforge-0.3.0/src/risforge.egg-info/SOURCES.txt

@@ -0,0 +1,36 @@
+LICENSE
+README.md
+pyproject.toml
+src/risforge/__init__.py
+src/risforge/cleaning.py
+src/risforge/cli.py
+src/risforge/enrichment.py
+src/risforge/exceptions.py
+src/risforge/merging.py
+src/risforge/pipeline.py
+src/risforge.egg-info/PKG-INFO
+src/risforge.egg-info/SOURCES.txt
+src/risforge.egg-info/dependency_links.txt
+src/risforge.egg-info/entry_points.txt
+src/risforge.egg-info/requires.txt
+src/risforge.egg-info/top_level.txt
+src/risforge_gui/__init__.py
+src/risforge_gui/app.py
+src/risforge_gui/dialogs.py
+src/risforge_gui/file_counter.py
+src/risforge_gui/main_window.py
+src/risforge_gui/models.py
+src/risforge_gui/theme.py
+src/risforge_gui/worker.py
+src/risforge_gui/widgets/__init__.py
+src/risforge_gui/widgets/config_panel.py
+src/risforge_gui/widgets/input_panel.py
+src/risforge_gui/widgets/log_panel.py
+src/risforge_gui/widgets/output_panel.py
+src/risforge_gui/widgets/progress_panel.py
+src/risforge_gui/widgets/results_panel.py
+tests/test_cleaning.py
+tests/test_cli.py
+tests/test_enrichment.py
+tests/test_merging.py
+tests/test_pipeline.py

risforge-0.3.0/src/risforge.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+risforge = risforge.cli:main
+
+[gui_scripts]
+risforge-gui = risforge_gui.app:main

{risforge-0.2.0 → risforge-0.3.0}/src/risforge.egg-info/requires.txt

@@ -8,3 +8,10 @@ pytest>=8.0
 pytest-cov>=5.0
 build>=1.2
 twine>=5.0
+
+[gui]
+PySide6>=6.5
+
+[gui-dev]
+risforge[gui]
+pytest-qt>=4.4

risforge-0.3.0/src/risforge.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+risforge
+risforge_gui

risforge-0.3.0/src/risforge_gui/__init__.py

@@ -0,0 +1,21 @@
+"""risforge_gui: a desktop GUI for the risforge package.
+
+This is a thin PySide6 presentation layer over the ``risforge`` core
+library -- it contains no merging, cleaning, deduplication, or
+enrichment logic of its own. Every operation it performs is a direct
+call into the public ``risforge`` API (:func:`risforge.risforge`,
+:func:`risforge.merge_ris_files`, :func:`risforge.clean_ris_file`,
+:class:`risforge.RisEnricher`).
+
+Deliberately not imported here: PySide6. Importing this top-level
+package should never require the GUI extra to be installed; only
+:mod:`risforge_gui.app` (the entry point) and the widget modules it
+pulls in do that. This keeps ``import risforge_gui`` itself cheap and
+side-effect-free, consistent with how ``risforge`` (the core package)
+never imports GUI dependencies.
+
+Install with the GUI extra and launch via the console entry point::
+
+    pip install "risforge[gui]"
+    risforge-gui
+"""

risforge-0.3.0/src/risforge_gui/app.py

@@ -0,0 +1,34 @@
+"""Entry point for the ``risforge-gui`` command."""
+
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    try:
+        from PySide6.QtWidgets import QApplication
+    except ImportError:
+        print(
+            "risforge-gui requires the GUI extras, which aren't installed.\n\n"
+            '    pip install "risforge[gui]"\n',
+            file=sys.stderr,
+        )
+        raise SystemExit(1) from None
+
+    from risforge_gui.main_window import MainWindow
+    from risforge_gui.theme import Theme, apply_theme
+
+    app = QApplication(sys.argv)
+    app.setApplicationName("risforge")
+    apply_theme(app, Theme.SYSTEM)
+
+    window = MainWindow()
+    window.resize(1100, 780)
+    window.show()
+
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    main()

risforge-0.3.0/src/risforge_gui/dialogs.py

@@ -0,0 +1,49 @@
+"""Error and confirmation dialogs.
+
+Errors are always shown with a plain-language message first. Technical
+detail (exception repr / traceback) is available but hidden behind
+Qt's built-in "Show Details..." expander -- never shown by default.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PySide6.QtWidgets import QMessageBox, QWidget
+
+
+def show_error_dialog(
+    parent: QWidget | None,
+    title: str,
+    message: str,
+    details: str = "",
+    affected_file: str = "",
+) -> None:
+    """Show a human-readable error, with technical details available on demand."""
+    box = QMessageBox(parent)
+    box.setIcon(QMessageBox.Icon.Critical)
+    box.setWindowTitle("risforge")
+    box.setText(title)
+
+    informative = message
+    if affected_file:
+        informative = f"File: {affected_file}\n\n{message}"
+    box.setInformativeText(informative)
+
+    if details:
+        box.setDetailedText(details)
+
+    box.setStandardButtons(QMessageBox.StandardButton.Ok)
+    box.exec()
+
+
+def confirm_overwrite(parent: QWidget | None, path: Path) -> bool:
+    """Ask before overwriting an existing output file. Defaults to No (safe)."""
+    result = QMessageBox.question(
+        parent,
+        "File already exists",
+        f"A file already exists at:\n{path}\n\nOverwrite it?",
+        QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No,
+        QMessageBox.StandardButton.No,
+    )
+    return result == QMessageBox.StandardButton.Yes

risforge-0.3.0/src/risforge_gui/file_counter.py

@@ -0,0 +1,41 @@
+"""Asynchronous record counting for the input files table.
+
+Counting records requires actually parsing the file, so it's done off
+the GUI thread via QThreadPool. The parsing itself is not
+reimplemented here -- it's the exact same
+``risforge.cleaning.parse_ris_records`` used by cleaning and merging,
+so a file's reported record count always matches what merge/clean
+will actually do with it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PySide6.QtCore import QObject, QRunnable, Signal
+
+from risforge.cleaning import parse_ris_records
+
+
+class _CounterSignals(QObject):
+    finished = Signal(Path, int, int)  # path, record_count, malformed_block_count
+    failed = Signal(Path, str)  # path, human-readable error message
+
+
+class RecordCounter(QRunnable):
+    """Counts records in one RIS file on a background thread pool."""
+
+    def __init__(self, path: Path) -> None:
+        super().__init__()
+        self._path = path
+        self.signals = _CounterSignals()
+
+    def run(self) -> None:  # noqa: D102 -- QRunnable interface
+        try:
+            records, errors = parse_ris_records(self._path)
+        except FileNotFoundError:
+            self.signals.failed.emit(self._path, "File not found.")
+        except OSError as error:
+            self.signals.failed.emit(self._path, f"Could not read file: {error}")
+        else:
+            self.signals.finished.emit(self._path, len(records), len(errors))