bibcite-cli 0.1.0__tar.gz → 0.3.0__tar.gz

{bibcite_cli-0.1.0 → bibcite_cli-0.3.0}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.4
 Name: bibcite-cli
-Version: 0.1.0
+Version: 0.3.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,16 +58,29 @@ 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
+
 # Upgrade every arXiv entry in a file to its published version (bibMatcher, CLI-style)
 bibcite upgrade refs.bib --dry-run
 
-# Just format, or just lint
+# Just format, or just lint (check is read-only)
 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.1.0 → bibcite_cli-0.3.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,16 +45,29 @@ 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
+
 # Upgrade every arXiv entry in a file to its published version (bibMatcher, CLI-style)
 bibcite upgrade refs.bib --dry-run
 
-# Just format, or just lint
+# Just format, or just lint (check is read-only)
 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.1.0 → bibcite_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bibcite-cli"
-version = "0.1.0"
+version = "0.3.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.1.0 → bibcite_cli-0.3.0}/src/bibcite/__init__.py

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

{bibcite_cli-0.1.0 → bibcite_cli-0.3.0}/src/bibcite/bibfile.py

@@ -14,7 +14,10 @@ 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",
@@ -27,10 +30,26 @@ TIDY_ARGS = [
     "--sort-fields=author,title,booktitle,journal,year,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 +61,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,10 +143,12 @@ 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) -> 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". With ``replace``, an existing matching entry is overwritten
+    (its citation key is kept so existing \\cite{} commands stay valid).
     """
     db = load_bib_file(path)
     if db is None:  # unparseable file: append blindly
@@ -132,13 +160,14 @@ def upsert_entry(path: Path, entry: dict) -> tuple[str, str]:
         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 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 else "upgraded"), key
         return "exists", existing["ID"]
 
     db.entries.append({k: str(v) for k, v in entry.items() if v})
@@ -146,6 +175,20 @@ def upsert_entry(path: Path, entry: dict) -> tuple[str, str]:
     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):
     writer = BibTexWriter()
     writer.indent = "  "

bibcite_cli-0.3.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)