risforge 0.3.0__tar.gz → 0.3.2__tar.gz

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: risforge
-Version: 0.3.0
+Version: 0.3.2
 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/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
+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
 Keywords: ris,bibliography,systematic-review,deduplication,crossref,openalex,citation-management,prisma
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "risforge"
-version = "0.3.0"
+version = "0.3.2"
 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/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"
+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"
 
 [project.scripts]
 risforge = "risforge.cli:main"

{risforge-0.3.0 → risforge-0.3.2}/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.3.0"
+__version__ = "0.3.2"
 
 __all__ = [
     "clean_ris_file",

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

@@ -24,6 +24,8 @@ from typing import Any
 import rispy
 import rispy.writer
 
+from risforge.exceptions import RisParsingError
+
 logger = logging.getLogger(__name__)
 
 RisRecord = dict[str, Any]
@@ -223,13 +225,32 @@ def parse_ris_records(
 
     Raises:
         FileNotFoundError: If ``input_path`` does not exist.
+        RisParsingError: If the file's bytes can't be decoded as text
+            (for example, a non-UTF-8 file saved by an older Windows
+            reference manager). This does not cover malformed
+            *individual records* -- those are tolerated and reported
+            in ``errors`` instead.
     """
     input_path = Path(input_path)
 
     if not input_path.exists():
         raise FileNotFoundError(f"Input file '{input_path}' not found.")
 
-    text = input_path.read_text(encoding="utf-8")
+    try:
+        # utf-8-sig: identical to plain utf-8 for files with no BOM,
+        # but also transparently strips a leading UTF-8 byte-order
+        # mark if one is present. Windows text editors and some
+        # reference managers commonly save UTF-8 files with a BOM;
+        # left in place, it silently prevents the very first "TY" tag
+        # in the file from being recognized at all (no crash, just an
+        # empty result), which is worse than being explicit about it.
+        text = input_path.read_text(encoding="utf-8-sig")
+    except UnicodeDecodeError as error:
+        raise RisParsingError(
+            f"Could not read '{input_path}' as UTF-8 text. The file may be "
+            "saved in a different encoding (common with exports from older "
+            "reference managers) -- try re-saving it as UTF-8."
+        ) from error
 
     blocks = re.split(r"(?m)^TY\s+-", text)
     records: list[RisRecord] = []

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

@@ -32,6 +32,24 @@ file, and ``extract_doi()`` could never find a DOI that was already
 present on the record either, since it looked for ``"DO"`` instead of
 ``"doi"``. :data:`RISPY_FIELD_MAP` below uses rispy's real field
 names, and :meth:`RisEnricher.extract_doi` reads ``"doi"``/``"urls"``.
+
+A second bug was found and fixed the same way: :meth:`RisEnricher.enrich_file`
+used to call ``rispy.load()`` directly on the whole input file in one
+pass. ``rispy`` (as of 0.10.0) has its own bug where it tracks the
+"last tag seen" as parser-wide state that is never reset between
+records -- so a single stray blank or otherwise non-tag-pattern line
+positioned early in one record, right after a record boundary, can
+make it try to extend a field from the *previous* record onto the new
+record's (fresh, and therefore missing that key) dict, raising a
+``KeyError`` for whatever field that happened to be and aborting the
+entire file's enrichment. ``risforge.cleaning.parse_ris_records()``
+already sidesteps this by parsing each record block independently (a
+fresh parser instance per block, so there's no cross-record state to
+leak) -- ``enrich_file()`` now reuses that same function instead of
+calling ``rispy.load()`` itself, which both fixes the crash and means
+a malformed record is tolerated and reported exactly the way
+:func:`risforge.cleaning.clean_ris_file` already tolerates and reports
+one, rather than each module handling malformed input differently.
 """
 
 from __future__ import annotations
@@ -52,6 +70,8 @@ import rispy
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
+from risforge.cleaning import parse_ris_records
+
 TITLE_MATCH_THRESHOLD = 0.90
 CACHE_EXPIRE_DAYS = 7
 
@@ -125,6 +145,7 @@ class RisEnricher:
             "processed": 0,
             "enriched": 0,
             "failed": 0,
+            "skipped_malformed": 0,
             "api_calls": {
                 "crossref": 0,
                 "openalex": 0,
@@ -407,12 +428,20 @@ class RisEnricher:
 
         logger.info("Loading %s...", input_path)
         try:
-            with input_path.open("r", encoding="utf-8") as file:
-                records = list(rispy.load(file))
+            records, parse_errors = parse_ris_records(input_path)
         except (OSError, TypeError, ValueError) as error:
             logger.error("Failed to parse RIS file: %s", error)
             return self.stats
 
+        if parse_errors:
+            logger.warning(
+                "Encountered %d malformed record block(s) in %s, skipped: %s",
+                len(parse_errors),
+                input_path,
+                "; ".join(f"block {n}: {msg}" for n, msg in parse_errors),
+            )
+        self.stats["skipped_malformed"] = len(parse_errors)
+
         total = len(records)
         enriched_records = []
         for index, record in enumerate(records):

risforge-0.3.2/src/risforge/exceptions.py

@@ -0,0 +1,38 @@
+"""Exception types for risforge.
+
+We deliberately keep this hierarchy small. Most failure modes in this
+package are already well described by the standard library's own
+exceptions (``FileNotFoundError``, ``ValueError``, etc.), and the
+original scripts caught those precisely rather than reaching for
+generic ``Exception``. We keep that pattern. ``RisForgeError`` exists
+only as a common base for the handful of errors that are specific to
+this package's domain logic, so library users can catch
+``RisForgeError`` if they want a single net for "something in risforge
+itself went wrong" without having to also catch unrelated stdlib
+errors they may want to handle differently.
+"""
+
+from __future__ import annotations
+
+
+class RisForgeError(Exception):
+    """Base class for errors raised directly by risforge's own logic."""
+
+
+class RisParsingError(RisForgeError, ValueError):
+    """Raised when a RIS file's content can't be decoded/read at all.
+
+    Deliberately inherits from ``ValueError`` too (like
+    ``json.JSONDecodeError`` does in the standard library) so every
+    existing ``except (OSError, ValueError, RuntimeError)`` clause
+    throughout this codebase (CLI, pipeline, GUI worker) already
+    catches it correctly, with no call site changes required. Catch
+    ``RisParsingError`` specifically, or ``RisForgeError`` generally,
+    for finer-grained handling.
+
+    This is for whole-file failures only (e.g. the file's bytes can't
+    be decoded as text) -- a malformed *individual record* within an
+    otherwise-readable file is not an error at this level; see
+    :func:`risforge.cleaning.parse_ris_records`, which tolerates and
+    reports those per-block instead of raising.
+    """

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: risforge
-Version: 0.3.0
+Version: 0.3.2
 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/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
+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
 Keywords: ris,bibliography,systematic-review,deduplication,crossref,openalex,citation-management,prisma
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research

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

@@ -353,6 +353,7 @@ class MainWindow(QMainWindow):
                 "input_records": stats.get("processed", 0),  # type: ignore[union-attr]
                 "enriched_records": stats.get("enriched", 0),  # type: ignore[union-attr]
                 "failed_enrichment": stats.get("failed", 0),  # type: ignore[union-attr]
+                "skipped_malformed": stats.get("skipped_malformed", 0),  # type: ignore[union-attr]
             }
             return summary, config.enriched_output_path, config.fail_report_path
 
@@ -363,6 +364,7 @@ class MainWindow(QMainWindow):
             "unique_records": result.cleaned_record_count,  # type: ignore[attr-defined]
             "enriched_records": result.enrichment_stats.get("enriched", 0),  # type: ignore[attr-defined]
             "failed_enrichment": result.enrichment_stats.get("failed", 0),  # type: ignore[attr-defined]
+            "skipped_malformed": result.enrichment_stats.get("skipped_malformed", 0),  # type: ignore[attr-defined]
         }
         return summary, config.enriched_output_path, config.fail_report_path
 

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

@@ -23,6 +23,7 @@ _SUMMARY_LABELS = {
     "unique_records": "Unique records",
     "enriched_records": "Enriched records",
     "failed_enrichment": "Unresolved records",
+    "skipped_malformed": "Skipped (unreadable records)",
 }
 
 
@@ -47,9 +48,11 @@ class ResultsPanel(QWidget):
         summary_box = QGroupBox("Summary")
         self._summary_form = QFormLayout(summary_box)
         self._value_labels: dict[str, QLabel] = {}
-        for key, label_text in _SUMMARY_LABELS.items():
+        self._summary_rows: dict[str, int] = {}
+        for row, (key, label_text) in enumerate(_SUMMARY_LABELS.items()):
             value_label = QLabel("\u2014")
             self._value_labels[key] = value_label
+            self._summary_rows[key] = row
             self._summary_form.addRow(QLabel(label_text), value_label)
         layout.addWidget(summary_box)
 
@@ -95,6 +98,14 @@ class ResultsPanel(QWidget):
             value = summary.get(key)
             label.setText(f"{value:,}" if isinstance(value, int) else "\u2014")
 
+        # Keep the summary uncluttered for the common case: only show
+        # "Skipped (unreadable records)" when there's actually
+        # something to report, rather than a permanent "0" row.
+        skipped = summary.get("skipped_malformed")
+        row = self._summary_rows.get("skipped_malformed")
+        if row is not None:
+            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._fail_report_path = (

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

@@ -178,7 +178,11 @@ class PipelineWorker(QThread):
         )
         self.stage_changed.emit("enrich", "completed")
         self.stats_changed.emit(
-            {"enriched_records": stats.get("enriched", 0), "failed_enrichment": stats.get("failed", 0)}
+            {
+                "enriched_records": stats.get("enriched", 0),
+                "failed_enrichment": stats.get("failed", 0),
+                "skipped_malformed": stats.get("skipped_malformed", 0),
+            }
         )
         self.finished_ok.emit(stats)
 
@@ -202,6 +206,7 @@ class PipelineWorker(QThread):
                 "unique_records": result.cleaned_record_count,
                 "enriched_records": result.enrichment_stats.get("enriched", 0),
                 "failed_enrichment": result.enrichment_stats.get("failed", 0),
+                "skipped_malformed": result.enrichment_stats.get("skipped_malformed", 0),
             }
         )
         self.finished_ok.emit(result)

{risforge-0.3.0 → risforge-0.3.2}/tests/test_cleaning.py

@@ -9,7 +9,9 @@ from risforge.cleaning import (
     merge_cluster,
     normalize_doi,
     normalize_title,
+    parse_ris_records,
 )
+from risforge.exceptions import RisParsingError
 
 
 class TestNormalizeTitle:
@@ -104,3 +106,77 @@ class TestCleanRisFile:
     def test_missing_input_raises(self, tmp_path) -> None:
         with pytest.raises(FileNotFoundError):
             clean_ris_file(tmp_path / "does_not_exist.ris", tmp_path / "out.ris")
+
+
+class TestParseRisRecordsEncoding:
+    """Regression tests for encoding-related parsing robustness.
+
+    These are not Windows-specific fixes (see the equivalent tests in
+    test_enrichment.py for the actual crash this was found alongside),
+    but a UTF-8 BOM in particular is disproportionately common in
+    files saved by Windows text editors and some reference managers,
+    so it's worth covering explicitly here too.
+    """
+
+    def test_utf8_bom_is_stripped_transparently(self, tmp_path) -> None:
+        ris_text = "TY  - JOUR\nAU  - Smith, John\nTI  - BOM paper\nER  - \n"
+        path = tmp_path / "bom.ris"
+        path.write_bytes(b"\xef\xbb\xbf" + ris_text.encode("utf-8"))
+
+        records, errors = parse_ris_records(path)
+
+        assert len(records) == 1
+        assert records[0]["title"] == "BOM paper"
+        assert errors == []
+
+    def test_non_utf8_bytes_raise_a_clear_parsing_error(self, tmp_path) -> None:
+        path = tmp_path / "bad_encoding.ris"
+        path.write_bytes(b"TY  - JOUR\nTI  - Bad \xff\xfe byte sequence\nER  - \n")
+
+        with pytest.raises(RisParsingError, match="bad_encoding.ris"):
+            parse_ris_records(path)
+
+    def test_parsing_error_is_also_a_value_error(self, tmp_path) -> None:
+        # RisParsingError intentionally also subclasses ValueError so
+        # every existing `except (..., ValueError, ...)` call site
+        # (CLI, pipeline, GUI worker) already catches it with no
+        # changes required at those call sites.
+        path = tmp_path / "bad_encoding.ris"
+        path.write_bytes(b"\xff\xfe\x00\x01")
+
+        with pytest.raises(ValueError):
+            parse_ris_records(path)
+
+
+class TestParseRisRecordsCrossRecordStateBug:
+    """Regression test for the rispy 0.10.0 cross-record state bug.
+
+    See risforge.enrichment's module docstring and
+    tests/test_enrichment.py::TestEnrichFileMalformedInput for the
+    full explanation. clean_ris_file() was never actually vulnerable
+    to this (each record block is parsed independently), but this
+    test pins that guarantee down explicitly so a future refactor
+    can't accidentally reintroduce the whole-file single-parse
+    pattern that enrich_file() used to use.
+    """
+
+    def test_stray_blank_line_after_record_boundary_does_not_crash(self, tmp_path) -> None:
+        ris_text = (
+            "TY  - JOUR\n"
+            "AU  - Smith, John\n"
+            "TI  - First paper\n"
+            "LA  - English\n"
+            "ER  - \n"
+            "\n"
+            "TY  - JOUR\n"
+            "\n"
+            "AU  - Doe, Jane\n"
+            "TI  - Second paper\n"
+            "ER  - \n"
+        )
+        path = tmp_path / "malformed.ris"
+        path.write_text(ris_text, encoding="utf-8")
+
+        records, errors = parse_ris_records(path)  # must not raise KeyError
+
+        assert len(records) == 2

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

@@ -152,3 +152,93 @@ class TestEnrichFile:
         assert output_path.exists()
         assert stats["processed"] == 1
         assert stats["enriched"] == 1
+
+
+class TestEnrichFileMalformedInput:
+    """Regression tests for a rispy 0.10.0 bug: RisParser tracks the
+
+    "last tag seen" as state that persists across record boundaries
+    within a single ``rispy.load()``/``rispy.loads()`` call. A stray
+    blank (or otherwise non-tag-pattern) line positioned early in one
+    record -- right after a record boundary -- could make it try to
+    extend a field from the *previous* record onto the new record's
+    dict, which doesn't have that key yet, raising KeyError and
+    aborting the whole file. Reproduces identically on every platform
+    (verified on Linux); it is not a Windows-specific issue, just a
+    RIS-content issue that happened to be triggered first by files
+    tested on Windows. enrich_file() now parses via
+    risforge.cleaning.parse_ris_records() (block-isolated, immune to
+    this) instead of calling rispy.load() directly on the whole file.
+    """
+
+    def test_stray_blank_line_after_record_boundary_does_not_crash(self, tmp_path) -> None:
+        # Record 1 ends with an "LA" (language) tag as its last real
+        # field before ER. Record 2 has a stray blank line immediately
+        # after "TY", before its own first tag -- this is exactly the
+        # combination that crashed rispy.load() with KeyError('language').
+        ris_text = (
+            "TY  - JOUR\n"
+            "AU  - Smith, John\n"
+            "TI  - First paper\n"
+            "LA  - English\n"
+            "DO  - 10.1000/first\n"
+            "ER  - \n"
+            "\n"
+            "TY  - JOUR\n"
+            "\n"
+            "AU  - Doe, Jane\n"
+            "TI  - Second paper\n"
+            "DO  - 10.1000/second\n"
+            "ER  - \n"
+        )
+        input_path = tmp_path / "malformed.ris"
+        input_path.write_text(ris_text, encoding="utf-8")
+
+        enricher, _session = _make_enricher()
+        # Must not raise KeyError.
+        stats = enricher.enrich_file(str(input_path), str(tmp_path / "out.ris"))
+
+        assert stats["processed"] == 2
+
+    def test_genuinely_unparseable_block_is_skipped_and_counted(self, tmp_path) -> None:
+        ris_text = (
+            "TY  - JOUR\n"
+            "AU  - Smith, John\n"
+            "TI  - Valid paper\n"
+            "DO  - 10.1000/valid\n"
+            "ER  - \n"
+            "\n"
+            "TY  - JOUR\n"
+            "AU  - Broken, Record\n"
+            "TI  - Missing ER terminator entirely\n"
+        )
+        input_path = tmp_path / "genuinely_malformed.ris"
+        input_path.write_text(ris_text, encoding="utf-8")
+
+        enricher, _session = _make_enricher()
+        stats = enricher.enrich_file(str(input_path), str(tmp_path / "out.ris"))
+
+        assert stats["processed"] == 1
+        assert stats["skipped_malformed"] == 1
+
+    def test_utf8_bom_is_handled_transparently(self, tmp_path) -> None:
+        ris_text = "TY  - JOUR\nAU  - Smith, John\nTI  - BOM paper\nDO  - 10.1000/bom\nER  - \n"
+        input_path = tmp_path / "bom.ris"
+        input_path.write_bytes(b"\xef\xbb\xbf" + ris_text.encode("utf-8"))
+
+        enricher, _session = _make_enricher()
+        stats = enricher.enrich_file(str(input_path), str(tmp_path / "out.ris"))
+
+        assert stats["processed"] == 1
+
+    def test_non_utf8_file_gives_a_clear_error_without_crashing(self, tmp_path) -> None:
+        input_path = tmp_path / "bad_encoding.ris"
+        input_path.write_bytes(b"TY  - JOUR\nTI  - Bad \xff\xfe byte sequence\nER  - \n")
+
+        enricher, _session = _make_enricher()
+        # enrich_file()'s existing contract: parsing failures are
+        # logged and it returns the (unmodified) stats rather than
+        # raising, exactly as it already did for a missing input file.
+        stats = enricher.enrich_file(str(input_path), str(tmp_path / "out.ris"))
+
+        assert stats["processed"] == 0

risforge-0.3.0/src/risforge/exceptions.py

@@ -1,23 +0,0 @@
-"""Exception types for risforge.
-
-We deliberately keep this hierarchy small. Most failure modes in this
-package are already well described by the standard library's own
-exceptions (``FileNotFoundError``, ``ValueError``, etc.), and the
-original scripts caught those precisely rather than reaching for
-generic ``Exception``. We keep that pattern. ``RisForgeError`` exists
-only as a common base for the handful of errors that are specific to
-this package's domain logic, so library users can catch
-``RisForgeError`` if they want a single net for "something in risforge
-itself went wrong" without having to also catch unrelated stdlib
-errors they may want to handle differently.
-"""
-
-from __future__ import annotations
-
-
-class RisForgeError(Exception):
-    """Base class for errors raised directly by risforge's own logic."""
-
-
-class RisParsingError(RisForgeError):
-    """Raised when a RIS file cannot be parsed into any usable records."""