bibcite-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{bibcite_cli-0.2.0 → bibcite_cli-0.4.0}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.4
 Name: bibcite-cli
-Version: 0.2.0
+Version: 0.4.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
 License-File: LICENSE
 Keywords: arxiv,bibliography,bibtex,citations,dblp
@@ -32,7 +33,7 @@ After every write, the file is formatted with [bibtex-tidy](https://github.com/F
 uv tool install --editable .
 
 # from git, no checkout needed
-uv tool install git+https://github.com/<you>/bibcite
+uv tool install git+https://github.com/leo1oel/bibcite
 
 # once published to PyPI (package name bibcite-cli, command name bibcite)
 uv tool install bibcite-cli   # or: uvx --from bibcite-cli bibcite ...
@@ -57,6 +58,13 @@ bibcite add refs.bib 2103.14030 --json
 # Add a raw BibTeX entry you already have (venue still canonicalized, file still tidied)
 bibcite add refs.bib --bibtex "$(pbpaste)"
 
+# Batch add (one query per line; shares rate-limit state, tidies once)
+bibcite add refs.bib --from ids.txt
+
+# Overwrite a bad existing entry (keeps its key), or delete one
+bibcite add refs.bib <query> --replace
+bibcite remove refs.bib <key>
+
 # One-shot cleanup: upgrade preprints → tidy → lint
 bibcite fix refs.bib
 
@@ -68,8 +76,11 @@ bibcite tidy refs.bib
 bibcite check refs.bib
 ```
 
-`--json` prints a machine-readable result on stdout (`action`, `key`, `venue`, `source`, ...); all diagnostics go to stderr.
+`add`/`upgrade`/`check`/`fix`/`remove` print a machine-readable JSON result on stdout (`action`, `key`, `venue`, `source`, ...); all diagnostics go to stderr.
 `add` is idempotent: an existing entry returns `action: exists` with its key, and an existing arXiv entry matched to a published version is upgraded in place, keeping its citation key.
+Exit codes: 0 success, 2 paper not found (ask for a better identifier), 3 sources/tool failure (retry later).
+Successful matches are cached at `~/.cache/bibcite/published.json` (published papers only — preprint status is never cached); bypass with `--no-cache` or `BIBCITE_NO_CACHE=1`.
+Entries marked `pubstate = {preprint}` are treated as confirmed preprint-only and muted from `check`/`upgrade`.
 
 ## For agents
 

{bibcite_cli-0.2.0 → bibcite_cli-0.4.0}/Readme.md

@@ -20,7 +20,7 @@ After every write, the file is formatted with [bibtex-tidy](https://github.com/F
 uv tool install --editable .
 
 # from git, no checkout needed
-uv tool install git+https://github.com/<you>/bibcite
+uv tool install git+https://github.com/leo1oel/bibcite
 
 # once published to PyPI (package name bibcite-cli, command name bibcite)
 uv tool install bibcite-cli   # or: uvx --from bibcite-cli bibcite ...
@@ -45,6 +45,13 @@ bibcite add refs.bib 2103.14030 --json
 # Add a raw BibTeX entry you already have (venue still canonicalized, file still tidied)
 bibcite add refs.bib --bibtex "$(pbpaste)"
 
+# Batch add (one query per line; shares rate-limit state, tidies once)
+bibcite add refs.bib --from ids.txt
+
+# Overwrite a bad existing entry (keeps its key), or delete one
+bibcite add refs.bib <query> --replace
+bibcite remove refs.bib <key>
+
 # One-shot cleanup: upgrade preprints → tidy → lint
 bibcite fix refs.bib
 
@@ -56,8 +63,11 @@ bibcite tidy refs.bib
 bibcite check refs.bib
 ```
 
-`--json` prints a machine-readable result on stdout (`action`, `key`, `venue`, `source`, ...); all diagnostics go to stderr.
+`add`/`upgrade`/`check`/`fix`/`remove` print a machine-readable JSON result on stdout (`action`, `key`, `venue`, `source`, ...); all diagnostics go to stderr.
 `add` is idempotent: an existing entry returns `action: exists` with its key, and an existing arXiv entry matched to a published version is upgraded in place, keeping its citation key.
+Exit codes: 0 success, 2 paper not found (ask for a better identifier), 3 sources/tool failure (retry later).
+Successful matches are cached at `~/.cache/bibcite/published.json` (published papers only — preprint status is never cached); bypass with `--no-cache` or `BIBCITE_NO_CACHE=1`.
+Entries marked `pubstate = {preprint}` are treated as confirmed preprint-only and muted from `check`/`upgrade`.
 
 ## For agents
 

{bibcite_cli-0.2.0 → bibcite_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bibcite-cli"
-version = "0.2.0"
+version = "0.4.0"
 description = "Resolve papers (arXiv id / DOI / title) to canonical, normalized BibTeX for agents and humans"
 readme = "Readme.md"
 license = "MIT"
@@ -11,6 +11,9 @@ dependencies = [
 ]
 keywords = ["bibtex", "arxiv", "citations", "dblp", "bibliography"]
 
+[project.urls]
+Repository = "https://github.com/leo1oel/bibcite"
+
 [project.scripts]
 bibcite = "bibcite.cli:main"
 

{bibcite_cli-0.2.0 → bibcite_cli-0.4.0}/src/bibcite/__init__.py

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

{bibcite_cli-0.2.0 → bibcite_cli-0.4.0}/src/bibcite/bibfile.py

@@ -14,23 +14,44 @@ from bibtexparser.bwriter import BibTexWriter
 from .normalize import norm_title
 
 # The exact bibtex-tidy invocation requested by the user; keep in sync with
-# their LaTeX workflow.
+# their LaTeX workflow. NOTE: no --generate-keys — bibcite owns key
+# generation (make_key ASCII-folds names, so Hyvärinen -> hyvarinen2000...,
+# where tidy would emit hyv_arinen2000...), and stable keys keep existing
+# \cite{} commands valid.
 TIDY_ARGS = [
     "--modify",
-    "--omit=pages,publisher,doi,timestamp,biburl,bibsource,abstract,month,series,volume,editor,note,date,number,address",
+    # volume/number/pages/doi are kept (bibliographic substance the user
+    # asked to retain); the omit list drops only true noise.
+    "--omit=publisher,timestamp,biburl,bibsource,abstract,month,series,editor,note,date,address",
     "--curly",
     "--blank-lines",
     "--trailing-commas",
     "--sort=-year",
     "--duplicates=citation",
     "--merge=first",
-    "--sort-fields=author,title,booktitle,journal,year,url,pdf",
+    "--sort-fields=author,title,booktitle,journal,volume,number,pages,year,doi,url,pdf",
     "--strip-enclosing-braces",
     "--tidy-comments",
-    "--generate-keys",
 ]
 
-NOISE_FIELDS = ("timestamp", "biburl", "bibsource", "crossref")
+NOISE_FIELDS = ("timestamp", "biburl", "bibsource", "crossref", "month")
+
+# BibTeX month macros. bibtexparser's common_strings only defines jan..dec;
+# CrossRef's transform endpoint emits bare full names (month=June), which
+# otherwise KeyError during string interpolation.
+MONTH_STRINGS = {
+    m[:3]: m.capitalize()
+    for m in (
+        "january february march april may june july august september "
+        "october november december"
+    ).split()
+} | {
+    m: m.capitalize()
+    for m in (
+        "january february march april may june july august september "
+        "october november december"
+    ).split()
+}
 
 ARXIV_ID_RE = re.compile(r"(\d{4}\.\d{4,5})(v\d+)?")
 
@@ -42,11 +63,18 @@ def _log(msg: str):
 def _parser() -> BibTexParser:
     p = BibTexParser(common_strings=True)
     p.ignore_nonstandard_types = False
+    p.bib_database.strings.update(MONTH_STRINGS)
     return p
 
 
 def parse_bib(text: str) -> BibDatabase:
-    return bibtexparser.loads(text, parser=_parser())
+    try:
+        return bibtexparser.loads(text, parser=_parser())
+    except Exception as e:
+        # Undefined @string macros raise bare KeyError('macro'); rewrap so
+        # callers see a real message and KeyError never masquerades as a
+        # LookupError "not found" upstream.
+        raise ValueError(f"BibTeX parse failed: {type(e).__name__}: {e}") from e
 
 
 def parse_bibtex_entry(text: str) -> dict:
@@ -117,36 +145,74 @@ def find_existing(db: BibDatabase, title: str, arxiv_id: str = "", doi: str = ""
     return None
 
 
-def upsert_entry(path: Path, entry: dict) -> tuple[str, str]:
+def upsert_entry(
+    path: Path, entry: dict, replace: bool = False, replace_key: str = ""
+) -> tuple[str, str]:
     """Insert or upgrade ``entry`` in ``path``.
 
-    Returns (action, key) where action is "added" | "upgraded" | "exists".
+    Returns (action, key), action in "added" | "upgraded" | "exists" |
+    "replaced" | "no_match_to_replace". With ``replace``, an existing
+    matching entry is overwritten; ``replace_key`` targets a specific entry
+    by citation key (for when title drift defeats the automatic match). The
+    existing key is always kept so \\cite{} commands stay valid. A replace
+    that matches nothing is an ERROR, not a silent add — that is how
+    duplicate entries sneak into a file.
     """
     db = load_bib_file(path)
     if db is None:  # unparseable file: append blindly
+        if replace or replace_key:
+            return "no_match_to_replace", replace_key or entry["ID"]
         with path.open("a") as f:
             f.write("\n" + entry_to_bibtex(entry))
         return "added", entry["ID"]
 
-    existing = find_existing(
-        db, entry.get("title", ""), entry_arxiv_id(entry), entry.get("doi", "")
-    )
+    if replace_key:
+        existing = next((e for e in db.entries if e.get("ID") == replace_key), None)
+    else:
+        existing = find_existing(
+            db, entry.get("title", ""), entry_arxiv_id(entry), entry.get("doi", "")
+        )
+
     if existing is not None:
-        if is_preprint(existing) and not is_preprint(entry):
+        upgrade = is_preprint(existing) and not is_preprint(entry)
+        if replace or replace_key or upgrade:
             key = existing["ID"]
             existing.clear()
-            existing.update(entry)
+            existing.update({k: str(v) for k, v in entry.items() if v})
             existing["ID"] = key  # keep the key the user may already \cite
             _write_db(path, db)
-            return "upgraded", key
+            return ("replaced" if (replace or replace_key) else "upgraded"), key
         return "exists", existing["ID"]
 
+    if replace or replace_key:
+        return "no_match_to_replace", replace_key or entry["ID"]
+
     db.entries.append({k: str(v) for k, v in entry.items() if v})
     _write_db(path, db)
     return "added", entry["ID"]
 
 
+def remove_entry(path: Path, key: str) -> bool:
+    """Delete the entry with citation key ``key``. True if something was
+    removed."""
+    db = load_bib_file(path)
+    if db is None:
+        return False
+    before = len(db.entries)
+    db.entries = [e for e in db.entries if e.get("ID") != key]
+    if len(db.entries) == before:
+        return False
+    _write_db(path, db)
+    return True
+
+
 def _write_db(path: Path, db: BibDatabase):
+    # Never write our injected month macros back out as @string blocks (they
+    # exist only so parsing month=June doesn't crash); this also scrubs any
+    # that leaked into a file before this guard existed. User-defined
+    # @strings are untouched.
+    for k in MONTH_STRINGS:
+        db.strings.pop(k, None)
     writer = BibTexWriter()
     writer.indent = "  "
     writer.order_entries_by = None  # preserve file order; tidy re-sorts anyway

bibcite_cli-0.4.0/src/bibcite/cache.py

@@ -0,0 +1,48 @@
+"""Local cache of successful publication matches.
+
+Keyed by normalized title. Only *published* matches are stored — a paper that
+is published stays published, while a preprint may get published tomorrow, so
+negative/preprint results are never cached. Re-running `fix`/`upgrade` or
+re-adding known papers therefore costs zero API calls.
+
+Disable with --no-cache or BIBCITE_NO_CACHE=1. Lives at
+$XDG_CACHE_HOME/bibcite/published.json (~/.cache/bibcite/published.json).
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+DISABLED = os.environ.get("BIBCITE_NO_CACHE", "") == "1"
+
+
+def _path() -> Path:
+    root = os.environ.get("XDG_CACHE_HOME") or "~/.cache"
+    return Path(root).expanduser() / "bibcite" / "published.json"
+
+
+def _load() -> dict:
+    try:
+        return json.loads(_path().read_text())
+    except Exception:
+        return {}
+
+
+def get(key: str) -> dict | None:
+    if DISABLED or not key:
+        return None
+    return _load().get(key)
+
+
+def put(key: str, value: dict):
+    if DISABLED or not key:
+        return
+    try:
+        data = _load()
+        data[key] = value
+        p = _path()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(json.dumps(data, ensure_ascii=False))
+    except Exception as e:  # cache must never break resolution
+        print(f"[cache] write failed: {e}", file=sys.stderr)