#!/usr/bin/env python3
"""Download BibTeX for all references of an arXiv paper via the INSPIRE REST API.\n
Given an arXiv ID (e.g. 2604.20797 or hep-ph/0603175), looks up the paper on
INSPIRE-HEP and fetches BibTeX for all its references in bulk via the search
endpoint (citedby:recid:...&format=bibtex).\n
Entries are returned sorted by most recent first.  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
References that are not yet indexed in INSPIRE are automatically excluded by
the search endpoint.\n
Rate limits: INSPIRE allows 15 requests per 5 seconds per IP.  The script
inserts a 0.4 s pause between page requests and automatically retries on
HTTP 429 with exponential backoff.\n
Progress and status messages are printed to stderr, so stdout contains only
BibTeX when writing to a pipe.\n
Usage:
    python scripts/inspire_references_bibtex.py 2604.20797
    python scripts/inspire_references_bibtex.py 2604.20797 > refs.bib
    python scripts/inspire_references_bibtex.py 2604.20797 -o refs.bib
    python scripts/inspire_references_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 reference 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, "citedby")
    log_to_stderr(f"  {total} references indexed in INSPIRE")
    #
    if total == 0:
        log_to_stderr("Nothing to fetch.")
        return
    #
    entries = fetch_bibtex_paginated(recid, total, "citedby")
    log_to_stderr(f"  {len(entries)} BibTeX entries retrieved")
    #
    write_bibtex_to_file(entries, args.output)

if __name__ == "__main__":
    main()