API reference

The strict standalone public API is:

File operations infer formats from filename suffixes unless an explicit format is provided. String operations require format. See Usage for the read/write format matrix, including the distinction between built-in Markdown table output and pending optional reference-list parsing.

Loading API

Raw loaders return an ordered list of record dictionaries with parser-level field names and values (for example, strings, lists, or mappings). They do not apply normalization or assign IDs.

bibliography_io.load_raw(path, *, format=None, mapping_fields=(), list_fields=())
bibliography_io.loads_raw(string, *, format, mapping_fields=(), list_fields=())

mapping_fields and list_fields declare structured BibTeX fields. File operations infer format from the suffix unless supplied explicitly; string operations require it.

The convenience loader applies generic normalization when source is omitted. If source is supplied, it selects an installed CoLRev search-source package by its unique endpoint identifier (for example, colrev.crossref). source_version is an optional export-version label. File suffixes are used to infer the format unless format is supplied; pass format when the suffix is ambiguous or does not match the file’s actual format. Use the raw loading APIs for parser-level values.

For the return-value contracts of the raw, normalized, and primary loaders, see the Record shape section in Usage.

bibliography_io.load(path, *, source=None, source_version=None, format=None)

It returns a list of record dictionaries in source order. CoLRev search-source packages register search_source entry points in the colrev entry-point group; bibliography-io selects the package whose endpoint matches source. Source-specific hook behavior and package registration are described in Source extensions for bibliography-io. A missing package raises OptionalBackendUnavailableError.

load_df() calls load() and returns its normalized records as DataFrame rows. Parser-level data is available through the list-returning raw APIs rather than a raw DataFrame helper.

bibliography_io.load_primary(path, *, format=None, header_only=False, mapping_fields=(), list_fields=())

Load primary records as an ID-indexed dictionary.

For BibTeX, header_only=True extracts ID, ENTRYTYPE, colrev_origin, colrev_status, file, screening_criteria, and colrev_masterdata_provenance while skipping other fields. Ordinary field values are strings. Declare fields through mapping_fields or list_fields to decode their BibTeX values into dictionaries or lists. Undeclared values remain strings.

Parameters:

  • path (str | Path)

  • format (str | None)

  • header_only (bool)

  • mapping_fields (Any)

  • list_fields (Any)

Return type:

dict[str, dict[str, Any]]

bibliography_io.loads_primary(text, *, format, mapping_fields=(), list_fields=())

Load primary records from a string as an ID-indexed dictionary.

Parameters:

  • text (str)

  • format (str)

  • mapping_fields (Any)

  • list_fields (Any)

Return type:

dict[str, dict[str, Any]]

bibliography_io.write(records, *, path, format=None, mapping_fields=(), list_fields=(), field_order=None, sort_fields=True, primary=False, sort_by_id=True)

Write records, replacing existing contents.

For BibTeX, mapping_fields and list_fields declare provenance mappings and semicolon-delimited list fields. Supplying either option for other formats raises UnsupportedFormatError. Set primary=True to validate an ID-keyed primary-record mapping, sort records by ID, and restrict output to BibTeX. By default, field_order (or the CoLRev-oriented order when omitted) is followed by remaining fields alphabetically. Set sort_fields=False to preserve input field order without sorting. Inputs are sorted by record ID by default. CSV, Markdown, Excel, and RIS output always uses ID order; sort_by_id=False preserves input order only for formats that support it. primary=True continues to sort the validated primary mapping by ID.

Parameters:

  • records (Any)

  • path (str | Path)

  • format (str | None)

  • mapping_fields (Any)

  • list_fields (Any)

  • field_order (Any)

  • sort_fields (bool)

  • primary (bool)

  • sort_by_id (bool)

Return type:

None

bibliography_io.to_string(records, *, format, mapping_fields=(), list_fields=(), field_order=None, sort_fields=True, sort_by_id=True)

Return records written as a formatted string.

For BibTeX, mapping_fields and list_fields declare provenance mappings and semicolon-delimited list fields. Supplying either option for other formats raises UnsupportedFormatError. The declared names match the record field names (matching is case-insensitive, as BibTeX field names are). By default, field_order (or the CoLRev-oriented order when omitted) is followed by remaining fields alphabetically. Set sort_fields=False to preserve the input field order without sorting. Inputs are sorted by record ID by default. CSV, Markdown, Excel, and RIS output always uses ID order; sort_by_id=False preserves input order only for formats that support it.

Parameters:

  • records (Any)

  • format (str)

  • mapping_fields (Any)

  • list_fields (Any)

  • field_order (Any)

  • sort_fields (bool)

  • sort_by_id (bool)

Return type:

str

bibliography_io.load_df(path, *, source=None, source_version=None, format=None)

Load normalized records into a DataFrame.

format overrides suffix inference when a file suffix is ambiguous or does not match the file’s actual format. Source-specific normalization can be selected with source and source_version.

Parameters:

  • path (str | Path)

  • source (str | None)

  • source_version (str | None)

  • format (str | None)

Return type:

Any

bibliography_io.load_primary_df(path, *, format=None, header_only=False, mapping_fields=(), list_fields=())

Load primary records into a DataFrame indexed by record ID.

Parameters:

  • path (str | Path)

  • format (str | None)

  • header_only (bool)

  • mapping_fields (Any)

  • list_fields (Any)

Return type:

Any

bibliography_io.get_nr_records(filename)

Return the number of raw records in a file.

Parameters:

filename (str | Path)

Return type:

int