#!/usr/bin/env python3
"""Download BibTeX for all papers that cite a given arXiv paper via INSPIRE.\n
Given an arXiv ID (e.g. 2604.20797 or hep-ph/0603175), resolves it to an
INSPIRE record and queries the ``refersto:recid:…`` search to collect every
citing paper in BibTeX format.  Results are fetched in pages of up to 1000
entries; if more than 1000 papers cite the target the script paginates
automatically.\n
By default the combined BibTeX is written to stdout so it can be piped or
redirected.  Use -o / --output to save directly to a file instead.\n
Rate limits: INSPIRE allows 15 requests per 5 seconds per IP; the script
inserts a 0.35 s pause between page fetches to stay comfortably under that cap.\n
Progress and status messages are printed to stderr, so stdout contains only
BibTeX when writing to a pipe.\n
Usage:
    python scripts/inspire_citations_bibtex.py 2604.20797
    python scripts/inspire_citations_bibtex.py 2604.20797 > cites.bib
    python scripts/inspire_citations_bibtex.py 2604.20797 -o cites.bib
    python scripts/inspire_citations_bibtex.py hep-ph/0603175
"""

import argparse
import os
import sys

sys.path.insert(0, os.path.dirname(__file__))

from inspire_lib import (
    resolve_arxiv_to_inspire_id,
    fetch_bibtex_paginated,
    count_matching_records,
    log_to_stderr,
    write_bibtex_to_file,
)

def main():
    """Parse CLI arguments and download citation BibTeX from INSPIRE-HEP."""
    parser = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument(
        "arxiv_id", help="arXiv paper ID, e.g. 2604.20797 or hep-ph/0603175"
    )
    parser.add_argument("-o", "--output", help="Output .bib file (default: stdout)")
    args = parser.parse_args()
    #
    log_to_stderr(f"Looking up arXiv:{args.arxiv_id} on INSPIRE...")
    recid = resolve_arxiv_to_inspire_id(args.arxiv_id)
    log_to_stderr(f"  recid = {recid}")
    #
    total = count_matching_records(recid, "refersto")
    log_to_stderr(f"  {total} citations indexed in INSPIRE")
    #
    if total == 0:
        log_to_stderr("Nothing to fetch.")
        return
    #
    entries = fetch_bibtex_paginated(recid, total, "refersto")
    log_to_stderr(f"  {len(entries)} BibTeX entries retrieved")
    #
    write_bibtex_to_file(entries, args.output)

if __name__ == "__main__":
    main()