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.
Related Python Libraries
The following libraries support additional bibliographic formats, conversion workflows, and reference extraction:
- BibtexParser — A lightweight, actively maintained library for reading, writing, and modifying
.bibfiles. 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.