bibcite-cli 0.4.1__tar.gz → 0.5.0__tar.gz

{bibcite_cli-0.4.1 → bibcite_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bibcite-cli
-Version: 0.4.1
+Version: 0.5.0
 Summary: Resolve papers (arXiv id / DOI / title) to canonical, normalized BibTeX for agents and humans
 Project-URL: Repository, https://github.com/leo1oel/bibcite
 License-Expression: MIT

{bibcite_cli-0.4.1 → bibcite_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bibcite-cli"
-version = "0.4.1"
+version = "0.5.0"
 description = "Resolve papers (arXiv id / DOI / title) to canonical, normalized BibTeX for agents and humans"
 readme = "Readme.md"
 license = "MIT"

{bibcite_cli-0.4.1 → bibcite_cli-0.5.0}/src/bibcite/__init__.py

@@ -1,3 +1,3 @@
 """bibcite: canonical BibTeX resolution for papers (arXiv id / DOI / title)."""
 
-__version__ = "0.4.1"
+__version__ = "0.5.0"

{bibcite_cli-0.4.1 → bibcite_cli-0.5.0}/src/bibcite/cli.py

@@ -80,18 +80,18 @@ def cmd_get(args) -> int:
     res, code = _resolve_or_none(query, args.require_published)
     if res is None:
         return code
-    _emit(
-        {
-            "action": "resolved",
-            "key": res.entry["ID"],
-            "title": res.entry.get("title", ""),
-            "venue": res.venue or "arXiv (preprint, no published venue found)",
-            "published": res.published,
-            "source": res.source,
-            "bibtex": res.bibtex,
-        },
-        args.json,
-    )
+    payload = {
+        "action": "resolved",
+        "key": res.entry["ID"],
+        "title": res.entry.get("title", ""),
+        "venue": res.venue or "arXiv (preprint, no published venue found)",
+        "published": res.published,
+        "source": res.source,
+        "bibtex": res.bibtex,
+    }
+    if not res.published:
+        payload["published_check"] = res.check
+    _emit(payload, args.json)
     return 0
 
 
@@ -256,6 +256,10 @@ def cmd_add(args) -> int:
             "published": res.published,
             "source": res.source,
         }
+        if not res.published:
+            # "incomplete" = the check ran while core sources were down; the
+            # paper may well be published — retry later.
+            result["published_check"] = res.check
         if warning:
             result["warning"] = warning
         results.append(result)
@@ -312,10 +316,13 @@ def _upgrade_entries(path: Path, dry_run: bool) -> dict:
         )
         match, status = find_published(title, entry.get("year", ""), aid, hint)
         if not match:
-            # "no_published_version" is a trustworthy miss; "sources_unavailable"
-            # means the sources were down — do not conclude anything.
+            # "no_published_version" is trustworthy ONLY when every core
+            # source answered; a batch that tripped DBLP's rate limit gets
+            # "sources_unavailable" so nobody believes a poisoned verdict.
             reason = (
-                "sources_unavailable" if status == "unavailable" else "no_published_version"
+                "no_published_version"
+                if status == "not_found"
+                else "sources_unavailable"
             )
             report.append(
                 {"key": entry["ID"], "title": title, "matched": False, "reason": reason}

{bibcite_cli-0.4.1 → bibcite_cli-0.5.0}/src/bibcite/resolve.py

@@ -72,6 +72,12 @@ class Resolved:
     source: str  # where the publication info came from
     venue: str  # final venue string ("" if preprint)
     published: bool
+    # For preprint fallbacks: was the publication check trustworthy?
+    # "complete"   — every core source answered; the paper really has no
+    #                published version (as of now)
+    # "incomplete" — core sources were rate-limited/down; retry later before
+    #                believing the preprint status
+    check: str = "complete"
 
     @property
     def bibtex(self) -> str:
@@ -220,9 +226,16 @@ def resolve(query: str, require_published: bool = False) -> Resolved:
                     f"Could not check publication status for arXiv:{value} (sources down)"
                 )
             raise NotFound(f"No published version found for arXiv:{value}")
-        _log("[bibcite] no published version found; using arXiv preprint entry")
+        check = "complete" if status == "not_found" else "incomplete"
+        if check == "incomplete":
+            _log(
+                "[bibcite] preprint fallback with INCOMPLETE publication check "
+                "(core sources were unavailable) — retry later"
+            )
+        else:
+            _log("[bibcite] no published version found; using arXiv preprint entry")
         entry = _arxiv_only_entry(meta)
-        return Resolved(_finalize(entry, meta), "arxiv", "", False)
+        return Resolved(_finalize(entry, meta), "arxiv", "", False, check)
 
     if kind == "doi":
         match = crossref_by_doi(value)
@@ -256,9 +269,16 @@ def resolve(query: str, require_published: bool = False) -> Resolved:
     if meta and meta.arxiv_id:
         if require_published:
             raise NotFound(f"Only an arXiv preprint was found for: {value}")
-        _log("[bibcite] no published version found; using arXiv preprint entry")
+        check = "complete" if status == "not_found" else "incomplete"
+        if check == "incomplete":
+            _log(
+                "[bibcite] preprint fallback with INCOMPLETE publication check "
+                "(core sources were unavailable) — retry later"
+            )
+        else:
+            _log("[bibcite] no published version found; using arXiv preprint entry")
         entry = _arxiv_only_entry(meta)
-        return Resolved(_finalize(entry, meta), "arxiv", "", False)
+        return Resolved(_finalize(entry, meta), "arxiv", "", False, check)
     if status == "unavailable":
         raise SourcesUnavailable(
             f"All sources were rate-limited or down while resolving: {value}"

{bibcite_cli-0.4.1 → bibcite_cli-0.5.0}/src/bibcite/sources.py

@@ -147,6 +147,42 @@ def arxiv_metadata(arxiv_id: str) -> ArxivMeta:
 # DBLP
 # ---------------------------------------------------------------------------
 
+# DBLP throttles at roughly 1-2 req/s and escalates to temporary IP bans when
+# hammered. Client-side pacing prevents the 429 in the first place; on a 429
+# we back off and retry (honoring Retry-After) instead of instantly poisoning
+# the rest of a batch run — only repeated failure disables the source.
+_DBLP_MIN_INTERVAL = 0.8
+_dblp_last_request = 0.0
+
+
+def _dblp_get(c: httpx.Client, url: str, params: dict | None = None) -> httpx.Response:
+    global _dblp_last_request
+    for attempt in range(3):
+        wait = _DBLP_MIN_INTERVAL - (time.monotonic() - _dblp_last_request)
+        if wait > 0:
+            time.sleep(wait)
+        _dblp_last_request = time.monotonic()
+        try:
+            r = c.get(url, params=params)
+        except httpx.HTTPError as e:  # TCP reset = temporary ban; retrying fast makes it worse
+            if attempt < 2:
+                time.sleep(5 * (attempt + 1))
+                continue
+            raise SourceUnavailable(f"DBLP unreachable ({type(e).__name__})")
+        if r.status_code == 429:
+            retry_after = int(r.headers.get("Retry-After") or 0)
+            if retry_after > 30:
+                raise SourceUnavailable(f"DBLP rate-limited (Retry-After {retry_after}s)")
+            if attempt < 2:
+                delay = max(retry_after, 4 * (attempt + 1))
+                _log(f"[dblp] 429 — backing off {delay}s")
+                time.sleep(delay)
+                continue
+            raise SourceUnavailable("DBLP rate-limited (429) after backoff retries")
+        return r
+    raise SourceUnavailable("DBLP unavailable")
+
+
 def try_dblp(title: str, author_hint: str = "") -> Match | None:
     """DBLP search. Generic titles ("X is all you need") drown in DBLP's
     ranking, so when we know the first author we query with their last name
@@ -157,12 +193,11 @@ def try_dblp(title: str, author_hint: str = "") -> Match | None:
     queries.append(title)
     with _client() as c:
         for q in queries:
-            r = c.get(
+            r = _dblp_get(
+                c,
                 "https://dblp.org/search/publ/api",
                 params={"q": q, "format": "json", "h": 100},
             )
-            if r.status_code == 429:
-                raise SourceUnavailable("DBLP rate-limited (429)")
             r.raise_for_status()
             hits = (
                 r.json().get("result", {}).get("hits", {}).get("hit", []) or []
@@ -182,9 +217,12 @@ def try_dblp(title: str, author_hint: str = "") -> Match | None:
                     venue = venue[0]
                 bibtex = ""
                 if info.get("url"):
-                    br = c.get(info["url"] + ".bib")
-                    if br.status_code == 200:
-                        bibtex = br.text
+                    try:
+                        br = _dblp_get(c, info["url"] + ".bib")
+                        if br.status_code == 200:
+                            bibtex = br.text
+                    except SourceUnavailable:
+                        pass  # keep the match; construct from fields
                 _log(f"[dblp] match: {venue} {info.get('year', '')}")
                 return Match(
                     source="dblp",
@@ -219,12 +257,11 @@ def try_dblp_fuzzy(title: str, author_hint: str, year: str = "") -> Match | None
         return None
     q = " ".join([author_hint] + tokens)
     with _client() as c:
-        r = c.get(
+        r = _dblp_get(
+            c,
             "https://dblp.org/search/publ/api",
             params={"q": q, "format": "json", "h": 100},
         )
-        if r.status_code == 429:
-            raise SourceUnavailable("DBLP rate-limited (429)")
         r.raise_for_status()
         hits = r.json().get("result", {}).get("hits", {}).get("hit", []) or []
         hits.sort(key=lambda h: int(h.get("info", {}).get("year", 9999)))
@@ -246,9 +283,12 @@ def try_dblp_fuzzy(title: str, author_hint: str, year: str = "") -> Match | None
                 venue = venue[0]
             bibtex = ""
             if info.get("url"):
-                br = c.get(info["url"] + ".bib")
-                if br.status_code == 200:
-                    bibtex = br.text
+                try:
+                    br = _dblp_get(c, info["url"] + ".bib")
+                    if br.status_code == 200:
+                        bibtex = br.text
+                except SourceUnavailable:
+                    pass  # keep the match; construct from fields
             _log(
                 f"[dblp-fuzzy] match with title drift: '{hit_title}' "
                 f"@ {venue} {info.get('year', '')}"
@@ -659,16 +699,24 @@ CASCADE = (
 # (PaperMemory's DISABLE_MATCH, ported).
 _DISABLED: dict[str, str] = {}
 
+# Only these sources are authoritative enough that losing one taints a miss
+# into "incomplete". Google Scholar captchas and Unpaywall flakiness are
+# routine and must not stop "not_found" from ever being trustworthy.
+CORE_SOURCES = frozenset({"dblp", "semanticscholar", "crossref", "openalex"})
+
 
 def find_published(
     title: str, year: str = "", arxiv_id: str = "", author_hint: str = ""
 ) -> tuple[Match | None, str]:
     """Try each source in order; first verified hit wins.
 
-    Returns (match, status). status distinguishes a trustworthy miss from an
-    outage: "found" | "not_found" (>=1 source answered cleanly with no hit) |
-    "unavailable" (every source was disabled or errored — do NOT conclude the
-    paper is unpublished).
+    Returns (match, status):
+      "found"       — verified publication match
+      "not_found"   — EVERY source answered cleanly with no hit; trustworthy
+      "incomplete"  — some sources answered (no hit) but others were
+                      disabled/erroring; a batch run that tripped DBLP's rate
+                      limit lands here — do NOT conclude "unpublished"
+      "unavailable" — no source answered at all
     """
     from . import cache
 
@@ -679,6 +727,8 @@ def find_published(
         return Match(**cached), "found"
 
     clean_misses = 0
+    # Core sources lost earlier in this run taint this query's verdict too.
+    incomplete = any(n in CORE_SOURCES for n in _DISABLED)
     for name, fn in CASCADE:
         if name in _DISABLED:
             continue
@@ -691,8 +741,10 @@ def find_published(
             _log(f"[{name}] no publication found")
         except SourceUnavailable as e:
             _DISABLED[name] = str(e)
+            incomplete = incomplete or name in CORE_SOURCES
             _log(f"[{name}] disabled for the rest of this run: {e}")
         except Exception as e:  # network hiccup on one source must not kill the run
+            incomplete = incomplete or name in CORE_SOURCES
             _log(f"[{name}] error: {type(e).__name__}: {e}")
 
     # Exact-title search missed everywhere. Before concluding "no published
@@ -707,6 +759,10 @@ def find_published(
             clean_misses += 1
         except SourceUnavailable as e:
             _DISABLED["dblp"] = str(e)
+            incomplete = True
         except Exception as e:
+            incomplete = True
             _log(f"[dblp-fuzzy] error: {type(e).__name__}: {e}")
-    return None, ("not_found" if clean_misses else "unavailable")
+    if not clean_misses:
+        return None, "unavailable"
+    return None, ("incomplete" if incomplete else "not_found")

bibcite_cli-0.5.0/tests/test_status_semantics.py

@@ -0,0 +1,78 @@
+"""The batch-429 poisoning scenario: a disabled core source must taint the
+verdict ('incomplete'), never masquerade as a trustworthy 'not_found'."""
+
+import pytest
+
+import bibcite.sources as sources
+from bibcite import cache
+from bibcite.sources import SourceUnavailable, find_published
+
+
+@pytest.fixture(autouse=True)
+def isolated(monkeypatch, tmp_path):
+    monkeypatch.setattr(cache, "DISABLED", True)
+    monkeypatch.setattr(sources, "_DISABLED", {})
+    # No fuzzy fallback network calls in these tests.
+    monkeypatch.setattr(sources, "try_dblp_fuzzy", lambda *a, **k: None)
+
+
+def _cascade(**outcomes):
+    """Build a fake CASCADE; outcome per source: None=clean miss, 'raise'=429."""
+
+    def make(o):
+        def fn(t, y, a, au):
+            if o == "raise":
+                raise SourceUnavailable("simulated 429")
+            return o
+
+        return fn
+
+    return tuple((name, make(o)) for name, o in outcomes.items())
+
+
+def test_all_clean_misses_is_trustworthy(monkeypatch):
+    monkeypatch.setattr(
+        sources, "CASCADE", _cascade(dblp=None, semanticscholar=None, crossref=None)
+    )
+    match, status = find_published("Some Title", author_hint="smith")
+    assert (match, status) == (None, "not_found")
+
+
+def test_core_source_429_taints_verdict(monkeypatch):
+    # DBLP 429s, others answer cleanly — the user's exact failure chain.
+    monkeypatch.setattr(
+        sources,
+        "CASCADE",
+        _cascade(dblp="raise", googlescholar=None, crossref=None),
+    )
+    match, status = find_published("Some Title", author_hint="smith")
+    assert (match, status) == (None, "incomplete")
+
+
+def test_previously_disabled_core_source_taints_next_queries(monkeypatch):
+    # Query N tripped DBLP; queries N+1... in the same run inherit the taint.
+    monkeypatch.setattr(sources, "_DISABLED", {"dblp": "429"})
+    monkeypatch.setattr(
+        sources, "CASCADE", _cascade(dblp=None, crossref=None)  # dblp skipped anyway
+    )
+    match, status = find_published("Another Title", author_hint="smith")
+    assert (match, status) == (None, "incomplete")
+
+
+def test_noncore_outage_does_not_taint(monkeypatch):
+    # Google Scholar captcha is routine; a miss stays trustworthy.
+    monkeypatch.setattr(
+        sources,
+        "CASCADE",
+        _cascade(dblp=None, googlescholar="raise", crossref=None),
+    )
+    match, status = find_published("Some Title", author_hint="smith")
+    assert (match, status) == (None, "not_found")
+
+
+def test_everything_down_is_unavailable(monkeypatch):
+    monkeypatch.setattr(
+        sources, "CASCADE", _cascade(dblp="raise", semanticscholar="raise")
+    )
+    match, status = find_published("Some Title", author_hint="smith")
+    assert (match, status) == (None, "unavailable")

{bibcite_cli-0.4.1 → bibcite_cli-0.5.0}/uv.lock

@@ -18,7 +18,7 @@ wheels = [
 
 [[package]]
 name = "bibcite-cli"
-version = "0.4.1"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "bibtexparser" },