Skip to main content
bibliography-io logo

bibliography-io

PyPI - Version PyPI - Python Version License GitHub Actions Documentation

bibliography-io addresses the distinct requirements of bibliographic data management throughout literature reviews: robust ingestion of heterogeneous source data and efficient, reproducible management of primary records.

These stages have different priorities:

  • Ingestion and normalization adapt source data for processing. load() orchestrates parsing and normalization, applying source-specific rules to transform differing source structures into a common primary record representation.
  • Primary data management prioritizes efficiency and reproducibility. Normalized records follow a consistent schema with unique IDs. Frequent reading and writing require efficient dictionary-based access, partial header loading, targeted updates, and deterministic serialization that avoids meaningless Git diffs.

Accordingly, bibliography-io distinguishes two interfaces:

  • load() — Orchestrated ingestion and normalization that parses source-specific structures into a common primary record representation.
  • load_primary() — Efficient I/O for consistently structured primary records.

Unlike format-specific libraries with differing internal representations, bibliography-io provides a common record structure across input formats, enabling source-independent processing in subsequent literature review steps.

The package also minimizes dependencies, requiring specialized packages (e.g., for Excel or GROBID-based extraction) only when needed, facilitating integration into diverse literature review workflows.

Installation

Install the base package with:

pip install bibliography-io

Install optional features as needed:

pip install "bibliography-io[markdown]"  # Markdown parsing through GROBID
pip install "bibliography-io[excel]"     # Excel file support
pip install "bibliography-io[all]"       # Both optional features

Markdown reference-list parsing uses the standalone grobid-tei client and requires a GROBID service started by the caller. The loader is designed to operate independently of the workflow application that uses it: it does not start, stop, or otherwise manage GROBID. The service URL defaults to http://localhost:8070; set BIBLIOGRAPHY_IO_GROBID_URL to provide another URL. If the configured service is unavailable, Markdown loading raises BackendExecutionError. Formats available in the base bibliography-io installation do not require the Markdown extra.

Usage

from bibliography_io import load, load_primary, write

records = load("references.bib", source="colrev.web_of_science")
write(records, path="primary.bib", primary=True)
primary_records = load_primary("primary.bib")

File APIs infer the format from recognized suffixes; an explicit format can override inference. String APIs always require format:

from bibliography_io import to_string
from bibliography_io import loads_raw

records = loads_raw("@article{example, title={An example}}", format="bib")
text = to_string(records, format="bib")

File formats are inferred from their suffixes; pass format to load() when a suffix is ambiguous or does not match the file's actual format.

Format support

Format Read files Write files String APIs
BibTeX (.bib) Yes Yes loads_raw() / to_string()
RIS (.ris) Yes Yes loads_raw() / to_string()
ENL / EndNote (.enl) Yes Planned loads_raw() (to_string() planned)
NBIB (.nbib) Yes Planned loads_raw() (to_string() planned)
JSON (.json) Yes Planned loads_raw() (to_string() planned)
CSV (.csv) Yes Yes loads_raw() / to_string()
Excel (.xls, .xlsx) Yes Yes File APIs only
Markdown (.md) Yes (markdown extra) Yes (tables) loads_raw() / to_string()

Markdown table writing is built into bibliography-io. Markdown reference-list parsing uses GROBID through the standalone grobid-tei client and requires a service started and managed by the caller. It defaults to http://localhost:8070; set BIBLIOGRAPHY_IO_GROBID_URL to use another URL. The loader is designed to operate independently of the workflow application that uses it and never manages the service. PDF handling will be added later.

See the documentation for installation details, usage examples, and the generated API reference.

Development

See the development documentation for test, lint, and documentation build instructions.

The following libraries support additional bibliographic formats, conversion workflows, and reference extraction:

  • BibtexParser — A lightweight, actively maintained library for reading, writing, and modifying .bib files. Supports customizable parsing, field transformations, and BibTeX writing. Best suited for general-purpose BibTeX processing.
  • Pybtex — A bibliography processing library that supports BibTeX parsing, citation formatting, and conversion between bibliography formats. Provides extensible formatting styles and output formats such as LaTeX, HTML, and plain text. Best suited for generating formatted references.
  • biblib — A library for managing bibliographic databases, including merging entries, accessing metadata, and retrieving references using DOI or ISBN identifiers. Useful for building custom bibliography management workflows, although its last PyPI release was in 2018.
  • rispy — A lightweight Python library for reading and writing RIS files. Supports configurable tag mappings and custom parsers/writers. Best suited for standalone RIS processing.
  • pybtexris — A Pybtex plugin for reading RIS files and converting them into formats such as BibTeX. Also supports bibliography formatting through Pybtex.
  • pybtexnbib — A Pybtex plugin for parsing PubMed/MEDLINE (.nbib) files. Useful for integrating PubMed references into BibTeX and other bibliography workflows.
  • endnote-utils — A utility for converting EndNote XML and RIS records to CSV, JSON, and Excel formats. Also provides command-line tools for bibliographic data processing.
  • Biopython (Bio.Medline) — Provides parsers for MEDLINE-formatted records, including PubMed exports. Best suited for biomedical literature processing.
  • pubmed-parser — A Python library for extracting structured metadata from PubMed and PubMed Central XML datasets. Particularly useful for large-scale biomedical literature analysis.

License

This project is distributed under the MIT License.

Metadata

Release files for bibliography-io 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bibliography-io 0.4.0
File Size Uploaded Provenance Actions
bibliography_io-0.4.0.tar.gz 585.6 kB With provenance Details for bibliography_io-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bibliography-io 0.4.0
File Interpreter ABI Platform Actions
bibliography_io-0.4.0-py3-none-any.whl Python 3 none any Details for bibliography_io-0.4.0-py3-none-any.whl

Total release size: 624.2 kB

Release files / bibliography_io-0.4.0.tar.gz

Download URL bibliography_io-0.4.0.tar.gz
Size 585.6 kB
Tags Source
SHA-256 checksum
How to use checksums
c3dd3318ef9269f6e2bba856ee53db96db175304486c28b35454d56dc437a0e1
BLAKE2b-256 checksum
How to use checksums
5381be798f59fab92596590a04232f13c5870eebaec7d3bd5d1198551b41df28
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Release files / bibliography_io-0.4.0-py3-none-any.whl

Download URL bibliography_io-0.4.0-py3-none-any.whl
Size 38.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7d6a47fad0ec410a04b2aedf3e91cff384e0e3cf9956ff16597d6d2ddf85628d
BLAKE2b-256 checksum
How to use checksums
21bfbf11fa35991f4da88efd8bccdb2708224c092264da259c529ef0f4ba0cae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Security for bibliography-io 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for bibliography_io-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page