feat: Codebase Improvements - Regression Testing and CI/CD

tests: add testing data for future regression tests (#5)

tests: add shared fixtures + helper function in conftest.py; add __init__.py (#6)

tests: add tests for missing, invalid, or conflicting arguments (ksamuk#7)

tests: add tests for problematic arguments (ksamuk#8)

tests: add tests for warnings and valid `pixy` inputs (ksamuk#9)

respond to reviewer comments; ruff + mypy checks

ci: add`ruff` to environment.yaml; style and lint `pixy` code (ksamuk#15)

chore: Move `pyproject.toml` to top-level (ksamuk#16)

* chore: move pyproject to top level

* chore: ruff format

ci: initial `mypy` on existing `pixy` files (ksamuk#14)

tests: add additional coverage for edge cases (ksamuk#18)

* tests: add new testing data for oddballs and edge cases

* tests: add additional testing conditions (WIP)

* bools should not be optional unless we have a good reason

* style for sites_path variable

feat: Add poetry and fix up GHA issues (ksamuk#28)

This PR adds the usual `poetry` configuration to the pyproject.toml, so
Python dependencies and our static analysis checks can be managed with
`poetry`.

In addition, the following associated changes were made:
- `ruff format` was applied to the codebase
- `ruff check --fix` was applied to the `tests/`module.
- The existing files - `pixy/__main__.py`, `pixy/core.py`, and
`pixy/calc.py` - are **temporarily** excluded from ruff linting.
Upcoming contributions should be added to different files **or** resolve
all existing issues in any updated files in the course of making
changes.
- Python dependencies and `pixy` were removed from the
`environment.yaml`, which is now only used to manage the `samtools`
dependency.
- NB: We should likely refactor to use `pysam` instead of subprocess
calls to the samtools suite, which may end up obviating the need for any
env yaml whatsoever. Would be nice if this could be hosted on pypi
- I added the GHA workflow from our python template
- A few lingering type issues were addressed.
- The GHA workflow was modified to include `conda` and install
samtools/htslib via conda
- A `CONTRIBUTING.md` was added, including development installation
instructions.

chore: rm pycache files (ksamuk#33)

These snuck through before the `.gitignore` was updated

chore: change conda env name (ksamuk#34)

To be consistent with the CONTRIBUTING docs

ci: upgrade `htslib` and `samtools` versions to accomodate wider spread of python versions (ksamuk#35)

.github/workflows/python_package.yml

@@ -0,0 +1,68 @@
+name: Code checks
+
+on: [push]
+
+env:
+  POETRY_VERSION: 1.8.2
+
+jobs:
+  Tests:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        PYTHON_VERSION: ["3.8", "3.9", "3.10", "3.11"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.PYTHON_VERSION }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.PYTHON_VERSION }}
+
+      - name: Set up miniconda and install samtools
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          miniforge-version: latest
+          channels: conda-forge,bioconda
+          activate-environment: pixy-dev
+          auto-activate-base: false
+          environment-file: environment.yaml
+          channel-priority: flexible
+          auto-update-conda: true
+          python-version: ${{ matrix.PYTHON_VERSION }}
+
+      - name: Get full Python version
+        id: full-python-version
+        shell: bash
+        run: echo "version=$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")" >> $GITHUB_OUTPUT
+
+      - name: Install poetry
+        run: |
+          python -m pip install --upgrade pipx
+          pipx install poetry==${{env.POETRY_VERSION}}
+
+      - name: Set up cache
+        uses: actions/cache@v4
+        id: cache
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Ensure cache is healthy
+        if: steps.cache.outputs.cache-hit == 'true'
+        shell: bash
+        run: poetry run pip --version >/dev/null 2>&1 || rm -rf .venv
+
+      - name: Install the library
+        shell: bash -el {0}
+        run: |
+          poetry install -v
+
+      - name: Test the library
+        shell: bash -el {0}
+        run: |
+          poetry run ruff format --check --diff
+          poetry run ruff check
+          poetry run mypy
+          poetry run pytest
+

.gitignore

@@ -8,3 +8,5 @@ data/vcf
 .ipynb_checkpoints/*
 output/*
 docs/_build
+
+__pycache__/

CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Development and Testing
+
+## Installing development version of pixy
+
+Create a fresh conda environment with Python 3.8, install samtools and htslib
+1.9 using the provided `environment.yaml`, and then install `pixy` and its
+Python dependencies with poetry.
+
+```console
+mamba create -n pixy-dev python=3.8
+mamba env update -f environment.yaml
+poetry install
+```
+
+## Primary Development Commands
+
+To check and resolve linting issues in the codebase, run:
+
+```console
+poetry run ruff check --fix
+```
+
+To check and resolve formatting issues in the codebase, run:
+
+```console
+poetry run ruff format
+```
+
+To check the unit tests in the codebase, run:
+
+```console
+poetry run pytest
+```
+
+To check the typing in the codebase, run:
+
+```console
+poetry run mypy
+```
+
+To generate a code coverage report after testing locally, run:
+
+```console
+poetry run coverage html
+```
+
+To check the lock file is up to date:
+
+```console
+poetry check --lock
+```
+
+## Shortcut Task Commands
+
+To be able to run shortcut task commands, first install the Poetry plugin [`poethepoet`](https://poethepoet.natn.io/index.html):
+
+```console
+poetry self add 'poethepoet[poetry_plugin]'
+```
+
+> [!NOTE]
+> Upon the release of Poetry [v2.0.0](https://github.com/orgs/python-poetry/discussions/9793#discussioncomment-11043205), Poetry will automatically support bootstrap installation of [project-specific plugins](https://github.com/python-poetry/poetry/pull/9547) and installation of the task runner will become automatic for this project.
+> The `pyproject.toml` syntax will be:
+> 
+> ```toml
+> [tool.poetry]
+> requires-poetry = ">=2.0"
+> 
+> [tool.poetry.requires-plugins]
+> poethepoet = ">=0.29"
+> ```
+
+###### For Running Individual Checks
+
+```console
+poetry task check-lock
+poetry task check-format
+poetry task check-lint
+poetry task check-tests
+poetry task check-typing
+```
+
+###### For Running All Checks
+
+```console
+poetry task check-all
+```
+
+###### For Running Individual Fixes
+
+```console
+poetry task fix-format
+poetry task fix-lint
+```
+
+###### For Running All Fixes
+
+```console
+poetry task fix-all
+```
+
+###### For Running All Fixes and Checks
+
+```console
+poetry task fix-and-check-all
+```

docs/conf.py

@@ -19,14 +19,14 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'pixy'
-copyright = '2019, Kieran Samuk, Katharine Korunes'
-author = 'Kieran Samuk, Katharine Korunes'
+project = "pixy"
+copyright = "2019, Kieran Samuk, Katharine Korunes"
+author = "Kieran Samuk, Katharine Korunes"
 
 # The short X.Y version
-version = ''
+version = ""
 # The full version, including alpha/beta/rc tags
-release = ''
+release = ""
 
 
 # -- General configuration ---------------------------------------------------
@@ -38,20 +38,19 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-]
+extensions = []
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -63,7 +62,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
@@ -77,7 +76,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -88,12 +87,12 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 # These paths are either relative to html_static_path
 # or fully qualified paths (eg. https://...)
 html_css_files = [
-    'css/custom.css',
+    "css/custom.css",
 ]
 
 # Custom sidebar templates, must be a dictionary that maps document names
@@ -110,7 +109,7 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'pixydoc'
+htmlhelp_basename = "pixydoc"
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -119,15 +118,12 @@
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -137,19 +133,21 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'pixy.tex', 'pixy Documentation',
-     'Kieran Samuk, Katharine Korunes', 'manual'),
+    (
+        master_doc,
+        "pixy.tex",
+        "pixy Documentation",
+        "Kieran Samuk, Katharine Korunes",
+        "manual",
+    ),
 ]
 
 
 # -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'pixy', 'pixy Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, "pixy", "pixy Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output ----------------------------------------------
@@ -158,9 +156,15 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'pixy', 'pixy Documentation',
-     author, 'pixy', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "pixy",
+        "pixy Documentation",
+        author,
+        "pixy",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]
 
 
@@ -179,4 +183,4 @@
 # epub_uid = ''
 
 # A list of files that should not be packed into the epub file.
-epub_exclude_files = ['search.html']
+epub_exclude_files = ["search.html"]

environment.yaml

@@ -0,0 +1,8 @@
+name: pixy-dev
+channels:
+  - bioconda
+  - conda-forge
+dependencies:
+  - bioconda::htslib=1.21
+  - bioconda::samtools=1.21
+