samplesheet-parser 1.3.0__tar.gz → 2.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/.github/workflows/ci.yml +2 -3
  2. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/.pre-commit-config.yaml +6 -2
  3. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/.zenodo.json +1 -1
  4. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/CHANGELOG.md +114 -0
  5. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/CITATION.cff +2 -2
  6. samplesheet_parser-2.1.0/Makefile +81 -0
  7. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/PKG-INFO +48 -17
  8. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/README.md +43 -14
  9. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/api.md +41 -3
  10. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/parsing.md +31 -2
  11. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/validation.md +8 -4
  12. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/index.md +1 -1
  13. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/installation.md +2 -2
  14. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/convert/environment.yml +1 -1
  15. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/convert/main.nf +4 -14
  16. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/convert/meta.yml +31 -15
  17. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +10 -10
  18. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/diff/environment.yml +1 -1
  19. samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/diff/main.nf +34 -0
  20. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/diff/meta.yml +28 -13
  21. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test +10 -10
  22. samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/diff/tests/main.nf.test.snap +80 -0
  23. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/filter/environment.yml +1 -1
  24. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/filter/main.nf +5 -15
  25. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/filter/meta.yml +32 -15
  26. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/filter/tests/main.nf.test +5 -5
  27. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/info/environment.yml +1 -1
  28. samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/info/main.nf +34 -0
  29. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/info/meta.yml +28 -13
  30. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test +7 -7
  31. samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/info/tests/main.nf.test.snap +80 -0
  32. samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/merge/environment.yml +6 -0
  33. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/merge/main.nf +5 -15
  34. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/merge/meta.yml +32 -15
  35. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/merge/tests/main.nf.test +10 -10
  36. samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/split/environment.yml +6 -0
  37. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/split/main.nf +5 -15
  38. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/split/meta.yml +32 -15
  39. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/split/tests/main.nf.test +7 -7
  40. samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/validate/environment.yml +6 -0
  41. samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/validate/main.nf +34 -0
  42. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/validate/meta.yml +28 -13
  43. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +7 -7
  44. samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/validate/tests/main.nf.test.snap +80 -0
  45. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/pyproject.toml +15 -8
  46. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/__init__.py +12 -3
  47. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/cli.py +7 -5
  48. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/converter.py +18 -13
  49. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/diff.py +56 -55
  50. samplesheet_parser-2.1.0/samplesheet_parser/enums.py +55 -0
  51. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/factory.py +106 -30
  52. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/filter.py +6 -5
  53. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/index_utils.py +3 -3
  54. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/instruments.py +40 -9
  55. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/merger.py +30 -29
  56. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/parsers/v1.py +97 -101
  57. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/parsers/v2.py +245 -168
  58. samplesheet_parser-2.1.0/samplesheet_parser/protocol.py +102 -0
  59. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/splitter.py +6 -5
  60. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/validators.py +135 -72
  61. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/writer.py +14 -12
  62. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/conftest.py +2 -2
  63. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_cli.py +6 -6
  64. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_converter.py +4 -4
  65. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_diff.py +101 -41
  66. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_factory.py +72 -4
  67. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_filter.py +11 -11
  68. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_index_utils.py +7 -3
  69. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_instruments.py +1 -1
  70. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_merger.py +111 -84
  71. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_parsers/test_v1.py +25 -28
  72. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_parsers/test_v2.py +51 -24
  73. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_splitter.py +11 -11
  74. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_validators/test_hamming.py +289 -85
  75. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_validators/test_validators.py +39 -11
  76. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_writer.py +23 -8
  77. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/convert/tests/tags.yml +0 -4
  78. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/main.nf +0 -45
  79. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/tests/tags.yml +0 -4
  80. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/tests/tags.yml +0 -4
  81. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/main.nf +0 -45
  82. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/tests/tags.yml +0 -4
  83. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/environment.yml +0 -6
  84. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/tests/tags.yml +0 -4
  85. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/environment.yml +0 -6
  86. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/tests/tags.yml +0 -4
  87. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/environment.yml +0 -6
  88. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/main.nf +0 -45
  89. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/tests/tags.yml +0 -4
  90. samplesheet_parser-1.3.0/samplesheet_parser/enums.py +0 -51
  91. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/.github/workflows/copilot-instructions.md +0 -0
  92. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/.gitignore +0 -0
  93. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/.readthedocs.yaml +0 -0
  94. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/CONTRIBUTING.md +0 -0
  95. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/LICENSE +0 -0
  96. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/changelog.md +0 -0
  97. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/ci.md +0 -0
  98. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/cli.md +0 -0
  99. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/contributing.md +0 -0
  100. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/examples.md +0 -0
  101. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/conversion.md +0 -0
  102. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/diffing.md +0 -0
  103. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/filtering.md +0 -0
  104. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/index_utils.md +0 -0
  105. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/merging.md +0 -0
  106. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/quickstart.md +0 -0
  107. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/splitting.md +0 -0
  108. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/writing.md +0 -0
  109. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/requirements.txt +0 -0
  110. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_converter.py +0 -0
  111. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_diff.py +0 -0
  112. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_filter.py +0 -0
  113. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_index_utils.py +0 -0
  114. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_merger.py +0 -0
  115. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_splitter.py +0 -0
  116. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_writer.py +0 -0
  117. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/parse_examples.py +0 -0
  118. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
  119. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
  120. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
  121. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
  122. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/README.md +0 -0
  123. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/combined_clean.csv +0 -0
  124. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
  125. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
  126. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
  127. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
  128. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v1_single_index.csv +0 -0
  129. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
  130. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
  131. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
  132. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
  133. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
  134. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
  135. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
  136. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
  137. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/images/samplesheet_parser_arch_v03.png +0 -0
  138. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/images/samplesheet_parser_overview.png +0 -0
  139. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/mkdocs.yml +0 -0
  140. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/filter/tests/nextflow.config +0 -0
  141. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/recipes/meta.yaml +0 -0
  142. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/parsers/__init__.py +0 -0
  143. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/py.typed +0 -0
  144. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/scripts/demo_converter.py +0 -0
  145. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/scripts/demo_diff.py +0 -0
  146. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/scripts/demo_writer.py +0 -0
  147. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/__init__.py +0 -0
  148. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
  149. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
  150. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
  151. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_parsers/__init__.py +0 -0
  152. {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_validators/__init__.py +0 -0
@@ -30,11 +30,10 @@ jobs:
30
30
  run: ruff check samplesheet_parser/
31
31
 
32
32
  - name: Type check with mypy
33
- run: mypy samplesheet_parser/ --ignore-missing-imports
34
- continue-on-error: true
33
+ run: mypy samplesheet_parser/ --strict --ignore-missing-imports
35
34
 
36
35
  - name: Run tests
37
- run: pytest tests/ -v --cov=samplesheet_parser --cov-report=xml
36
+ run: pytest tests/ -v -W error::DeprecationWarning --cov=samplesheet_parser --cov-report=xml
38
37
 
39
38
  - name: Upload coverage to Codecov
40
39
  uses: codecov/codecov-action@v4
@@ -26,5 +26,9 @@ repos:
26
26
  rev: v1.13.0
27
27
  hooks:
28
28
  - id: mypy
29
- additional_dependencies: [loguru, typer]
30
- args: [--ignore-missing-imports]
29
+ additional_dependencies: [typer]
30
+ # Type-check the package only, matching CI. Tests are intentionally
31
+ # exempt (see the tests.* override in pyproject.toml); passing
32
+ # individual test file paths here would bypass that override.
33
+ pass_filenames: false
34
+ args: [--strict, --ignore-missing-imports, samplesheet_parser/]
@@ -4,7 +4,7 @@
4
4
  "upload_type": "software",
5
5
  "access_right": "open",
6
6
  "license": "Apache-2.0",
7
- "version": "1.1.0",
7
+ "version": "2.1.0",
8
8
  "keywords": [
9
9
  "bioinformatics", "Illumina", "SampleSheet", "BCLConvert",
10
10
  "demultiplexing", "genomics", "sequencing", "Python"
@@ -8,6 +8,120 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
8
8
 
9
9
  ## [Unreleased]
10
10
 
11
+ _No unreleased changes._
12
+
13
+ ## [2.1.0] - 2026-06-09
14
+
15
+ ### Fixed
16
+
17
+ - **Format auto-detection now scans the whole file.** The V2 fallback that
18
+ looks for `[BCLConvert_Settings]` / `[BCLConvert_Data]` previously stopped
19
+ reading at the first section after `[Header]`, so a V2 sheet that lacked
20
+ `FileFormatVersion` and placed those sections after `[Reads]` was misdetected
21
+ as V1. Detection now reads the full file (sheets are small) before falling
22
+ back, and matches the BCLConvert section names case-insensitively so a sheet
23
+ using e.g. `[bclconvert_data]` is detected as V2.
24
+ - **Index-free libraries no longer raise `DUPLICATE_INDEX`.** A full-lane
25
+ library where every sample has an empty index was incorrectly flagged as a
26
+ duplicate. Samples with no index are now skipped in the duplicate-index
27
+ check.
28
+ - **Duplicate-index detection is now case-insensitive.** Indexes are
29
+ upper-cased before comparison, so the same barcode written with different
30
+ casing is correctly flagged as a duplicate, consistent with the index
31
+ distance and character checks.
32
+ - **`mypy --strict` passes again.** The `info` CLI command accessed
33
+ V2-only attributes on the parser protocol without narrowing; it now narrows
34
+ with `isinstance`.
35
+ - **CLI no longer emits Typer deprecation warnings.** Removed the deprecated
36
+ `is_flag=True` from the `--version` option, clearing the warnings that were
37
+ raised on every CLI invocation.
38
+
39
+ ### Changed
40
+
41
+ - **Index distance checking is now a sum of per-index distances.** For dual
42
+ index sheets the validator adds the I7 mismatch count to the I5 mismatch
43
+ count instead of comparing the two indexes concatenated into one string.
44
+ The result is the same for uniform-length indexes but correct when samples
45
+ use different index lengths, and it keeps I7 and I5 positions aligned. The
46
+ `INDEX_DISTANCE_TOO_LOW` message now refers to a "combined distance" and the
47
+ `index_a` / `index_b` context values use an `I7+I5` separator.
48
+ - **`N` is treated as a wildcard in collision detection.** Index distance
49
+ checks now treat an `N` cycle as matching any base, so two indexes that
50
+ differ only at an `N` are reported as colliding. The pure `hamming_distance`
51
+ helper is unchanged.
52
+
53
+ ### Added
54
+
55
+ - **`index_collision_distance(a, b)`** public helper: the wildcard-aware,
56
+ per-index distance the validator uses for collision detection.
57
+
58
+ ### Documentation
59
+
60
+ - Formalised the `OverrideCycles` grammar in `SampleSheetV2._parse_override_cycles`,
61
+ documented how a `U` token is attributed to an index versus a read, clarified
62
+ that `umi_length` is the largest single UMI segment (not the sum), and made
63
+ malformed segments log a warning and decode on a best-effort basis instead of
64
+ being silently dropped.
65
+
66
+ ---
67
+
68
+ ## [2.0.0] - 2026-06-06
69
+
70
+ ### Breaking changes
71
+
72
+ - **Python 3.10+ required** (was 3.12+). The `str, Enum` mixin replaces
73
+ `StrEnum` throughout `enums.py` and `instruments.py`, giving identical
74
+ behaviour on all supported versions.
75
+ - **`loguru` dependency removed.** The library now uses `logging.getLogger(__name__)`
76
+ in every module. Host applications retain full control of log configuration.
77
+ If you previously relied on `loguru` sinks seeing library log output, wire up
78
+ a standard `logging` handler instead.
79
+ - **`clean()` now returns the cleaned content as a `str` and never writes to
80
+ disk.** Previously `SampleSheetV1.clean()` and `SampleSheetV2.clean()` wrote
81
+ to the source file and created a `.backup` alongside it. The source file is
82
+ now untouched; the cleaned string is passed in-memory to `read()`. Callers
83
+ that relied on the side-effect (file written, `.backup` created) must adapt.
84
+ - **`samples()` deduplication key changed from `sample_id` to `(sample_id, lane)`.**
85
+ Multi-lane sheets where the same sample appears in multiple lanes now return
86
+ one record *per lane* rather than silently dropping all but the first row.
87
+ - **`SampleSheetFactory.create_parser()` return type is now `SampleSheetParser`**
88
+ (the new Protocol) rather than `SampleSheetV1 | SampleSheetV2`. Both concrete
89
+ types structurally satisfy the Protocol; the change only affects code with
90
+ explicit type annotations on the return value.
91
+ - **`_hamming_distance` renamed to `hamming_distance`** (underscore removed).
92
+ Import path: `from samplesheet_parser import hamming_distance` or
93
+ `from samplesheet_parser.validators import hamming_distance`.
94
+
95
+ ### Fixed
96
+
97
+ - **V2 `parse_data()` no longer silently drops keys with empty-string values.**
98
+ The `{k: v for k, v in ... if v}` filter was removing keys whose value was
99
+ `""`, making V2 record dicts structurally inconsistent with V1. All keys are
100
+ now preserved; values are stripped of surrounding whitespace only.
101
+ - **`converter.to_v1()` bare `assert` replaced with explicit `TypeError`.**
102
+ `assert isinstance(sheet, SampleSheetV2)` is stripped by `python -O`; the
103
+ guard now raises `TypeError` unconditionally when the wrong type is passed.
104
+
105
+ ### Added
106
+
107
+ - **`SampleSheetParser` Protocol** (`samplesheet_parser.protocol`) — a
108
+ `runtime_checkable` structural protocol satisfied by both `SampleSheetV1`
109
+ and `SampleSheetV2`. Third-party parsers that implement the same interface
110
+ can be registered with the factory without inheriting from any base class.
111
+ `isinstance(sheet, SampleSheetParser)` works at runtime.
112
+ - **`SampleSheetFactory.register(detector, parser_class, version)`** — class
113
+ method that registers a custom format detector. Registered detectors are
114
+ tried before the built-in V1/V2 detection in LIFO order. Useful for
115
+ supporting hypothetical V3 formats or vendor-specific variants.
116
+ - **`SampleSheetFactory.clear_registry()`** — removes all custom registrations.
117
+ Intended for use in tests to prevent cross-test contamination.
118
+ - **`detect_workflow()` accepts `extra_a` / `extra_b` keyword arguments** —
119
+ caller-supplied `frozenset[str]` of instrument names checked before the
120
+ built-in tables. Allows narrowing workflow classification without subclassing.
121
+ - **`hamming_distance` is now a public export** — available as
122
+ `from samplesheet_parser import hamming_distance` and documented in the API
123
+ reference.
124
+
11
125
  ---
12
126
 
13
127
  ## [1.3.0] - 2026-05-20
@@ -8,8 +8,8 @@ abstract: >
8
8
  Provides format auto-detection, bidirectional V1/V2 conversion,
9
9
  structural and index validation, sheet diffing, and cross-project
10
10
  merging with Hamming-distance collision detection.
11
- version: 1.3.0
12
- date-released: 2026-05-20
11
+ version: 2.1.0
12
+ date-released: 2026-06-09
13
13
  license: Apache-2.0
14
14
  url: "https://github.com/chaitanyakasaraneni/samplesheet-parser"
15
15
  repository-code: "https://github.com/chaitanyakasaraneni/samplesheet-parser"
@@ -0,0 +1,81 @@
1
+ # Makefile for samplesheet-parser
2
+ # Keeps the version in sync across pyproject.toml, CITATION.cff, and .zenodo.json.
3
+ # Portable to GNU Make 3.81 (macOS default) — recipes are single POSIX-sh lines.
4
+
5
+ PKG := samplesheet_parser
6
+ PYPROJECT := pyproject.toml
7
+ CITATION := CITATION.cff
8
+ ZENODO := .zenodo.json
9
+ CHANGELOG := CHANGELOG.md
10
+
11
+ CURRENT_VERSION := $(shell sed -n -E 's/^version = "([0-9]+\.[0-9]+\.[0-9]+)".*/\1/p' $(PYPROJECT) | head -1)
12
+
13
+ .DEFAULT_GOAL := help
14
+ .PHONY: help version major minor patch tag test lint build clean
15
+
16
+ help:
17
+ @echo "samplesheet-parser — current version: $(CURRENT_VERSION)"
18
+ @echo ""
19
+ @echo "Version bumping (syncs $(PYPROJECT), $(CITATION), $(ZENODO); rolls $(CHANGELOG)):"
20
+ @echo " make patch patch bump (x.y.Z)"
21
+ @echo " make minor minor bump (x.Y.0)"
22
+ @echo " make major major bump (X.0.0)"
23
+ @echo ""
24
+ @echo "Other targets:"
25
+ @echo " make version print the current version"
26
+ @echo " make tag create git tag v$(CURRENT_VERSION)"
27
+ @echo " make test run pytest"
28
+ @echo " make lint run ruff"
29
+ @echo " make build build sdist + wheel"
30
+ @echo " make clean remove build artifacts"
31
+
32
+ version:
33
+ @echo $(CURRENT_VERSION)
34
+
35
+ patch minor major:
36
+ @$(MAKE) --no-print-directory _bump PART=$@
37
+
38
+ # internal: bump the version part named by PART across all files (one shell line)
39
+ _bump:
40
+ @cur="$(CURRENT_VERSION)"; \
41
+ [ -n "$$cur" ] || { echo "error: could not read version from $(PYPROJECT)"; exit 1; }; \
42
+ MA=$${cur%%.*}; rest=$${cur#*.}; MI=$${rest%%.*}; PA=$${rest##*.}; \
43
+ case "$(PART)" in \
44
+ major) MA=$$((MA + 1)); MI=0; PA=0 ;; \
45
+ minor) MI=$$((MI + 1)); PA=0 ;; \
46
+ patch) PA=$$((PA + 1)) ;; \
47
+ *) echo "error: unknown bump part '$(PART)'"; exit 1 ;; \
48
+ esac; \
49
+ new="$$MA.$$MI.$$PA"; today="$$(date +%F)"; \
50
+ sed -E 's/^version = "[0-9]+\.[0-9]+\.[0-9]+"/version = "'"$$new"'"/' $(PYPROJECT) > $(PYPROJECT).tmp && mv $(PYPROJECT).tmp $(PYPROJECT); \
51
+ sed -E -e 's/^version: .*/version: '"$$new"'/' -e 's/^date-released: .*/date-released: '"$$today"'/' $(CITATION) > $(CITATION).tmp && mv $(CITATION).tmp $(CITATION); \
52
+ sed -E 's/("version": )"[0-9]+\.[0-9]+\.[0-9]+"/\1"'"$$new"'"/' $(ZENODO) > $(ZENODO).tmp && mv $(ZENODO).tmp $(ZENODO); \
53
+ cl_note=""; \
54
+ if [ -f $(CHANGELOG) ] && grep -q '^## \[Unreleased\]' $(CHANGELOG); then \
55
+ awk -v v="$$new" -v d="$$today" '!done && /^## \[Unreleased\]/ {print "## [Unreleased]"; print ""; print "_No unreleased changes._"; print ""; print "## [" v "] - " d; done=1; next} {print}' $(CHANGELOG) > $(CHANGELOG).tmp && mv $(CHANGELOG).tmp $(CHANGELOG); \
56
+ cl_note=", $(CHANGELOG)"; \
57
+ else \
58
+ cl_note=" (warning: no [Unreleased] section in $(CHANGELOG) — not rolled)"; \
59
+ fi; \
60
+ echo "Bumped $$cur -> $$new (date-released: $$today)"; \
61
+ echo " updated: $(PYPROJECT), $(CITATION), $(ZENODO)$$cl_note"; \
62
+ echo "Next: review $(CHANGELOG), then: git commit -am \"release v$$new\" && make tag && git push --follow-tags"
63
+
64
+ tag:
65
+ @v="$(CURRENT_VERSION)"; \
66
+ if git rev-parse "v$$v" >/dev/null 2>&1; then echo "tag v$$v already exists"; exit 1; fi; \
67
+ git tag -a "v$$v" -m "Release v$$v"; \
68
+ echo "created annotated tag v$$v (push with: git push --follow-tags)"
69
+
70
+ test:
71
+ @pytest
72
+
73
+ lint:
74
+ @ruff check $(PKG)/
75
+
76
+ build:
77
+ @python3 -m hatchling build
78
+
79
+ clean:
80
+ @rm -rf dist build *.egg-info
81
+ @find . -type d -name __pycache__ -prune -exec rm -rf {} +
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: samplesheet-parser
3
- Version: 1.3.0
3
+ Version: 2.1.0
4
4
  Summary: Format-agnostic parser for Illumina SampleSheet.csv files — supports IEM V1 and BCLConvert V2
5
5
  Project-URL: Homepage, https://github.com/chaitanyakasaraneni/samplesheet-parser
6
6
  Project-URL: Documentation, https://illumina-samplesheet.readthedocs.io
@@ -33,11 +33,13 @@ Classifier: Intended Audience :: Developers
33
33
  Classifier: Intended Audience :: Science/Research
34
34
  Classifier: License :: OSI Approved :: Apache Software License
35
35
  Classifier: Programming Language :: Python :: 3
36
+ Classifier: Programming Language :: Python :: 3.10
37
+ Classifier: Programming Language :: Python :: 3.11
36
38
  Classifier: Programming Language :: Python :: 3.12
39
+ Classifier: Programming Language :: Python :: 3.13
37
40
  Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
38
41
  Classifier: Typing :: Typed
39
- Requires-Python: >=3.12
40
- Requires-Dist: loguru>=0.7
42
+ Requires-Python: >=3.10
41
43
  Provides-Extra: cli
42
44
  Requires-Dist: typer>=0.12; extra == 'cli'
43
45
  Provides-Extra: dev
@@ -59,7 +61,7 @@ Description-Content-Type: text/markdown
59
61
  Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, diff comparison, multi-sheet merging, programmatic sheet creation, and a full-featured CLI.
60
62
 
61
63
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
62
- [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
64
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
63
65
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)
64
66
  [![Install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/samplesheet-parser/README.html)
65
67
 
@@ -94,7 +96,7 @@ pip install samplesheet-parser
94
96
  pip install "samplesheet-parser[cli]"
95
97
  ```
96
98
 
97
- Requires Python 3.12+. No mandatory runtime dependencies beyond `loguru`.
99
+ Requires Python 3.10+. No mandatory runtime dependencies.
98
100
 
99
101
  ---
100
102
 
@@ -367,20 +369,27 @@ The detector reads only as much of the file as needed — stopping after `[Heade
367
369
  | `NO_ADAPTERS` | warning | No adapter sequences configured |
368
370
  | `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
369
371
 
370
- ### Hamming distance checking
372
+ ### Index distance checking
371
373
 
372
374
  Indexes that are too similar cause read bleed-through between samples during
373
- demultiplexing — a common cause of low-quality runs that is not caught by a
374
- simple duplicate check. The validator computes the Hamming distance between
375
- every pair of indexes within each lane and warns when the distance falls below
376
- the recommended minimum of 3.
377
-
378
- For dual-index sheets, the I7 and I5 sequences are combined before comparison,
379
- so a pair that is close on I7 but well-separated on I5 (as most dual-index
380
- kits are designed) is not incorrectly flagged.
375
+ demultiplexing, a common cause of low-quality runs that a simple duplicate
376
+ check does not catch. For every pair of samples within a lane the validator
377
+ computes a combined distance and warns when it falls below the recommended
378
+ minimum of 3.
379
+
380
+ For dual-index sheets the combined distance is the sum of the per-index
381
+ mismatch counts: the I7 distance plus the I5 distance. This equals the minimum
382
+ number of sequencing errors needed to read one sample's barcodes as another's
383
+ across both index reads, and summing per index (rather than concatenating the
384
+ two indexes into one string) keeps the I7 and I5 positions aligned even when
385
+ samples use different index lengths. So a pair that is close on I7 but
386
+ well-separated on I5, as most dual-index kits are designed, is not flagged.
387
+
388
+ Each per-index distance treats an `N` cycle as a wildcard that matches any
389
+ base, so two indexes that differ only at an `N` are reported as colliding.
381
390
 
382
391
  ```python
383
- # Custom threshold — stricter than the default of 3
392
+ # Custom threshold: stricter than the default of 3
384
393
  from samplesheet_parser.validators import SampleSheetValidator, ValidationResult
385
394
 
386
395
  samples = sheet.samples()
@@ -464,10 +473,21 @@ sheet.get_read_structure() # → ReadStructure dataclass
464
473
 
465
474
  | Method / attribute | Returns | Description |
466
475
  |---|---|---|
467
- | `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetV1 \| SampleSheetV2` | Auto-detect format and return appropriate parser |
476
+ | `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetParser` | Auto-detect format and return appropriate parser |
477
+ | `register(detector, parser_class, version)` | `None` | Register a custom format detector (class method, LIFO) |
478
+ | `clear_registry()` | `None` | Remove all custom registrations (class method) |
468
479
  | `get_umi_length()` | `int` | UMI length from the current parser |
469
480
  | `.version` | `SampleSheetVersion` | Detected format version |
470
481
 
482
+ ### `SampleSheetParser` (Protocol)
483
+
484
+ A `runtime_checkable` structural protocol satisfied by both `SampleSheetV1` and `SampleSheetV2`. Third-party parsers that implement the same methods and attributes can be registered with `SampleSheetFactory.register()` without inheriting from any base class.
485
+
486
+ ```python
487
+ from samplesheet_parser import SampleSheetParser, SampleSheetV1
488
+ assert isinstance(SampleSheetV1("sheet.csv"), SampleSheetParser)
489
+ ```
490
+
471
491
  ### `SampleSheetV1` / `SampleSheetV2` (shared interface)
472
492
 
473
493
  | Method / attribute | Returns | Description |
@@ -498,6 +518,17 @@ sheet.get_read_structure() # → ReadStructure dataclass
498
518
  | `validate(sheet)` | `ValidationResult` | Run all checks; returns structured result |
499
519
  | `_check_index_distances(samples, result, min_distance=3)` | `None` | Hamming distance check (callable directly for custom thresholds) |
500
520
 
521
+ ### `hamming_distance`
522
+
523
+ ```python
524
+ from samplesheet_parser import hamming_distance
525
+
526
+ hamming_distance("ATTACTCG", "ATTACTCA") # → 1
527
+ hamming_distance("ATTACTCG", "GCTAGCTA") # → 6
528
+ ```
529
+
530
+ Public helper for computing the Hamming distance between two index sequences. Sequences of unequal length are compared up to the shorter length.
531
+
501
532
  ### `SampleSheetWriter`
502
533
 
503
534
  | Method / attribute | Returns | Description |
@@ -593,7 +624,7 @@ jobs:
593
624
 
594
625
  - uses: actions/setup-python@v5
595
626
  with:
596
- python-version: '3.12'
627
+ python-version: '3.10'
597
628
 
598
629
  - run: pip install "samplesheet-parser[cli]"
599
630
 
@@ -5,7 +5,7 @@
5
5
  Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, diff comparison, multi-sheet merging, programmatic sheet creation, and a full-featured CLI.
6
6
 
7
7
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
8
- [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
8
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
9
9
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)
10
10
  [![Install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/samplesheet-parser/README.html)
11
11
 
@@ -40,7 +40,7 @@ pip install samplesheet-parser
40
40
  pip install "samplesheet-parser[cli]"
41
41
  ```
42
42
 
43
- Requires Python 3.12+. No mandatory runtime dependencies beyond `loguru`.
43
+ Requires Python 3.10+. No mandatory runtime dependencies.
44
44
 
45
45
  ---
46
46
 
@@ -313,20 +313,27 @@ The detector reads only as much of the file as needed — stopping after `[Heade
313
313
  | `NO_ADAPTERS` | warning | No adapter sequences configured |
314
314
  | `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
315
315
 
316
- ### Hamming distance checking
316
+ ### Index distance checking
317
317
 
318
318
  Indexes that are too similar cause read bleed-through between samples during
319
- demultiplexing — a common cause of low-quality runs that is not caught by a
320
- simple duplicate check. The validator computes the Hamming distance between
321
- every pair of indexes within each lane and warns when the distance falls below
322
- the recommended minimum of 3.
323
-
324
- For dual-index sheets, the I7 and I5 sequences are combined before comparison,
325
- so a pair that is close on I7 but well-separated on I5 (as most dual-index
326
- kits are designed) is not incorrectly flagged.
319
+ demultiplexing, a common cause of low-quality runs that a simple duplicate
320
+ check does not catch. For every pair of samples within a lane the validator
321
+ computes a combined distance and warns when it falls below the recommended
322
+ minimum of 3.
323
+
324
+ For dual-index sheets the combined distance is the sum of the per-index
325
+ mismatch counts: the I7 distance plus the I5 distance. This equals the minimum
326
+ number of sequencing errors needed to read one sample's barcodes as another's
327
+ across both index reads, and summing per index (rather than concatenating the
328
+ two indexes into one string) keeps the I7 and I5 positions aligned even when
329
+ samples use different index lengths. So a pair that is close on I7 but
330
+ well-separated on I5, as most dual-index kits are designed, is not flagged.
331
+
332
+ Each per-index distance treats an `N` cycle as a wildcard that matches any
333
+ base, so two indexes that differ only at an `N` are reported as colliding.
327
334
 
328
335
  ```python
329
- # Custom threshold — stricter than the default of 3
336
+ # Custom threshold: stricter than the default of 3
330
337
  from samplesheet_parser.validators import SampleSheetValidator, ValidationResult
331
338
 
332
339
  samples = sheet.samples()
@@ -410,10 +417,21 @@ sheet.get_read_structure() # → ReadStructure dataclass
410
417
 
411
418
  | Method / attribute | Returns | Description |
412
419
  |---|---|---|
413
- | `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetV1 \| SampleSheetV2` | Auto-detect format and return appropriate parser |
420
+ | `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetParser` | Auto-detect format and return appropriate parser |
421
+ | `register(detector, parser_class, version)` | `None` | Register a custom format detector (class method, LIFO) |
422
+ | `clear_registry()` | `None` | Remove all custom registrations (class method) |
414
423
  | `get_umi_length()` | `int` | UMI length from the current parser |
415
424
  | `.version` | `SampleSheetVersion` | Detected format version |
416
425
 
426
+ ### `SampleSheetParser` (Protocol)
427
+
428
+ A `runtime_checkable` structural protocol satisfied by both `SampleSheetV1` and `SampleSheetV2`. Third-party parsers that implement the same methods and attributes can be registered with `SampleSheetFactory.register()` without inheriting from any base class.
429
+
430
+ ```python
431
+ from samplesheet_parser import SampleSheetParser, SampleSheetV1
432
+ assert isinstance(SampleSheetV1("sheet.csv"), SampleSheetParser)
433
+ ```
434
+
417
435
  ### `SampleSheetV1` / `SampleSheetV2` (shared interface)
418
436
 
419
437
  | Method / attribute | Returns | Description |
@@ -444,6 +462,17 @@ sheet.get_read_structure() # → ReadStructure dataclass
444
462
  | `validate(sheet)` | `ValidationResult` | Run all checks; returns structured result |
445
463
  | `_check_index_distances(samples, result, min_distance=3)` | `None` | Hamming distance check (callable directly for custom thresholds) |
446
464
 
465
+ ### `hamming_distance`
466
+
467
+ ```python
468
+ from samplesheet_parser import hamming_distance
469
+
470
+ hamming_distance("ATTACTCG", "ATTACTCA") # → 1
471
+ hamming_distance("ATTACTCG", "GCTAGCTA") # → 6
472
+ ```
473
+
474
+ Public helper for computing the Hamming distance between two index sequences. Sequences of unequal length are compared up to the shorter length.
475
+
447
476
  ### `SampleSheetWriter`
448
477
 
449
478
  | Method / attribute | Returns | Description |
@@ -539,7 +568,7 @@ jobs:
539
568
 
540
569
  - uses: actions/setup-python@v5
541
570
  with:
542
- python-version: '3.12'
571
+ python-version: '3.10'
543
572
 
544
573
  - run: pip install "samplesheet-parser[cli]"
545
574
 
@@ -5,6 +5,7 @@ All public classes are importable directly from the top-level package:
5
5
  ```python
6
6
  from samplesheet_parser import (
7
7
  SampleSheetFactory,
8
+ SampleSheetParser,
8
9
  SampleSheetV1,
9
10
  SampleSheetV2,
10
11
  SampleSheetConverter,
@@ -15,6 +16,7 @@ from samplesheet_parser import (
15
16
  SampleSheetSplitter,
16
17
  SampleSheetFilter,
17
18
  normalize_index_lengths,
19
+ hamming_distance,
18
20
  )
19
21
  ```
20
22
 
@@ -24,19 +26,37 @@ from samplesheet_parser import (
24
26
 
25
27
  | Method / attribute | Returns | Description |
26
28
  |---|---|---|
27
- | `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetV1 \| SampleSheetV2` | Auto-detect format and return the appropriate parser |
29
+ | `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetParser` | Auto-detect format and return the appropriate parser |
28
30
  | `get_umi_length()` | `int` | UMI length from the current parser |
31
+ | `register(detector, parser_class, version)` | `None` | Register a custom format detector; tried before built-in detection in LIFO order |
32
+ | `clear_registry()` | `None` | Remove all custom registrations (useful in tests) |
29
33
  | `.version` | `SampleSheetVersion \| None` | Detected format version |
30
34
 
31
35
  ---
32
36
 
37
+ ## SampleSheetParser Protocol
38
+
39
+ `SampleSheetParser` is a `runtime_checkable` structural protocol satisfied by both `SampleSheetV1` and `SampleSheetV2`. Use it as a type hint wherever either parser is accepted, or implement it in a third-party parser and register it with the factory.
40
+
41
+ ```python
42
+ from samplesheet_parser import SampleSheetParser
43
+
44
+ isinstance(sheet, SampleSheetParser) # True for V1 and V2 instances
45
+ ```
46
+
47
+ ---
48
+
33
49
  ## SampleSheetV1 / SampleSheetV2 (shared interface)
34
50
 
51
+ Both parsers satisfy `SampleSheetParser` and expose:
52
+
35
53
  | Method / attribute | Returns | Description |
36
54
  |---|---|---|
37
55
  | `parse(do_clean=True)` | `None` | Parse all sections |
38
- | `samples()` | `list[dict]` | One record per unique sample |
56
+ | `clean()` | `str` | Return cleaned content as a string — source file is **never** modified |
57
+ | `samples()` | `list[dict]` | One record per unique `(sample_id, lane)` pair |
39
58
  | `index_type()` | `str` | `"dual"`, `"single"`, or `"none"` |
59
+ | `parse_custom_section(name, *, required=False)` | `dict[str, str]` | Parse any non-standard section as key/value pairs |
40
60
  | `.adapters` | `list[str]` | Adapter sequences |
41
61
  | `.experiment_name` | `str \| None` | Run/experiment name |
42
62
 
@@ -87,7 +107,7 @@ from samplesheet_parser.instruments import (
87
107
 
88
108
  | Name | Kind | Description |
89
109
  |---|---|---|
90
- | `Workflow` | `StrEnum` | `Workflow.A` (i5 forward) / `Workflow.B` (i5 RC'd on chip) |
110
+ | `Workflow` | `str, Enum` | `Workflow.A` (i5 forward) / `Workflow.B` (i5 RC'd on chip) |
91
111
  | `detect_workflow(name)` | `Workflow \| None` | Classify an instrument name; `None` for unknown or ambiguous (e.g. `NovaSeq 6000`) |
92
112
  | `parse_workflow(value)` | `Workflow \| None` | Coerce a CLI string (`"a"` / `"b"`) to `Workflow` |
93
113
  | `reverse_complement(seq)` | `str` | Reverse-complement a DNA sequence (preserves `N`, case-preserving) |
@@ -243,6 +263,24 @@ Normalizes index sequence lengths across a list of sample dicts. See [Index Util
243
263
 
244
264
  ---
245
265
 
266
+ ## hamming_distance
267
+
268
+ ```python
269
+ from samplesheet_parser import hamming_distance
270
+ ```
271
+
272
+ Computes the Hamming distance between two equal-length index sequences, counting `N` wildcards as matches:
273
+
274
+ ```python
275
+ hamming_distance("ATTACTCG", "ATTACTCG") # 0
276
+ hamming_distance("ATTACTCG", "ATTACTCC") # 1
277
+ hamming_distance("ATTNCNCG", "ATTACTCG") # 0 — N matches anything
278
+ ```
279
+
280
+ Used internally by `SampleSheetValidator` when checking index collision thresholds. Accepts sequences of different lengths (returns `None`) but in practice all samples in a valid sheet have uniform index lengths after normalization.
281
+
282
+ ---
283
+
246
284
  ## Enums
247
285
 
248
286
  ```python
@@ -73,12 +73,41 @@ print(rs.read_structure)
73
73
 
74
74
  ## Shared interface
75
75
 
76
- Both `SampleSheetV1` and `SampleSheetV2` expose:
76
+ Both `SampleSheetV1` and `SampleSheetV2` satisfy the `SampleSheetParser` Protocol and expose:
77
77
 
78
78
  | Method / attribute | Returns | Description |
79
79
  |---|---|---|
80
80
  | `parse(do_clean=True)` | `None` | Parse all sections |
81
- | `samples()` | `list[dict]` | One record per unique sample |
81
+ | `clean()` | `str` | Return cleaned content as a string — source file is **never** modified |
82
+ | `samples()` | `list[dict]` | One record per unique `(sample_id, lane)` pair |
82
83
  | `index_type()` | `str` | `"dual"`, `"single"`, or `"none"` |
84
+ | `parse_custom_section(name, *, required=False)` | `dict[str, str]` | Parse any non-standard section as key/value pairs |
83
85
  | `.adapters` | `list[str]` | Adapter sequences |
84
86
  | `.experiment_name` | `str \| None` | Run/experiment name |
87
+
88
+ ### In-memory cleaning
89
+
90
+ `parse(do_clean=True)` (the default) cleans the file content in memory before parsing — stripping BOM, quotes, stray whitespace, and normalising V2 section names. **The source file on disk is never modified and no `.backup` files are created.**
91
+
92
+ ```python
93
+ # Access the cleaned content directly
94
+ cleaned = sheet.clean() # returns str, no file I/O side-effects
95
+
96
+ # Parse with cleaning (default)
97
+ sheet.parse()
98
+
99
+ # Parse without cleaning (raw file)
100
+ sheet.parse(do_clean=False)
101
+ ```
102
+
103
+ ### Multi-lane deduplication
104
+
105
+ `samples()` deduplicates by `(sample_id, lane)` pair, not by `sample_id` alone. A sample appearing across multiple lanes produces one record per lane.
106
+
107
+ ```python
108
+ sheet.parse()
109
+ samples = sheet.samples()
110
+ # Multi-lane sheet with Sample1 in lanes 1 and 2 → two records:
111
+ # [{"sample_id": "Sample1", "lane": "1", ...},
112
+ # {"sample_id": "Sample1", "lane": "2", ...}]
113
+ ```
@@ -32,20 +32,24 @@ for w in result.warnings:
32
32
  | `NO_ADAPTERS` | warning | No adapter sequences configured |
33
33
  | `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
34
34
 
35
- ## Hamming distance checking
35
+ ## Index distance checking
36
36
 
37
- Indexes that are too similar cause read bleed-through between samples during demultiplexing — a common cause of low-quality runs that is not caught by a simple duplicate check.
37
+ Indexes that are too similar cause read bleed-through between samples during demultiplexing, a common cause of low-quality runs that a simple duplicate check does not catch.
38
38
 
39
- The validator computes the Hamming distance between every pair of indexes within each lane. For dual-index sheets, the I7 and I5 sequences are combined before comparison, so a pair that is close on I7 but well-separated on I5 is not incorrectly flagged.
39
+ For every pair of samples within a lane, the validator computes a combined distance: the I7 (index) mismatch count plus the I5 (index2) mismatch count. This sum equals the minimum number of sequencing errors needed to read one sample's barcodes as another's across both index reads, which is the quantity that governs misassignment risk. Summing the per-index distances (rather than concatenating the two indexes into one string) keeps the I7 and I5 positions aligned even when samples use different index lengths. A pair is flagged when the combined distance is below the threshold.
40
+
41
+ Each per-index distance treats an `N` cycle as a wildcard that matches any base, matching how demultiplexers handle `N`. Two indexes that differ only where one carries an `N` are therefore reported as colliding. Sequences of different lengths are compared up to the length of the shorter sequence.
40
42
 
41
43
  ```python
42
44
  # Default threshold: 3
43
45
  result = SampleSheetValidator().validate(sheet)
44
46
 
45
- # Custom threshold — stricter for longer indexes
47
+ # Custom threshold: stricter for longer indexes
46
48
  result = SampleSheetValidator().validate(sheet, min_hamming_distance=4)
47
49
  ```
48
50
 
51
+ The standalone helpers are also available: `hamming_distance(a, b)` for the literal Hamming distance and `index_collision_distance(a, b)` for the wildcard-aware per-index distance the validator uses.
52
+
49
53
  ## Structured results
50
54
 
51
55
  ```python