Create methods and type stubs on pysam htslib C extension calls

[NatPRoach]

It is often helpful to use pysam bindings to htslib functions a la

import pysam
pysam.sort(myfile, "-o", my_output)

etc.

mypy will complain when attempting to use these functions (presumably because they originate from a C extension module) with an error "AttributeError: module pysam has no attribute 'sort'"

I think it would behoove us to make wrapper functions around the pysam htslib calls with named parameters and type checking etc. This will require generating stubs for the functions, e.g.

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    def sort(*args: Any) -> None:
        pass
else:
    from pysam import sort

def sort_samfile( ... ) -> None:
    ... (some invocation that references `sort` ...

[nh13]

Why not solve it in pysam so everyone can benefit? https://github.com/pysam-developers/pysam/issues/1153

[tfenne]

Well, @nh13 part of the goal of this would be to provide a better interface that has the commonly used parameters to each of samtools' command line modules exposed as actual python parameters, so they are easier to use. E.g. instead of sort(*args: Any), we might want:

def sort(in_bam: Path, out_bam: Path, compress: int = 5, by_name: bool = False, threads: int = 1)

[nh13]

That makes sense. My only hesitancy is that the interface is tied to a specific samtools version, so we’d have to pin the version and revisit the available options each time we update the samtools dependency. And then why not have it in pysam?

[NatPRoach]

@nh13 @tfenne I have a draft PR for the first of the wrappers here, more to come. If we want to get them reviewed here and then use that to make a PR into pysam I am also fine with that. Would just need the heads up if that's what we want to do.

https://github.com/fulcrumgenomics/fgpyo/pull/26