Python API Reference ==================== This guide covers using OneCite as a Python library in your own code. Basic Usage ----------- Simple Citation Processing ~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: from onecite import process_references # Process a simple reference result = process_references( input_content="10.1038/nature14539", input_type="txt", template_name="journal_article_full", output_format="bibtex" ) # Print results for citation in result['results']: print(citation) The Result Dictionary ~~~~~~~~~~~~~~~~~~~~~ The ``process_references`` function returns a dictionary containing: - ``results`` (List[str]): List of formatted citation strings, one per unique resolved work - ``report`` (dict): Processing report with keys: - ``total`` (int): Total number of entries processed - ``succeeded`` (int): Number of successfully processed entries - ``failed_entries`` (List[Dict]): Failed entries, each with the original input text (``raw_text``) and a ``reason`` code - ``warnings`` (List[Dict]): Non-blocking review warnings, e.g. ``text_metadata_mismatch`` when the input text appears to describe a different work than the resolved DOI - ``duplicates`` (List[Dict]): Entries whose DOI already resolved earlier in the batch :: result = process_references( input_content="10.1038/nature14539", input_type="txt", template_name="journal_article_full", output_format="bibtex" ) print(f"Total: {result['report']['total']}") print(f"Succeeded: {result['report']['succeeded']}") print(f"Failed: {len(result['report']['failed_entries'])}") Processing Different Input Formats ----------------------------------- Plain Text Input ~~~~~~~~~~~~~~~~ :: from onecite import process_references txt_content = """ 10.1038/nature14539 arXiv:1706.03762 ISBN:9780262035613 """ result = process_references( input_content=txt_content, input_type="txt", template_name="journal_article_full", output_format="bibtex" ) # Access results print('\n\n'.join(result['results'])) BibTeX Input ~~~~~~~~~~~~ :: from onecite import process_references bibtex_content = """ @article{LeCun2015, title = {Deep Learning}, author = {LeCun, Yann and Bengio, Yoshua and Hinton, Geoffrey}, journal = {Nature}, year = {2015} } """ result = process_references( input_content=bibtex_content, input_type="bib", template_name="journal_article_full", output_format="bibtex" ) print('\n\n'.join(result['results'])) Output Formats -------------- OneCite supports BibTeX and CSL-JSON output:: # BibTeX (default) result = process_references( input_content="10.1038/nature14539", input_type="txt", template_name="journal_article_full", output_format="bibtex" ) # CSL-JSON — each result string is one CSL item (JSON object), # ready for pandoc, Quarto, citeproc, or reference-manager import result = process_references( input_content="10.1038/nature14539", input_type="txt", template_name="journal_article_full", output_format="csl-json" ) Passing any other value (such as ``"apa"`` or ``"mla"``) raises ``FormatError``; styled rendering belongs to dedicated tools like pandoc or citeproc-py, which consume the CSL-JSON that OneCite emits. Candidate Suggestions for Ambiguous References ---------------------------------------------- For plain-text title searches, use the suggestion API instead of resolving directly to BibTeX: :: from onecite import suggest_references result = suggest_references( input_content="Deep learning Hinton", input_type="txt", limit=5, ) for suggestion in result['suggestions']: for candidate in suggestion['candidates']: print(candidate['title'], candidate.get('doi', '')) A note on ``interactive_callback`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``process_references`` accepts an ``interactive_callback`` keyword for backward compatibility, but it is **never invoked**: ``process`` is strictly non-interactive and fail-closed. Entries without a verifiable strong identifier stay unresolved and are reported. To review candidates for an ambiguous reference and then resolve one, take the DOI from the chosen suggestion and pass it back through ``process_references``. Advanced Data Structures ------------------------ OneCite defines three TypedDict classes representing different stages of the processing pipeline: RawEntry ~~~~~~~~ A TypedDict representing an unprocessed reference entry (Stage 1): :: from onecite import RawEntry from typing import Dict, Any, Optional # RawEntry is a TypedDict with these fields: entry: RawEntry = { 'id': 1, 'raw_text': "10.1038/nature14539", 'doi': "10.1038/nature14539", 'url': None, 'query_string': None, 'original_entry': None } IdentifiedEntry ~~~~~~~~~~~~~~~ A TypedDict representing an entry after identification from data sources (Stage 2): :: from onecite import IdentifiedEntry # IdentifiedEntry includes fields like: # id, raw_text, doi, arxiv_id, url, metadata, status CompletedEntry ~~~~~~~~~~~~~~~ A TypedDict representing a completed or failed Stage-3 entry. A completed entry contains the metadata available to the formatter; it is not guaranteed to have every possible field: :: from onecite import CompletedEntry # CompletedEntry includes fields like: # id, doi, status, bib_key, bib_data These are TypedDict classes used internally by the pipeline. For typical usage, call ``process_references()`` directly. Working with Templates ---------------------- Load and inspect templates:: from onecite import TemplateLoader loader = TemplateLoader() # Load a specific template template = loader.load_template("journal_article_full") print(f"Template name: {template['name']}") print(f"Entry type: {template['entry_type']}") print(f"Fields: {[f['name'] for f in template['fields']]}") # Use a custom templates directory custom_loader = TemplateLoader(templates_dir="/path/to/templates") custom_template = custom_loader.load_template("my_template") Using the Pipeline Controller ------------------------------ For advanced use cases requiring more control over the processing pipeline: :: from onecite import PipelineController # Create controller (optionally enable Google Scholar) controller = PipelineController(use_google_scholar=False) # Process with full control result = controller.process( input_content="10.1038/nature14539", input_type="txt", template_name="journal_article_full", output_format="bibtex" ) print('\n\n'.join(result['results'])) For typical usage, ``process_references()`` is simpler and covers the same functionality. Error Handling -------------- Handling Exceptions ~~~~~~~~~~~~~~~~~~~ :: from onecite import process_references, ValidationError, ParseError try: result = process_references( input_content="invalid_reference", input_type="txt", template_name="journal_article_full", output_format="bibtex" ) except ValidationError as e: print(f"Validation error: {e}") except ParseError as e: print(f"Parse error: {e}") except Exception as e: print(f"Processing error: {e}") Processing Files ---------------- Reading from File ~~~~~~~~~~~~~~~~~ :: from onecite import process_references # Read from file with open("references.txt", "r", encoding="utf-8") as f: content = f.read() result = process_references( input_content=content, input_type="txt", template_name="journal_article_full", output_format="bibtex" ) # Write to file output_content = '\n\n'.join(result['results']) with open("output.bib", "w", encoding="utf-8") as f: f.write(output_content) Complete Example ---------------- :: from onecite import process_references # Read references with open("my_references.txt", "r", encoding="utf-8") as f: references = f.read() # Process with BibTeX format result = process_references( input_content=references, input_type="txt", template_name="journal_article_full", output_format="bibtex" ) # Check results report = result['report'] print(f"Total entries: {report['total']}") print(f"Successfully processed: {report['succeeded']}") print(f"Failed: {len(report['failed_entries'])}") if report['failed_entries']: print("\nFailed entries:") for failed in report['failed_entries']: print(f" - Entry {failed['id']}: {failed.get('error', 'Unknown error')}") # Save output output_content = '\n\n'.join(result['results']) with open("formatted_refs.txt", "w", encoding="utf-8") as f: f.write(output_content) print("\nDone!") API Reference ------------- See :doc:`api/core` for the complete API documentation. Next Steps ---------- - Explore :doc:`templates` for custom formatting - Check :doc:`faq` for common questions