risforge 0.3.2__tar.gz → 0.3.3__tar.gz

{risforge-0.3.2/src/risforge.egg-info → risforge-0.3.3}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: risforge
-Version: 0.3.2
+Version: 0.3.3
 Summary: Clean, deduplicate, and enrich RIS bibliographic files for systematic reviews.
 Author-email: Amyr <amyrhexa@gmail.com>
 License: MIT
-Project-URL: Homepage, https://github.com/pythyn/risforge
-Project-URL: Repository, https://github.com/pythyn/risforge
-Project-URL: Issues, https://github.com/pythyn/risforge/issues
-Project-URL: Changelog, https://github.com/pythyn/risforge/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/amyr/risforge
+Project-URL: Repository, https://github.com/amyr/risforge
+Project-URL: Issues, https://github.com/amyr/risforge/issues
+Project-URL: Changelog, https://github.com/amyr/risforge/blob/main/CHANGELOG.md
 Keywords: ris,bibliography,systematic-review,deduplication,crossref,openalex,citation-management,prisma
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research

{risforge-0.3.2 → risforge-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "risforge"
-version = "0.3.2"
+version = "0.3.3"
 description = "Clean, deduplicate, and enrich RIS bibliographic files for systematic reviews."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -59,10 +59,10 @@ gui-dev = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/pythyn/risforge"
-Repository = "https://github.com/pythyn/risforge"
-Issues = "https://github.com/pythyn/risforge/issues"
-Changelog = "https://github.com/pythyn/risforge/blob/main/CHANGELOG.md"
+Homepage = "https://github.com/amyr/risforge"
+Repository = "https://github.com/amyr/risforge"
+Issues = "https://github.com/amyr/risforge/issues"
+Changelog = "https://github.com/amyr/risforge/blob/main/CHANGELOG.md"
 
 [project.scripts]
 risforge = "risforge.cli:main"
@@ -81,3 +81,10 @@ testpaths = ["tests"]
 
 [tool.coverage.run]
 concurrency = ["thread"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310", "py311", "py312"]
+
+[tool.ruff]
+line-length = 100

{risforge-0.3.2 → risforge-0.3.3}/src/risforge/__init__.py

@@ -51,17 +51,17 @@ from risforge.exceptions import RisForgeError, RisParsingError
 from risforge.merging import MergeResult, merge_ris_files
 from risforge.pipeline import PipelineResult, risforge, run_pipeline
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 
 __all__ = [
-    "clean_ris_file",
-    "process_ris_file",
-    "RisEnricher",
-    "merge_ris_files",
     "MergeResult",
-    "risforge",
-    "run_pipeline",
     "PipelineResult",
+    "RisEnricher",
     "RisForgeError",
     "RisParsingError",
+    "clean_ris_file",
+    "merge_ris_files",
+    "process_ris_file",
+    "risforge",
+    "run_pipeline",
 ]

{risforge-0.3.2 → risforge-0.3.3}/src/risforge/cleaning.py

@@ -147,11 +147,7 @@ def merge_cluster(cluster: list[RisRecord]) -> RisRecord:
                 for item in value:
                     if item not in merged[key]:
                         merged[key].append(item)
-            elif (
-                isinstance(merged[key], str)
-                and not merged[key]
-                and isinstance(value, str)
-            ):
+            elif isinstance(merged[key], str) and not merged[key] and isinstance(value, str):
                 merged[key] = value
 
     return merged
@@ -346,9 +342,7 @@ def clean_ris_file(
     for index in range(total_records):
         clusters[union_find.find(index)].append(index)
 
-    final_records = [
-        merge_cluster([records[i] for i in indices]) for indices in clusters.values()
-    ]
+    final_records = [merge_cluster([records[i] for i in indices]) for indices in clusters.values()]
 
     total_duplicates_removed = doi_duplicates_removed + title_author_duplicates_removed
 

{risforge-0.3.2 → risforge-0.3.3}/src/risforge/cli.py

@@ -48,9 +48,7 @@ def _configure_logging(verbose: bool) -> None:
 
 
 def _add_common_args(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument(
-        "-v", "--verbose", action="store_true", help="Enable debug-level logging."
-    )
+    parser.add_argument("-v", "--verbose", action="store_true", help="Enable debug-level logging.")
 
 
 def _cmd_merge(args: argparse.Namespace) -> int:
@@ -188,9 +186,7 @@ def build_parser() -> argparse.ArgumentParser:
     _add_common_args(merge_parser)
     merge_parser.set_defaults(func=_cmd_merge)
 
-    clean_parser = subparsers.add_parser(
-        "clean", help="Deduplicate and normalize a RIS file."
-    )
+    clean_parser = subparsers.add_parser("clean", help="Deduplicate and normalize a RIS file.")
     clean_parser.add_argument("input", help="Input RIS file path.")
     clean_parser.add_argument("output", help="Output cleaned RIS file path.")
     clean_parser.add_argument(

{risforge-0.3.2 → risforge-0.3.3}/src/risforge/enrichment.py

@@ -74,6 +74,7 @@ from risforge.cleaning import parse_ris_records
 
 TITLE_MATCH_THRESHOLD = 0.90
 CACHE_EXPIRE_DAYS = 7
+REQUEST_TIMEOUT_SECONDS = 10  # Applied to every provider HTTP call; retries/backoff are separate.
 
 logger = logging.getLogger(__name__)
 
@@ -155,9 +156,7 @@ class RisEnricher:
         }
         self.failed_records: list[dict[str, Any]] = []
         self.session = session or _build_default_session(str(cache_name))
-        self.session.headers.update(
-            {"User-Agent": f"risforge/1.0 (mailto:{self.email})"}
-        )
+        self.session.headers.update({"User-Agent": f"risforge/1.0 (mailto:{self.email})"})
 
     # --- Core identification -------------------------------------------------
 
@@ -191,7 +190,7 @@ class RisEnricher:
             f"&select=DOI,title&rows=3&mailto={self.email}"
         )
         try:
-            response = self.session.get(url, timeout=10)
+            response = self.session.get(url, timeout=REQUEST_TIMEOUT_SECONDS)
             self.stats["api_calls"]["crossref"] += 1
 
             if response.status_code == 200:
@@ -216,7 +215,7 @@ class RisEnricher:
         """Fetch authoritative bibliographic metadata from Crossref."""
         url = f"https://api.crossref.org/works/{quote(doi)}?mailto={self.email}"
         try:
-            response = self.session.get(url, timeout=10)
+            response = self.session.get(url, timeout=REQUEST_TIMEOUT_SECONDS)
             self.stats["api_calls"]["crossref"] += 1
 
             if response.status_code == 200:
@@ -273,15 +272,15 @@ class RisEnricher:
         """Fetch open-access status and subject concepts from OpenAlex."""
         url = f"https://api.openalex.org/works/doi:{quote(doi)}?mailto={self.email}"
         try:
-            response = self.session.get(url, timeout=10)
+            response = self.session.get(url, timeout=REQUEST_TIMEOUT_SECONDS)
             self.stats["api_calls"]["openalex"] += 1
 
             if response.status_code == 200:
                 payload = response.json()
                 concepts = [
-                    c.get("display_name")
-                    for c in payload.get("concepts", [])
-                    if c.get("level", 99) <= 1 and c.get("display_name")
+                    concept.get("display_name")
+                    for concept in payload.get("concepts", [])
+                    if concept.get("level", 99) <= 1 and concept.get("display_name")
                 ]
                 oa_url = payload.get("open_access", {}).get("oa_url")
                 return {
@@ -302,7 +301,7 @@ class RisEnricher:
             f"?fields=abstract,referenceCount,citationCount"
         )
         try:
-            response = self.session.get(url, timeout=10)
+            response = self.session.get(url, timeout=REQUEST_TIMEOUT_SECONDS)
             self.stats["api_calls"]["semanticscholar"] += 1
 
             if response.status_code == 200:
@@ -318,7 +317,7 @@ class RisEnricher:
         """Fetch the best open-access PDF location from Unpaywall."""
         url = f"https://api.unpaywall.org/v2/{quote(doi)}?email={self.email}"
         try:
-            response = self.session.get(url, timeout=10)
+            response = self.session.get(url, timeout=REQUEST_TIMEOUT_SECONDS)
             self.stats["api_calls"]["unpaywall"] += 1
 
             if response.status_code == 200:

{risforge-0.3.2 → risforge-0.3.3}/src/risforge/merging.py

@@ -106,9 +106,7 @@ def merge_ris_files(
                 len(errors),
                 path,
             )
-        all_errors.extend(
-            (path, block_number, message) for block_number, message in errors
-        )
+        all_errors.extend((path, block_number, message) for block_number, message in errors)
         all_records.extend(records)
         logger.info("%s: %d record(s) parsed.", path, len(records))
 

{risforge-0.3.2 → risforge-0.3.3/src/risforge.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: risforge
-Version: 0.3.2
+Version: 0.3.3
 Summary: Clean, deduplicate, and enrich RIS bibliographic files for systematic reviews.
 Author-email: Amyr <amyrhexa@gmail.com>
 License: MIT
-Project-URL: Homepage, https://github.com/pythyn/risforge
-Project-URL: Repository, https://github.com/pythyn/risforge
-Project-URL: Issues, https://github.com/pythyn/risforge/issues
-Project-URL: Changelog, https://github.com/pythyn/risforge/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/amyr/risforge
+Project-URL: Repository, https://github.com/amyr/risforge
+Project-URL: Issues, https://github.com/amyr/risforge/issues
+Project-URL: Changelog, https://github.com/amyr/risforge/blob/main/CHANGELOG.md
 Keywords: ris,bibliography,systematic-review,deduplication,crossref,openalex,citation-management,prisma
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research

risforge-0.3.3/src/risforge_gui/app.py

@@ -0,0 +1,48 @@
+"""Entry point for the ``risforge-gui`` command."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+def main() -> None:
+    """Launch the risforge desktop application.
+
+    Registered as the ``risforge-gui`` console entry point. The GUI
+    extra (PySide6) is optional at the package level, so this is the
+    one place that has to tolerate it being absent -- everything past
+    the import guard below assumes it's installed.
+    """
+    try:
+        from PySide6.QtWidgets import QApplication
+    except ImportError:
+        # No logging handler is configured yet at this point (that's
+        # normally the CLI's or the GUI's own job, and we haven't
+        # reached either), but an unconfigured logger's "last resort"
+        # handler still writes ERROR+ to stderr, so this is exactly as
+        # visible to the user as a plain print() would have been.
+        logger.error(
+            "risforge-gui requires the GUI extras, which aren't installed.\n\n"
+            '    pip install "risforge[gui]"\n'
+        )
+        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.2 → risforge-0.3.3}/src/risforge_gui/file_counter.py

@@ -30,12 +30,21 @@ class RecordCounter(QRunnable):
         self._path = path
         self.signals = _CounterSignals()
 
-    def run(self) -> None:  # noqa: D102 -- QRunnable interface
+    def run(self) -> None:
+        """Parse the file and report success/failure via signals.
+
+        Catches ValueError alongside OSError specifically because
+        ``parse_ris_records`` raises ``RisParsingError`` (a ValueError
+        subclass) for files that can't be decoded as text -- without
+        this, such a file would raise out of a QThreadPool worker
+        uncaught, and its row would be stuck at "Counting..." forever
+        with no visible error at all.
+        """
         try:
             records, errors = parse_ris_records(self._path)
         except FileNotFoundError:
             self.signals.failed.emit(self._path, "File not found.")
-        except OSError as error:
+        except (OSError, ValueError) 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))

{risforge-0.3.2 → risforge-0.3.3}/src/risforge_gui/main_window.py

@@ -11,7 +11,6 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from PySide6.QtCore import Qt
 from PySide6.QtWidgets import (
     QComboBox,
     QGroupBox,
@@ -201,9 +200,16 @@ class MainWindow(QMainWindow):
                 if input_count > 1
                 else "Deduplicates and enriches your input file."
             ),
-            OperationMode.MERGE: "Combines every input file's records into one file. Does not deduplicate or enrich.",
-            OperationMode.CLEAN: "Deduplicates a single RIS file. Requires exactly one input file.",
-            OperationMode.ENRICH: "Fills in missing metadata for a single, already-clean RIS file. Requires exactly one input file.",
+            OperationMode.MERGE: (
+                "Combines every input file's records into one file. Does not deduplicate or enrich."
+            ),
+            OperationMode.CLEAN: (
+                "Deduplicates a single RIS file. Requires exactly one input file."
+            ),
+            OperationMode.ENRICH: (
+                "Fills in missing metadata for a single, already-clean RIS file. "
+                "Requires exactly one input file."
+            ),
         }
         self.mode_hint_label.setText(hints[mode])
 
@@ -238,15 +244,17 @@ class MainWindow(QMainWindow):
         input_paths = self.input_panel.model.paths()
 
         if not input_paths:
-            QMessageBox.warning(self, "No input files", "Add at least one .ris file before starting.")
+            QMessageBox.warning(
+                self, "No input files", "Add at least one .ris file before starting."
+            )
             return None
 
         if mode is OperationMode.CLEAN and len(input_paths) != 1:
             QMessageBox.warning(
                 self,
                 "Too many input files",
-                "\"Clean only\" works on exactly one file. Either remove the extra files, "
-                "or use \"Merge only\" first to combine them into one.",
+                '"Clean only" works on exactly one file. Either remove the extra files, '
+                'or use "Merge only" first to combine them into one.',
             )
             return None
 
@@ -254,7 +262,7 @@ class MainWindow(QMainWindow):
             QMessageBox.warning(
                 self,
                 "Too many input files",
-                "\"Enrich only\" works on exactly one file. Remove the extra files first.",
+                '"Enrich only" works on exactly one file. Remove the extra files first.',
             )
             return None
 
@@ -280,11 +288,15 @@ class MainWindow(QMainWindow):
             )
             return None
 
-        result_name = self.output_panel.final_name_edit.text().strip() or _DEFAULT_NAME_BY_MODE[mode]
+        result_name = (
+            self.output_panel.final_name_edit.text().strip() or _DEFAULT_NAME_BY_MODE[mode]
+        )
         result_path = output_dir / result_name
         merge_path = output_dir / "merged.ris"
         dedup_path = output_dir / "clean.ris"
-        fail_report_path = _resolve_relative_to(self.enrichment_panel.fail_report_name(), output_dir)
+        fail_report_path = _resolve_relative_to(
+            self.enrichment_panel.fail_report_name(), output_dir
+        )
 
         outputs_to_check = {result_path}
         if mode is OperationMode.PIPELINE:

{risforge-0.3.2 → risforge-0.3.3}/src/risforge_gui/models.py

@@ -16,6 +16,8 @@ from PySide6.QtCore import QAbstractTableModel, QModelIndex, Qt
 
 @dataclass
 class InputFileEntry:
+    """One row's state: a file path plus its (possibly still-pending) record count."""
+
     path: Path
     record_count: int | None = None  # None while counting is in progress.
     status: str = "Counting..."
@@ -33,18 +35,30 @@ class InputFilesModel(QAbstractTableModel):
 
     # --- Qt model interface -----------------------------------------------
 
-    def rowCount(self, parent: QModelIndex = QModelIndex()) -> int:  # noqa: N802
+    def rowCount(self, parent: QModelIndex = QModelIndex()) -> int:  # noqa: B008
+        # QModelIndex() as a default is the standard Qt Model/View idiom
+        # (used verbatim in Qt's own documentation): it's an immutable
+        # "invalid index" value, not mutable state that could leak
+        # between calls, so constructing it once at import time is safe.
         return 0 if parent.isValid() else len(self._entries)
 
-    def columnCount(self, parent: QModelIndex = QModelIndex()) -> int:  # noqa: N802
+    def columnCount(self, parent: QModelIndex = QModelIndex()) -> int:  # noqa: B008
         return 0 if parent.isValid() else len(self.COLUMNS)
 
-    def headerData(self, section, orientation, role=Qt.ItemDataRole.DisplayRole):  # noqa: N802
+    def headerData(self, section, orientation, role=Qt.ItemDataRole.DisplayRole):
         if orientation == Qt.Orientation.Horizontal and role == Qt.ItemDataRole.DisplayRole:
             return self.COLUMNS[section]
         return None
 
     def data(self, index: QModelIndex, role: int = Qt.ItemDataRole.DisplayRole):
+        """Return display/tooltip/alignment data for one cell.
+
+        Branches on ``role`` because Qt's view asks the model the same
+        question ("what goes in this cell?") several times with
+        different intents -- text to show, tooltip to show, how to
+        align it -- rather than the model exposing separate methods
+        per concern.
+        """
         if not index.isValid() or not (0 <= index.row() < len(self._entries)):
             return None
         entry = self._entries[index.row()]
@@ -66,7 +80,8 @@ class InputFilesModel(QAbstractTableModel):
             return Qt.AlignmentFlag.AlignRight | Qt.AlignmentFlag.AlignVCenter
         return None
 
-    def flags(self, index: QModelIndex):  # noqa: N802
+    def flags(self, index: QModelIndex):
+        """Selectable but never editable -- this table is for review, not inline editing."""
         if not index.isValid():
             return Qt.ItemFlag.NoItemFlags
         return Qt.ItemFlag.ItemIsEnabled | Qt.ItemFlag.ItemIsSelectable
@@ -129,7 +144,7 @@ class InputFilesModel(QAbstractTableModel):
                 return
 
     def total_known_records(self) -> int | None:
-        """Sum of record counts for entries that finished counting, or None if any are still pending/errored."""
+        """Sum of counted records, or None while any entry is still pending/errored."""
         if any(entry.record_count is None for entry in self._entries):
             return None
         return sum(entry.record_count or 0 for entry in self._entries)

{risforge-0.3.2 → risforge-0.3.3}/src/risforge_gui/theme.py

@@ -19,6 +19,8 @@ from PySide6.QtWidgets import QApplication
 
 
 class Theme(str, Enum):
+    """Selectable appearance modes; SYSTEM defers to the OS light/dark preference."""
+
     LIGHT = "light"
     DARK = "dark"
     SYSTEM = "system"
@@ -61,7 +63,7 @@ DARK_PALETTE: dict[str, str] = {
 }
 
 
-def _build_stylesheet(p: dict[str, str]) -> str:
+def _build_stylesheet(palette: dict[str, str]) -> str:
     """Render a palette dict into a Qt stylesheet.
 
     Kept as one template so the two palettes can never drift into
@@ -69,18 +71,18 @@ def _build_stylesheet(p: dict[str, str]) -> str:
     """
     return f"""
     QWidget {{
-        background-color: {p['bg']};
-        color: {p['text']};
+        background-color: {palette["bg"]};
+        color: {palette["text"]};
         font-size: 13px;
     }}
 
     QMainWindow, #SetupPage, #ProgressPage, #ResultsPage {{
-        background-color: {p['bg']};
+        background-color: {palette["bg"]};
     }}
 
     QGroupBox {{
-        background-color: {p['surface']};
-        border: 1px solid {p['border']};
+        background-color: {palette["surface"]};
+        border: 1px solid {palette["border"]};
         border-radius: 6px;
         margin-top: 14px;
         padding: 12px;
@@ -90,7 +92,7 @@ def _build_stylesheet(p: dict[str, str]) -> str:
         subcontrol-origin: margin;
         left: 10px;
         padding: 0 4px;
-        color: {p['text']};
+        color: {palette["text"]};
     }}
 
     QLabel#HeaderTitle {{
@@ -98,10 +100,10 @@ def _build_stylesheet(p: dict[str, str]) -> str:
         font-weight: 700;
     }}
     QLabel#HeaderSubtitle, QLabel#MutedLabel, QLabel#HelperText {{
-        color: {p['text_muted']};
+        color: {palette["text_muted"]};
     }}
     QLabel#VersionLabel {{
-        color: {p['text_muted']};
+        color: {palette["text_muted"]};
         font-size: 11px;
     }}
     QLabel#SectionHeading {{
@@ -110,82 +112,82 @@ def _build_stylesheet(p: dict[str, str]) -> str:
     }}
 
     QPushButton {{
-        background-color: {p['surface']};
-        border: 1px solid {p['border']};
+        background-color: {palette["surface"]};
+        border: 1px solid {palette["border"]};
         border-radius: 5px;
         padding: 6px 14px;
     }}
     QPushButton:hover {{
-        border-color: {p['accent']};
+        border-color: {palette["accent"]};
     }}
     QPushButton:pressed {{
-        background-color: {p['surface_alt']};
+        background-color: {palette["surface_alt"]};
     }}
     QPushButton:disabled {{
-        color: {p['text_muted']};
+        color: {palette["text_muted"]};
     }}
     QPushButton#PrimaryButton {{
-        background-color: {p['accent']};
-        color: {p['accent_text']};
+        background-color: {palette["accent"]};
+        color: {palette["accent_text"]};
         border: none;
         font-weight: 600;
         padding: 8px 20px;
     }}
     QPushButton#PrimaryButton:hover {{
-        background-color: {p['accent_hover']};
+        background-color: {palette["accent_hover"]};
     }}
     QPushButton#PrimaryButton:disabled {{
-        background-color: {p['border']};
-        color: {p['text_muted']};
+        background-color: {palette["border"]};
+        color: {palette["text_muted"]};
     }}
 
     QLineEdit, QSpinBox, QDoubleSpinBox, QComboBox {{
-        background-color: {p['surface']};
-        border: 1px solid {p['border']};
+        background-color: {palette["surface"]};
+        border: 1px solid {palette["border"]};
         border-radius: 4px;
         padding: 4px 6px;
-        selection-background-color: {p['accent']};
+        selection-background-color: {palette["accent"]};
     }}
     QLineEdit:focus, QSpinBox:focus, QDoubleSpinBox:focus, QComboBox:focus {{
-        border: 1px solid {p['focus']};
+        border: 1px solid {palette["focus"]};
     }}
     QLineEdit:read-only {{
-        color: {p['text_muted']};
+        color: {palette["text_muted"]};
     }}
 
     QTableView {{
-        background-color: {p['surface']};
-        alternate-background-color: {p['surface_alt']};
-        gridline-color: {p['border']};
-        border: 1px solid {p['border']};
+        background-color: {palette["surface"]};
+        alternate-background-color: {palette["surface_alt"]};
+        gridline-color: {palette["border"]};
+        border: 1px solid {palette["border"]};
         border-radius: 4px;
-        selection-background-color: {p['accent']};
-        selection-color: {p['accent_text']};
+        selection-background-color: {palette["accent"]};
+        selection-color: {palette["accent_text"]};
     }}
     QHeaderView::section {{
-        background-color: {p['surface_alt']};
-        color: {p['text']};
+        background-color: {palette["surface_alt"]};
+        color: {palette["text"]};
         border: none;
-        border-bottom: 1px solid {p['border']};
+        border-bottom: 1px solid {palette["border"]};
         padding: 4px 6px;
         font-weight: 600;
     }}
 
     QProgressBar {{
-        background-color: {p['surface_alt']};
-        border: 1px solid {p['border']};
+        background-color: {palette["surface_alt"]};
+        border: 1px solid {palette["border"]};
         border-radius: 4px;
         text-align: center;
         height: 18px;
     }}
     QProgressBar::chunk {{
-        background-color: {p['accent']};
+        background-color: {palette["accent"]};
         border-radius: 3px;
     }}
 
     QPlainTextEdit#LogPanel {{
-        background-color: {p['surface']};
-        border: 1px solid {p['border']};
+        background-color: {palette["surface"]};
+        border: 1px solid {palette["border"]};
         border-radius: 4px;
         font-family: "Menlo", "Consolas", monospace;
         font-size: 12px;
@@ -193,10 +195,10 @@ def _build_stylesheet(p: dict[str, str]) -> str:
 
     QToolButton {{
         border: none;
-        color: {p['text_muted']};
+        color: {palette["text_muted"]};
     }}
     QToolButton:hover {{
-        color: {p['text']};
+        color: {palette["text"]};
     }}
 
     QScrollArea {{
@@ -208,7 +210,7 @@ def _build_stylesheet(p: dict[str, str]) -> str:
         outline: none;
     }}
     QPushButton:focus, QComboBox:focus, QCheckBox:focus {{
-        border: 2px solid {p['focus']};
+        border: 2px solid {palette["focus"]};
     }}
     """
 

{risforge-0.3.2 → risforge-0.3.3}/src/risforge_gui/widgets/config_panel.py

@@ -29,7 +29,7 @@ def default_cache_path() -> Path:
 
 
 class EnrichmentConfigPanel(QGroupBox):
-    """"Enrichment settings" group box."""
+    """ "Enrichment settings" group box."""
 
     changed = Signal()
 
@@ -119,7 +119,10 @@ class EnrichmentConfigPanel(QGroupBox):
 
     def _browse_fail_report(self) -> None:
         path, _filter = QFileDialog.getSaveFileName(
-            self, "Choose failure report location", self.fail_report_edit.text(), "JSON files (*.json)"
+            self,
+            "Choose failure report location",
+            self.fail_report_edit.text(),
+            "JSON files (*.json)",
         )
         if path:
             self.fail_report_edit.setText(path)

{risforge-0.3.2 → risforge-0.3.3}/src/risforge_gui/widgets/input_panel.py

@@ -25,7 +25,7 @@ from risforge_gui.models import InputFilesModel
 
 
 class InputPanel(QGroupBox):
-    """"Input files" group box: table + add/remove controls + drag-and-drop."""
+    """ "Input files" group box: table + add/remove controls + drag-and-drop."""
 
     files_changed = Signal()
 
@@ -57,8 +57,12 @@ class InputPanel(QGroupBox):
         self.table.setAlternatingRowColors(True)
         self.table.horizontalHeader().setStretchLastSection(False)
         self.table.horizontalHeader().setSectionResizeMode(0, QHeaderView.ResizeMode.Stretch)
-        self.table.horizontalHeader().setSectionResizeMode(1, QHeaderView.ResizeMode.ResizeToContents)
-        self.table.horizontalHeader().setSectionResizeMode(2, QHeaderView.ResizeMode.ResizeToContents)
+        self.table.horizontalHeader().setSectionResizeMode(
+            1, QHeaderView.ResizeMode.ResizeToContents
+        )
+        self.table.horizontalHeader().setSectionResizeMode(
+            2, QHeaderView.ResizeMode.ResizeToContents
+        )
         self.table.verticalHeader().setVisible(False)
         self.table.setMinimumHeight(140)
         self.table.setAccessibleName("Input files table")
@@ -103,7 +107,9 @@ class InputPanel(QGroupBox):
         folder = QFileDialog.getExistingDirectory(self, "Add folder of RIS files", str(Path.home()))
         if not folder:
             return
-        found = sorted(p for p in Path(folder).iterdir() if p.is_file() and p.suffix.lower() == ".ris")
+        found = sorted(
+            p for p in Path(folder).iterdir() if p.is_file() and p.suffix.lower() == ".ris"
+        )
         if not found:
             QMessageBox.information(
                 self, "No RIS files found", f"No .ris files were found directly inside:\n{folder}"
@@ -150,11 +156,13 @@ class InputPanel(QGroupBox):
 
     # --- Drag and drop -------------------------------------------------------------
 
-    def dragEnterEvent(self, event: QDragEnterEvent) -> None:  # noqa: N802
+    def dragEnterEvent(self, event: QDragEnterEvent) -> None:
+        """Accept any drag containing file URLs; actual .ris filtering happens on drop."""
         if event.mimeData().hasUrls():
             event.acceptProposedAction()
 
-    def dropEvent(self, event: QDropEvent) -> None:  # noqa: N802
+    def dropEvent(self, event: QDropEvent) -> None:
+        """Route dropped files through add_dropped_paths() for consistent .ris filtering."""
         paths = [Path(url.toLocalFile()) for url in event.mimeData().urls() if url.isLocalFile()]
         if paths:
             self.add_dropped_paths(paths)

{risforge-0.3.2 → risforge-0.3.3}/src/risforge_gui/widgets/log_panel.py

@@ -27,6 +27,14 @@ class LogPanel(QPlainTextEdit):
         self.setAccessibleName("Activity log")
 
     def append_log(self, level: str, message: str) -> None:
+        """Append one timestamped, level-colored line.
+
+        Renders as HTML (not plain text) so WARNING/ERROR lines can be
+        colored -- ``message`` is escaped first since it may contain
+        arbitrary file paths or error text from risforge itself.
+        ``setMaximumBlockCount`` above caps memory use on a very long
+        or noisy run by silently dropping the oldest lines.
+        """
         timestamp = datetime.now().strftime("%H:%M:%S")
         safe_message = html.escape(message)
         color = _LEVEL_COLORS.get(level.upper())

{risforge-0.3.2 → risforge-0.3.3}/src/risforge_gui/widgets/output_panel.py

@@ -35,7 +35,7 @@ def default_output_dir() -> Path:
 
 
 class OutputConfigPanel(QGroupBox):
-    """"Output" group box: destination directory, final filename, optional intermediates."""
+    """ "Output" group box: destination directory, final filename, optional intermediates."""
 
     changed = Signal()
 

{risforge-0.3.2 → risforge-0.3.3}/src/risforge_gui/widgets/progress_panel.py

@@ -81,11 +81,19 @@ class ProgressPanel(QWidget):
 
     def _toggle_log(self, checked: bool) -> None:
         self.log_panel.setVisible(checked)
-        self.log_toggle.setText("Hide activity log \u25b4" if checked else "Show activity log \u25be")
+        self.log_toggle.setText(
+            "Hide activity log \u25b4" if checked else "Show activity log \u25be"
+        )
 
     # --- Public update API, called from MainWindow's signal-connected slots ---
 
     def reset(self, stages_in_use: list[str]) -> None:
+        """Prepare the panel for a new run.
+
+        Only the stages actually applicable to this run's mode are
+        made visible (e.g. no "Merge" bar for a single-file pipeline)
+        so the layout doesn't imply a step that isn't going to happen.
+        """
         for stage_key, bar in self._bars.items():
             in_use = stage_key in stages_in_use
             bar.setVisible(in_use)
@@ -98,6 +106,7 @@ class ProgressPanel(QWidget):
         self.current_activity_label.setText("")
 
     def set_stage_status(self, stage: str, status: str) -> None:
+        """Reflect a merge/clean/enrich stage's started/completed transition."""
         bar = self._bars.get(stage)
         if bar is None:
             return
@@ -115,6 +124,7 @@ class ProgressPanel(QWidget):
             self.current_activity_label.setText(f"{title} complete.")
 
     def set_enrichment_progress(self, processed: int, total: int) -> None:
+        """Show real, determinate progress -- unlike merge/clean, enrichment reports per-record."""
         bar = self._bars.get("enrich")
         if bar is None or total <= 0:
             return
@@ -124,6 +134,13 @@ class ProgressPanel(QWidget):
         self.current_activity_label.setText(f"Enriching record {processed:,} of {total:,}...")
 
     def update_stats(self, stats: dict) -> None:
+        """Update whichever stat labels this run's stats dict has values for.
+
+        Silently ignores keys the panel doesn't display and ``None``
+        values (used for stats that don't apply to the current mode,
+        e.g. "merged records" for a single-file run) rather than
+        overwriting the placeholder dash with "None".
+        """
         for key, value in stats.items():
             label = self._stat_value_labels.get(key)
             if label is None or value is None:

{risforge-0.3.2 → risforge-0.3.3}/src/risforge_gui/widgets/results_panel.py

@@ -94,6 +94,12 @@ class ResultsPanel(QWidget):
         final_ris_path: Path | None,
         fail_report_path: Path | None,
     ) -> None:
+        """Populate the summary and wire up the action buttons to real, existing files.
+
+        A path is only offered to "Open ..." if it actually exists on
+        disk -- e.g. no failure-report button when nothing failed, so
+        the buttons can't lead to a broken/missing-file open attempt.
+        """
         for key, label in self._value_labels.items():
             value = summary.get(key)
             label.setText(f"{value:,}" if isinstance(value, int) else "\u2014")
@@ -107,7 +113,9 @@ class ResultsPanel(QWidget):
             self._summary_form.setRowVisible(row, bool(skipped))
 
         self._output_dir = output_dir
-        self._final_ris_path = final_ris_path if final_ris_path and final_ris_path.exists() else None
+        self._final_ris_path = (
+            final_ris_path if final_ris_path and final_ris_path.exists() else None
+        )
         self._fail_report_path = (
             fail_report_path if fail_report_path and fail_report_path.exists() else None
         )

{risforge-0.3.2 → risforge-0.3.3}/src/risforge_gui/worker.py

@@ -23,7 +23,6 @@ import logging
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
-from typing import Any
 
 from PySide6.QtCore import QThread, Signal
 
@@ -69,9 +68,18 @@ class _LogBridge(logging.Handler):
         self._log_signal = log_signal
 
     def emit(self, record: logging.LogRecord) -> None:
-        level = "ERROR" if record.levelno >= logging.ERROR else (
-            "WARNING" if record.levelno >= logging.WARNING else "INFO"
-        )
+        """Map a stdlib log level to the three-tier severity the GUI displays.
+
+        The log panel only distinguishes INFO/WARNING/ERROR (matching
+        the UI's three status colors); DEBUG-and-below is never
+        forwarded at all (the handler is installed at level INFO).
+        """
+        if record.levelno >= logging.ERROR:
+            level = "ERROR"
+        elif record.levelno >= logging.WARNING:
+            level = "WARNING"
+        else:
+            level = "INFO"
         self._log_signal.emit(level, record.getMessage())
 
 
@@ -89,7 +97,14 @@ class PipelineWorker(QThread):
         super().__init__(parent)
         self._config = config
 
-    def run(self) -> None:  # noqa: D102 -- QThread interface
+    def run(self) -> None:
+        """Execute the configured operation and always emit a terminal signal.
+
+        Every exception type risforge's own API documents raising is
+        translated into a human-readable error_occurred signal instead
+        of propagating out of the thread (which would terminate it
+        silently, with nothing visible to the user at all).
+        """
         log_bridge = _LogBridge(self.log_message)
         risforge_logger = logging.getLogger("risforge")
         risforge_logger.addHandler(log_bridge)

{risforge-0.3.2 → risforge-0.3.3}/tests/test_cli.py

@@ -60,9 +60,7 @@ class TestBuildParser:
 
     def test_enrich_requires_email(self) -> None:
         parser = build_parser()
-        args = parser.parse_args(
-            ["enrich", "in.ris", "out.ris", "--email", "you@example.com"]
-        )
+        args = parser.parse_args(["enrich", "in.ris", "out.ris", "--email", "you@example.com"])
         assert args.email == "you@example.com"
 
     def test_pipeline_defaults_are_none(self) -> None:
@@ -96,9 +94,7 @@ class TestBuildParser:
 
     def test_merge_subcommand_parses_inputs_and_trailing_output(self) -> None:
         parser = build_parser()
-        args = parser.parse_args(
-            ["merge", "scopus.ris", "pubmed.ris", "wos.ris", "merged.ris"]
-        )
+        args = parser.parse_args(["merge", "scopus.ris", "pubmed.ris", "wos.ris", "merged.ris"])
         assert args.command == "merge"
         assert args.inputs == ["scopus.ris", "pubmed.ris", "wos.ris"]
         assert args.output == "merged.ris"
@@ -167,9 +163,7 @@ class TestMergeCommandExecution:
 
 
 class TestPipelineCommandExecution:
-    def test_single_input_pipeline_runs(
-        self, sample_ris_path, mock_enrichment, tmp_path
-    ) -> None:
+    def test_single_input_pipeline_runs(self, sample_ris_path, mock_enrichment, tmp_path) -> None:
         parser = build_parser()
         dedup_path = tmp_path / "clean.ris"
         enriched_path = tmp_path / "enriched.ris"

{risforge-0.3.2 → risforge-0.3.3}/tests/test_enrichment.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import json
 from typing import Any
 
 import rispy
@@ -56,9 +55,7 @@ OPENALEX_PAYLOAD = {
     "open_access": {"oa_url": "https://example.org/paper.pdf"},
 }
 SEMANTIC_SCHOLAR_PAYLOAD = {"abstract": "An abstract from Semantic Scholar."}
-UNPAYWALL_PAYLOAD = {
-    "best_oa_location": {"url_for_pdf": "https://example.org/oa-version.pdf"}
-}
+UNPAYWALL_PAYLOAD = {"best_oa_location": {"url_for_pdf": "https://example.org/oa-version.pdf"}}
 
 
 def _make_enricher() -> tuple[RisEnricher, _MockSession]:

{risforge-0.3.2 → risforge-0.3.3}/tests/test_merging.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-from pathlib import Path
-
 import pytest
 import rispy
 
@@ -173,9 +171,7 @@ class TestDeterministicOrdering:
         merge_ris_files(multi_source_paths, forward_path)
         merge_ris_files(list(reversed(multi_source_paths)), reversed_path)
 
-        forward_titles = [
-            r.get("title") for r in rispy.load(open(forward_path, encoding="utf-8"))
-        ]
+        forward_titles = [r.get("title") for r in rispy.load(open(forward_path, encoding="utf-8"))]
         reversed_titles = [
             r.get("title") for r in rispy.load(open(reversed_path, encoding="utf-8"))
         ]

{risforge-0.3.2 → risforge-0.3.3}/tests/test_pipeline.py

@@ -99,9 +99,7 @@ class TestMultiInputPipeline:
         )
 
         cleaned_records = list(rispy.load(open(dedup_path, encoding="utf-8")))
-        shared_paper = next(
-            r for r in cleaned_records if "Tractography" in (r.get("title") or "")
-        )
+        shared_paper = next(r for r in cleaned_records if "Tractography" in (r.get("title") or ""))
         # abstract came from pubmed.ris, keywords came from wos.ris --
         # merge_cluster() is what combines them into the one surviving record.
         assert shared_paper["abstract"] == (
@@ -129,9 +127,7 @@ class TestMultiInputPipeline:
         )
 
         enriched_records = list(rispy.load(open(enriched_path, encoding="utf-8")))
-        shared_paper = next(
-            r for r in enriched_records if "Tractography" in (r.get("title") or "")
-        )
+        shared_paper = next(r for r in enriched_records if "Tractography" in (r.get("title") or ""))
         # Kept from the original cleaned record, not overwritten by the
         # mocked Crossref payload's different title/journal:
         assert shared_paper["title"] == "Deep Learning for Diffusion MRI Tractography"

risforge-0.3.2/src/risforge_gui/app.py

@@ -1,34 +0,0 @@
-"""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()