Use black to format code; prep docs for RTD

* ./prep_for_commit.sh runs all pre-commit checks now
* CI checks code formatting
* Docs are built more nicely for read-the-docs integration

.github/workflows/python-package.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
     - uses: actions/checkout@v4
@@ -27,14 +27,20 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install flake8 pytest BitVector
+        python -m pip install flake8 pytest BitVector black mypy
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
     - name: Lint with flake8
       run: |
         # stop the build if there are Python syntax errors or undefined names
         flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
         # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
         flake8 . --count --exit-zero --statistics
+    - name: Check formatting
+      run: |
+        black pyigd/ setup.py test/ examples/ --check 
+    - name: Check typing
+      run: |
+        mypy pyigd --no-namespace-packages --ignore-missing-imports
     - name: Test with pytest
       run: |
         PYTHONPATH=$PWD pytest

.gitignore

@@ -3,3 +3,4 @@ __pycache__
 *.swp
 build/
 dist/
+docs/_build/

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "doc/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+    install:
+    - requirements: docs/requirements.txt

docs/conf.py

@@ -6,23 +6,23 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'pyigd'
-copyright = '2024, Drew DeHaas'
-author = 'Drew DeHaas'
-release = '0.2'
+project = "pyigd"
+copyright = "2024, Drew DeHaas"
+author = "Drew DeHaas"
+release = "0.2"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = ["sphinx.ext.autodoc"]
 
-templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docs/index.rst

@@ -10,6 +10,8 @@ pyigd Documentation
    :maxdepth: 2
    :caption: Contents:
 
+   pyigd
+
 pyigd is a Python library for reading and writing Indexable Genotype Data
 (IGD) files. `IGD is a binary format <https://github.com/aprilweilab/picovcf/blob/main/IGD.FORMAT.md>`_ that is very simple and uses no
 compression, but tends to be quite small and fast.

docs/pyigd.rst

@@ -1,8 +1,5 @@
-pyigd package
-=============
-
-Module contents
----------------
+pyigd API
+=========
 
 .. automodule:: pyigd
    :members:

docs/requirements.txt

@@ -0,0 +1 @@
+BitVector

examples/igdread.py

@@ -15,11 +15,13 @@
     print(f"Description: {igd_file.description}")
     for variant_index in range(igd_file.num_variants):
         # Approach 1: Get the samples as a list
-        print(f"REF: {igd_file.get_ref_allele(variant_index)}, ALT: {igd_file.get_alt_allele(variant_index)}")
+        print(
+            f"REF: {igd_file.get_ref_allele(variant_index)}, ALT: {igd_file.get_alt_allele(variant_index)}"
+        )
         position, is_missing, sample_list = igd_file.get_samples(variant_index)
-        print( (position, is_missing, len(sample_list))  )
+        print((position, is_missing, len(sample_list)))
 
         # Approach 2: Get the samples as a BitVector object
         # See https://engineering.purdue.edu/kak/dist/BitVector-3.5.0.html
         position, is_missing, bitvect = igd_file.get_samples_bv(variant_index)
-        print( (position, is_missing, bitvect.count_bits())  )
+        print((position, is_missing, bitvect.count_bits()))

examples/xform.py

@@ -5,14 +5,18 @@
     print("Pass in IGD input/output filenames")
     exit(1)
 
+
 # Our own IGDTransformer. This just deletes the first sample from every variant, but
 # in general you can change the sample list any way you want. Return None to delete
 # the variant entirely.
 class MyXformer(pyigd.IGDTransformer):
     def modify_samples(self, position, is_missing, samples):
         return samples[1:]
 
+
 with open(sys.argv[1], "rb") as fin, open(sys.argv[2], "wb") as fout:
     xformer = MyXformer(fin, fout, use_bitvectors=False)
     xformer.transform()
-print(f"Copied {sys.argv[1]} to {sys.argv[2]} and deleted the first sample from every variant.")
+print(
+    f"Copied {sys.argv[1]} to {sys.argv[2]} and deleted the first sample from every variant."
+)

examples/xform_bv.py

@@ -5,6 +5,7 @@
     print("Pass in IGD input/output filenames")
     exit(1)
 
+
 # Our own IGDTransformer. This just deletes the first sample from every variant, but
 # in general you can change the sample list any way you want. Return None to delete
 # the variant entirely.
@@ -16,7 +17,10 @@ def modify_samples(self, position, is_missing, samples):
                 samples[i] = 0
         return samples
 
+
 with open(sys.argv[1], "rb") as fin, open(sys.argv[2], "wb") as fout:
     xformer = MyXformer(fin, fout, use_bitvectors=True)
     xformer.transform()
-print(f"Copied {sys.argv[1]} to {sys.argv[2]} and deleted the first sample from every variant.")
+print(
+    f"Copied {sys.argv[1]} to {sys.argv[2]} and deleted the first sample from every variant."
+)

prep_for_commit.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+set -ev
+
+flake8 pyigd --count --select=E9,F63,F7,F82,F401 --show-source --statistics
+
+black pyigd/ setup.py test/ examples/ --check 
+
+mypy pyigd --no-namespace-packages --ignore-missing-imports
+
+pytest test/
+