Developer’s guide

Code organization

The top level directory is organized in the following directories:

pysam

Code specific to pysam.

doc

The documentation. To build the latest documentation, first install Sphinx and then type:

make -C doc html

tests

Code and data for testing and benchmarking.

htslib

Source code from htslib shipped with pysam. See import.py about importing.

samtools

Source code from samtools shipped with pysam. See import.py about importing.

bcftools

Source code from bcftools shipped with pysam. See import.py about importing.

Python language level

Pysam currently requires Python 3.6 as a minimum language level. For example, this means that the following comparatively recent language features and library functions are available for use:

f-strings
raise ... from None
str.startswith(), str.endswith(), str.rstrip(), etc

However in particular the the following should not be used in pysam source code or infrastructure scripts:

str.removeprefix(), str.removesuffix() (new in 3.9)
walrus := operator (new in 3.8)

Importing new versions of htslib and samtools

See instructions in import.py to import the latest versions of htslib, samtools and bcftools.

Unit testing

Unit tests are in the tests directory. To run all unit tests, run:

pytest tests

Most tests use test data from the tests/*_data directories. Some of these test data files are generated from other files in these directories, which is done by running make in each directory:

make -C tests/pysam_data
# etc

Alternatively if any tests/*_data/all.stamp file is not already present, running the unit tests should generate that directory’s data files automatically.

Benchmarking

To run the benchmarking suite, make sure that pytest-benchmark is installed. To run all benchmarks, type:

pytest tests/*_bench.py

See Benchmarking for more on this topic.

Contributors

Please see Github for a list of all contributors:

https://github.com/pysam-developers/pysam/graphs/contributors

Many thanks to all contributors for helping in making pysam useful.