API reference

Stream alignment records from htsget servers.

Example usage:

import htslurp

records = htslurp.stream_records(
    "https://htsget.ga4gh.org/reads",
    "giab.NA12878",
    "CRAM",
    region="11:4900000-5000000",
)
header_text = records.header.decode()
for line in records:
    fields = line.decode().split("\t")
    # ... or feed line.decode() and a pysam.AlignmentHeader built from
    # header_text to pysam.AlignedSegment.fromstring.

stream_records(base_url, id, format, region=None, reference=None) builtin

Stream alignment records from an htsget server.

Lazily fetches and decodes a (possibly region-restricted) BAM or CRAM slice; the full response is never materialized.

Parameters:

Name	Type	Description	Default
base_url	str	htsget endpoint URL (e.g. "https://htsget.ga4gh.org/reads").	required
id	str	Resource identifier on the server (e.g. "giab.NA12878").	required
format	str	"BAM" or "CRAM".	required
region	str	Genomic region string (e.g. "chr1:1000-2000"). When set, records that don't overlap are dropped.	None
reference	str	Path to an indexed FASTA. Required only for CRAMs that use external reference-based compression.	None

Returns:

Type	Description
RecordIter	Lazy iterator of SAM-format bytes lines; its header attribute holds the SAM header as bytes.

Raises:

Type	Description
RuntimeError	If the request fails (unreachable server, unknown id, invalid region) or a record fails to decode mid-stream.