biolm.io package

Submodules

biolm.io.csv module

CSV format input/output utilities.

biolm.io.csv.load_csv(file_path: str | Path | IO, sequence_key: str | None = None) → List[Dict[str, Any]]

Load data from a CSV file.

Parses a CSV file and returns a list of dictionaries suitable for use with BioLM API requests. Each row becomes a dictionary with column headers as keys. All values are kept as strings (no type inference).

Args:

file_path: Path to CSV file (str, Path) or file-like object. sequence_key: Optional key name to validate exists in CSV; if provided, raises ValueError if column is missing.

Returns:

List of dictionaries, one per row.

Raises:

FileNotFoundError: If file path doesn’t exist. ValueError: If file is empty or sequence_key column is missing.

Example:

default Copy

>>> items = load_csv("data.csv", sequence_key="sequence")
>>> items[0]
{'sequence': 'ACDEFGHIKLMNPQRSTVWY', 'id': 'seq1', 'score': '0.95'}

biolm.io.csv.to_csv(data: List[Dict[str, Any]], file_path: str | Path | IO, fieldnames: List[str] | None = None) → None

Write data to a CSV file.

Converts a list of dictionaries (API response format) to CSV format.

Args:

data: List of dictionaries to write. file_path: Output file path (str, Path) or file-like object. fieldnames: Optional list of column names; if not provided, inferred from the first item’s keys (missing keys filled with empty strings).

Raises:

ValueError: If data is empty.

Example:

default Copy

>>> data = [{"sequence": "ACDEFGHIKLMNPQRSTVWY", "score": 0.95}]
>>> to_csv(data, "output.csv")

biolm.io.fasta module

FASTA format input/output utilities.

biolm.io.fasta.load_fasta(file_path: str | Path | IO) → List[Dict[str, Any]]

Load sequences from a FASTA file.

Parses a FASTA file and returns a list of dictionaries suitable for use with BioLM API requests. Each dictionary contains: - “sequence”: The sequence string - “id”: Sequence identifier from header (if available) - “metadata”: Additional metadata from header (if available)

Supports multi-line sequences (wrapped sequences).

Args:

file_path: Path to FASTA file (str, Path) or file-like object

Returns:

List of dictionaries, each containing sequence data

Raises:

FileNotFoundError: If file path doesn’t exist ValueError: If file is empty or malformed

Example:

default Copy

>>> items = load_fasta("sequences.fasta")
>>> items[0]
{'sequence': 'ACDEFGHIKLMNPQRSTVWY', 'id': 'seq1', 'metadata': {}}

biolm.io.fasta.to_fasta(data: List[Dict[str, Any]], file_path: str | Path | IO, sequence_key: str = 'sequence') → None

Write sequences to a FASTA file.

Converts a list of dictionaries (API response format) to FASTA format. Each dictionary should contain a sequence field (default: “sequence”).

Args:

data: List of dictionaries containing sequence data file_path: Output file path (str, Path) or file-like object sequence_key: Key to use for sequence data (default: “sequence”)

Raises:

ValueError: If sequence_key is missing from any item KeyError: If required keys are missing

Example:

default Copy

>>> data = [{"sequence": "ACDEFGHIKLMNPQRSTVWY", "id": "seq1"}]
>>> to_fasta(data, "output.fasta")

biolm.io.json module

JSON format input/output utilities.

biolm.io.json.load_json(file_path: str | Path | IO) → List[Dict[str, Any]]

Load data from a JSON file or JSONL (newline-delimited JSON) file.

Parses a JSON file and returns a list of dictionaries suitable for use with BioLM API requests. Supports: - Single JSON object: Returns list with one item - JSON array: Returns list of items - JSONL format (newline-delimited): Returns list of items, one per line

Args:

file_path: Path to JSON/JSONL file (str, Path), file-like object, or “-” for stdin

Returns:

List of dictionaries, each containing data suitable for API requests

Raises:

FileNotFoundError: If file path doesn’t exist ValueError: If file is empty or malformed json.JSONDecodeError: If JSON is invalid

Example:

default Copy

>>> items = load_json("data.json")
>>> items[0]
{'sequence': 'ACDEFGHIKLMNPQRSTVWY', 'id': 'seq1'}

default Copy

>>> items = load_json("data.jsonl")  # JSONL format
>>> len(items)
3

biolm.io.json.to_json(data: List[Dict[str, Any]], file_path: str | Path | IO, indent: int = 2, jsonl: bool = False) → None

Write data to a JSON file or JSONL (newline-delimited JSON) file.

Converts a list of dictionaries (API response format) to JSON format.

Args:

data: List of dictionaries to write. file_path: Output file path (str, Path), file-like object, or “-” for stdout. indent: Indentation level for JSON (default: 2). Use None for compact JSON. jsonl: If True, write as JSONL (one JSON object per line); if False, write as JSON array. Default: False.

Raises:

ValueError: If data is empty.

Example:

default Copy

>>> data = [{"sequence": "ACDEFGHIKLMNPQRSTVWY", "score": 0.95}]
>>> to_json(data, "output.json")
>>> to_json(data, "output.jsonl", jsonl=True)

biolm.io.pdb module

PDB format input/output utilities.

biolm.io.pdb.load_pdb(file_path: str | Path | IO) → List[Dict[str, Any]]

Load PDB structure(s) from a PDB file.

Reads a PDB file and returns a list of dictionaries suitable for use with BioLM API requests. For single-model PDBs, returns one item. For multi-model PDBs (with MODEL/ENDMDL records), returns one item per model.

Args:

file_path: Path to PDB file (str, Path) or file-like object

Returns:

List of dictionaries, each containing “pdb” key with PDB content. Single-model files return [{“pdb”: “…”}]. Multi-model files return [{“pdb”: “…”}, {“pdb”: “…”}, …].

Raises:

FileNotFoundError: If file path doesn’t exist ValueError: If file is empty

Example:

default Copy

>>> items = load_pdb("structure.pdb")
>>> items[0]
{'pdb': 'ATOM      1  N   MET A   1      20.154  16.967  19.502...'}

biolm.io.pdb.to_pdb(data: List[Dict[str, Any]], file_path: str | Path | IO, pdb_key: str = 'pdb') → None

Write PDB structure(s) to a PDB file.

Converts a list of dictionaries (API response format) to PDB format. Each dictionary should contain a PDB content field (default: “pdb”). If multiple items are provided, they are concatenated.

Args:

data: List of dictionaries containing PDB data file_path: Output file path (str, Path) or file-like object pdb_key: Key to use for PDB content (default: “pdb”)

Raises:

ValueError: If data is empty or pdb_key is missing from any item

Example:

default Copy

>>> data = [{"pdb": "ATOM      1  N   MET A   1..."}]
>>> to_pdb(data, "output.pdb")

Module contents

IO utilities for converting between file formats and API JSON structures.

This module provides functions to load data from common biological file formats (FASTA, CSV, PDB, JSON) into BioLM API request format, and to export API responses back to these formats.

biolm.io.load_csv(file_path: str | Path | IO, sequence_key: str | None = None) → List[Dict[str, Any]]

Load data from a CSV file.

Parses a CSV file and returns a list of dictionaries suitable for use with BioLM API requests. Each row becomes a dictionary with column headers as keys. All values are kept as strings (no type inference).

Args:

file_path: Path to CSV file (str, Path) or file-like object. sequence_key: Optional key name to validate exists in CSV; if provided, raises ValueError if column is missing.

Returns:

List of dictionaries, one per row.

Raises:

FileNotFoundError: If file path doesn’t exist. ValueError: If file is empty or sequence_key column is missing.

Example:

default Copy

>>> items = load_csv("data.csv", sequence_key="sequence")
>>> items[0]
{'sequence': 'ACDEFGHIKLMNPQRSTVWY', 'id': 'seq1', 'score': '0.95'}

biolm.io.load_fasta(file_path: str | Path | IO) → List[Dict[str, Any]]

Load sequences from a FASTA file.

Parses a FASTA file and returns a list of dictionaries suitable for use with BioLM API requests. Each dictionary contains: - “sequence”: The sequence string - “id”: Sequence identifier from header (if available) - “metadata”: Additional metadata from header (if available)

Supports multi-line sequences (wrapped sequences).

Args:

file_path: Path to FASTA file (str, Path) or file-like object

Returns:

List of dictionaries, each containing sequence data

Raises:

FileNotFoundError: If file path doesn’t exist ValueError: If file is empty or malformed

Example:

default Copy

>>> items = load_fasta("sequences.fasta")
>>> items[0]
{'sequence': 'ACDEFGHIKLMNPQRSTVWY', 'id': 'seq1', 'metadata': {}}

biolm.io.load_json(file_path: str | Path | IO) → List[Dict[str, Any]]

Load data from a JSON file or JSONL (newline-delimited JSON) file.

Parses a JSON file and returns a list of dictionaries suitable for use with BioLM API requests. Supports: - Single JSON object: Returns list with one item - JSON array: Returns list of items - JSONL format (newline-delimited): Returns list of items, one per line

Args:

file_path: Path to JSON/JSONL file (str, Path), file-like object, or “-” for stdin

Returns:

List of dictionaries, each containing data suitable for API requests

Raises:

FileNotFoundError: If file path doesn’t exist ValueError: If file is empty or malformed json.JSONDecodeError: If JSON is invalid

Example:

default Copy

>>> items = load_json("data.json")
>>> items[0]
{'sequence': 'ACDEFGHIKLMNPQRSTVWY', 'id': 'seq1'}

default Copy

>>> items = load_json("data.jsonl")  # JSONL format
>>> len(items)
3

biolm.io.load_pdb(file_path: str | Path | IO) → List[Dict[str, Any]]

Load PDB structure(s) from a PDB file.

Reads a PDB file and returns a list of dictionaries suitable for use with BioLM API requests. For single-model PDBs, returns one item. For multi-model PDBs (with MODEL/ENDMDL records), returns one item per model.

Args:

file_path: Path to PDB file (str, Path) or file-like object

Returns:

List of dictionaries, each containing “pdb” key with PDB content. Single-model files return [{“pdb”: “…”}]. Multi-model files return [{“pdb”: “…”}, {“pdb”: “…”}, …].

Raises:

FileNotFoundError: If file path doesn’t exist ValueError: If file is empty

Example:

default Copy

>>> items = load_pdb("structure.pdb")
>>> items[0]
{'pdb': 'ATOM      1  N   MET A   1      20.154  16.967  19.502...'}

biolm.io.to_csv(data: List[Dict[str, Any]], file_path: str | Path | IO, fieldnames: List[str] | None = None) → None

Write data to a CSV file.

Converts a list of dictionaries (API response format) to CSV format.

Args:

data: List of dictionaries to write. file_path: Output file path (str, Path) or file-like object. fieldnames: Optional list of column names; if not provided, inferred from the first item’s keys (missing keys filled with empty strings).

Raises:

ValueError: If data is empty.

Example:

default Copy

>>> data = [{"sequence": "ACDEFGHIKLMNPQRSTVWY", "score": 0.95}]
>>> to_csv(data, "output.csv")

biolm.io.to_fasta(data: List[Dict[str, Any]], file_path: str | Path | IO, sequence_key: str = 'sequence') → None

Write sequences to a FASTA file.

Converts a list of dictionaries (API response format) to FASTA format. Each dictionary should contain a sequence field (default: “sequence”).

Args:

data: List of dictionaries containing sequence data file_path: Output file path (str, Path) or file-like object sequence_key: Key to use for sequence data (default: “sequence”)

Raises:

ValueError: If sequence_key is missing from any item KeyError: If required keys are missing

Example:

default Copy

>>> data = [{"sequence": "ACDEFGHIKLMNPQRSTVWY", "id": "seq1"}]
>>> to_fasta(data, "output.fasta")

biolm.io.to_json(data: List[Dict[str, Any]], file_path: str | Path | IO, indent: int = 2, jsonl: bool = False) → None

Write data to a JSON file or JSONL (newline-delimited JSON) file.

Converts a list of dictionaries (API response format) to JSON format.

Args:

data: List of dictionaries to write. file_path: Output file path (str, Path), file-like object, or “-” for stdout. indent: Indentation level for JSON (default: 2). Use None for compact JSON. jsonl: If True, write as JSONL (one JSON object per line); if False, write as JSON array. Default: False.

Raises:

ValueError: If data is empty.

Example:

default Copy

>>> data = [{"sequence": "ACDEFGHIKLMNPQRSTVWY", "score": 0.95}]
>>> to_json(data, "output.json")
>>> to_json(data, "output.jsonl", jsonl=True)

biolm.io.to_pdb(data: List[Dict[str, Any]], file_path: str | Path | IO, pdb_key: str = 'pdb') → None

Write PDB structure(s) to a PDB file.

Converts a list of dictionaries (API response format) to PDB format. Each dictionary should contain a PDB content field (default: “pdb”). If multiple items are provided, they are concatenated.

Args:

data: List of dictionaries containing PDB data file_path: Output file path (str, Path) or file-like object pdb_key: Key to use for PDB content (default: “pdb”)

Raises:

ValueError: If data is empty or pdb_key is missing from any item

Example:

default Copy

>>> data = [{"pdb": "ATOM      1  N   MET A   1..."}]
>>> to_pdb(data, "output.pdb")