samplesheet-parser 1.0.0__tar.gz → 1.2.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 (117) hide show
  1. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/.gitignore +1 -0
  2. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/.pre-commit-config.yaml +1 -0
  3. samplesheet_parser-1.2.0/.readthedocs.yaml +17 -0
  4. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/.zenodo.json +1 -1
  5. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/CHANGELOG.md +154 -0
  6. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/CITATION.cff +2 -2
  7. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/CONTRIBUTING.md +1 -1
  8. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/PKG-INFO +12 -6
  9. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/README.md +6 -3
  10. samplesheet_parser-1.2.0/docs/api.md +215 -0
  11. samplesheet_parser-1.2.0/docs/changelog.md +5 -0
  12. samplesheet_parser-1.2.0/docs/ci.md +83 -0
  13. samplesheet_parser-1.2.0/docs/cli.md +250 -0
  14. samplesheet_parser-1.2.0/docs/contributing.md +5 -0
  15. samplesheet_parser-1.2.0/docs/examples.md +365 -0
  16. samplesheet_parser-1.2.0/docs/guide/conversion.md +54 -0
  17. samplesheet_parser-1.2.0/docs/guide/diffing.md +59 -0
  18. samplesheet_parser-1.2.0/docs/guide/filtering.md +101 -0
  19. samplesheet_parser-1.2.0/docs/guide/index_utils.md +60 -0
  20. samplesheet_parser-1.2.0/docs/guide/merging.md +87 -0
  21. samplesheet_parser-1.2.0/docs/guide/parsing.md +84 -0
  22. samplesheet_parser-1.2.0/docs/guide/quickstart.md +69 -0
  23. samplesheet_parser-1.2.0/docs/guide/splitting.md +102 -0
  24. samplesheet_parser-1.2.0/docs/guide/validation.md +59 -0
  25. samplesheet_parser-1.2.0/docs/guide/writing.md +82 -0
  26. samplesheet_parser-1.2.0/docs/index.md +59 -0
  27. samplesheet_parser-1.2.0/docs/installation.md +44 -0
  28. samplesheet_parser-1.2.0/docs/requirements.txt +4 -0
  29. samplesheet_parser-1.2.0/examples/demo_converter.py +117 -0
  30. samplesheet_parser-1.2.0/examples/demo_diff.py +144 -0
  31. samplesheet_parser-1.2.0/examples/demo_filter.py +110 -0
  32. samplesheet_parser-1.2.0/examples/demo_index_utils.py +123 -0
  33. samplesheet_parser-1.2.0/examples/demo_splitter.py +87 -0
  34. samplesheet_parser-1.2.0/examples/demo_writer.py +170 -0
  35. samplesheet_parser-1.2.0/mkdocs.yml +80 -0
  36. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/convert/environment.yml +6 -0
  37. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/convert/main.nf +50 -0
  38. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/convert/meta.yml +62 -0
  39. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +79 -0
  40. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/convert/tests/tags.yml +4 -0
  41. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/info/environment.yml +6 -0
  42. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/info/main.nf +45 -0
  43. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/info/meta.yml +61 -0
  44. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/info/tests/main.nf.test +76 -0
  45. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/info/tests/tags.yml +4 -0
  46. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/validate/environment.yml +6 -0
  47. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/validate/main.nf +45 -0
  48. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/validate/meta.yml +62 -0
  49. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +76 -0
  50. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/validate/tests/tags.yml +4 -0
  51. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/pyproject.toml +6 -3
  52. samplesheet_parser-1.2.0/recipes/meta.yaml +56 -0
  53. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/__init__.py +6 -0
  54. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/cli.py +241 -3
  55. samplesheet_parser-1.2.0/samplesheet_parser/filter.py +243 -0
  56. samplesheet_parser-1.2.0/samplesheet_parser/splitter.py +303 -0
  57. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/writer.py +190 -147
  58. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_cli.py +438 -42
  59. samplesheet_parser-1.2.0/tests/test_filter.py +380 -0
  60. samplesheet_parser-1.2.0/tests/test_splitter.py +466 -0
  61. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/.github/workflows/ci.yml +0 -0
  62. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/.github/workflows/copilot-instructions.md +0 -0
  63. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/LICENSE +0 -0
  64. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/demo_merger.py +0 -0
  65. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/parse_examples.py +0 -0
  66. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
  67. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
  68. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
  69. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
  70. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/README.md +0 -0
  71. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/combined_clean.csv +0 -0
  72. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
  73. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
  74. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
  75. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
  76. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/v1_single_index.csv +0 -0
  77. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
  78. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
  79. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
  80. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
  81. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
  82. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
  83. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
  84. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
  85. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/images/samplesheet_parser_arch_v03.png +0 -0
  86. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/images/samplesheet_parser_overview.png +0 -0
  87. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/converter.py +0 -0
  88. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/diff.py +0 -0
  89. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/enums.py +0 -0
  90. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/factory.py +0 -0
  91. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/index_utils.py +0 -0
  92. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/merger.py +0 -0
  93. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/parsers/__init__.py +0 -0
  94. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/parsers/v1.py +0 -0
  95. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/parsers/v2.py +0 -0
  96. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/py.typed +0 -0
  97. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/samplesheet_parser/validators.py +0 -0
  98. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/scripts/demo_converter.py +0 -0
  99. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/scripts/demo_diff.py +0 -0
  100. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/scripts/demo_writer.py +0 -0
  101. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/__init__.py +0 -0
  102. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/conftest.py +0 -0
  103. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
  104. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
  105. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
  106. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_converter.py +0 -0
  107. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_diff.py +0 -0
  108. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_factory.py +0 -0
  109. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_index_utils.py +0 -0
  110. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_merger.py +0 -0
  111. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_parsers/__init__.py +0 -0
  112. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_parsers/test_v1.py +0 -0
  113. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_parsers/test_v2.py +0 -0
  114. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_validators/__init__.py +0 -0
  115. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_validators/test_hamming.py +0 -0
  116. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_validators/test_validators.py +0 -0
  117. {samplesheet_parser-1.0.0 → samplesheet_parser-1.2.0}/tests/test_writer.py +0 -0
@@ -45,3 +45,4 @@ env/
45
45
  *.backup
46
46
  *.tmp
47
47
 
48
+ site/
@@ -5,6 +5,7 @@ repos:
5
5
  - id: trailing-whitespace
6
6
  - id: end-of-file-fixer
7
7
  - id: check-yaml
8
+ exclude: ^recipes/
8
9
  - id: check-toml
9
10
  - id: check-merge-conflict
10
11
  - id: check-added-large-files
@@ -0,0 +1,17 @@
1
+ version: 2
2
+
3
+ build:
4
+ os: ubuntu-24.04
5
+ tools:
6
+ python: "3.12"
7
+
8
+ mkdocs:
9
+ configuration: mkdocs.yml
10
+
11
+ python:
12
+ install:
13
+ - method: pip
14
+ path: .
15
+ extra_requirements:
16
+ - cli
17
+ - requirements: docs/requirements.txt
@@ -4,7 +4,7 @@
4
4
  "upload_type": "software",
5
5
  "access_right": "open",
6
6
  "license": "Apache-2.0",
7
- "version": "0.3.1",
7
+ "version": "1.1.0",
8
8
  "keywords": [
9
9
  "bioinformatics", "Illumina", "SampleSheet", "BCLConvert",
10
10
  "demultiplexing", "genomics", "sequencing", "Python"
@@ -6,6 +6,160 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
6
6
 
7
7
  ---
8
8
 
9
+ ## [Unreleased]
10
+
11
+ ---
12
+
13
+ ## [1.2.0] - 2026-04-14
14
+
15
+ ### Changed
16
+
17
+ - Minimum `typer` version raised from `>=0.9` to `>=0.12` to ensure
18
+ compatibility with `click >=8.2` (`make_metavar` signature change).
19
+
20
+ ### Added
21
+
22
+ - **`SampleSheetSplitter` and `SplitResult`** — splits a combined sheet into
23
+ one file per project or per lane (the inverse of `SampleSheetMerger`).
24
+ - `SampleSheetSplitter(path, *, by="project"|"lane", target_version=None, unassigned_label="unassigned")`
25
+ - `split(output_dir, *, prefix="", suffix="_SampleSheet.csv", validate=True) → SplitResult`
26
+ - Header, reads, and settings are copied into every output file; only sample
27
+ rows are divided. Samples with no project/lane are grouped under a
28
+ configurable `unassigned_label`.
29
+ - Incomplete records (missing `Sample_ID` or `Index`) are skipped with a
30
+ warning. Groups that produce no valid samples are omitted with a warning.
31
+ - `SampleSheetSplitter` and `SplitResult` are exported from the top-level
32
+ package.
33
+
34
+ - **`SampleSheetFilter` and `FilterResult`** — extracts a subset of samples
35
+ from a sheet by project, lane, or sample ID (with glob support).
36
+ - `SampleSheetFilter(path, *, target_version=None)`
37
+ - `filter(output_path, *, project=None, lane=None, sample_id=None, validate=True) → FilterResult`
38
+ - Multiple criteria are ANDed — a sample must match all provided criteria.
39
+ - `sample_id` supports glob patterns (e.g. `"CTRL_*"`, `"SAMPLE_00[1-3]"`)
40
+ via `fnmatch.fnmatchcase` for consistent case-sensitive behavior across
41
+ platforms.
42
+ - No file is written when no samples match; `FilterResult.output_path` is
43
+ `None` in that case.
44
+ - `SampleSheetFilter` and `FilterResult` are exported from the top-level
45
+ package.
46
+
47
+ - **`samplesheet split` CLI command** — splits a combined sheet into per-group
48
+ files. Accepts `--by project|lane`, `--output-dir / -d`, `--to v1|v2`,
49
+ `--format json|text`, and `--prefix`. Exits 0 on clean split, 1 if warnings
50
+ were produced, 2 on bad arguments or unreadable files.
51
+
52
+ - **`samplesheet filter` CLI command** — filters samples by `--project / -p`,
53
+ `--lane / -l`, and `--sample-id / -s` (glob patterns supported). Accepts
54
+ `--output / -o`, `--to v1|v2`, and `--format json|text`. Exits 0 when
55
+ samples match, 1 when no samples match, 2 on bad arguments.
56
+
57
+ - **`SampleSheetWriter.clear_samples()`** — public method to remove all samples
58
+ from a writer while preserving header, reads, and settings. Enables the
59
+ copy-metadata-then-repopulate pattern without accessing the private
60
+ `_samples` attribute.
61
+
62
+ - **`--format json` for `samplesheet convert`** — the convert command now accepts
63
+ `--format json` and emits a structured JSON object with `input`, `output`,
64
+ `source_version`, and `target_version` keys. All seven CLI subcommands now
65
+ support `--format json` uniformly.
66
+
67
+ - **Bioconda recipe (`recipes/meta.yaml`)** — a `noarch: python` conda recipe
68
+ with `loguru` as the only runtime dependency. Python version is not pinned
69
+ (noarch packages rely on the conda solver for compatibility). The CLI extra
70
+ (`typer`) is intentionally omitted from the base recipe so the conda package
71
+ stays lightweight; users who need the `samplesheet` CLI can
72
+ `conda install typer` alongside.
73
+
74
+ - **nf-core compatible Nextflow modules** — three modules following
75
+ nf-core/modules conventions, each with `main.nf`, `meta.yml`,
76
+ `environment.yml`, nf-test tests, and `tags.yml`:
77
+ - `SAMPLESHEETPARSER_VALIDATE` — validates V1/V2 sheets and emits a
78
+ structured JSON report; exits 1 on errors so pipelines fail before
79
+ demultiplexing.
80
+ - `SAMPLESHEETPARSER_CONVERT` — bidirectional V1↔V2 conversion with target
81
+ version passed as a channel value.
82
+ - `SAMPLESHEETPARSER_INFO` — emits a JSON metadata summary (format, sample
83
+ count, lanes, index type, read lengths, adapters) for run logging and
84
+ conditional pipeline branching.
85
+
86
+ - **Example scripts** — `examples/demo_splitter.py` and
87
+ `examples/demo_filter.py` demonstrating the new split and filter APIs with
88
+ three and four runnable scenarios respectively.
89
+
90
+ ### Tests
91
+
92
+ - **`tests/test_splitter.py`** — 46 tests covering: split by project and lane,
93
+ header/reads/settings preservation, unassigned samples (custom label),
94
+ incomplete records (missing `Sample_ID` or `Index`, all-incomplete group),
95
+ empty input, target version override, custom prefix/suffix, output directory
96
+ creation, `SplitResult` summary and `source_version`, and error conditions
97
+ (`FileNotFoundError`, `ValueError` on invalid `--by`).
98
+
99
+ - **`tests/test_filter.py`** — 46 tests covering: filter by project, lane
100
+ (string and int), and sample ID (exact and glob); multiple ANDed criteria;
101
+ no-match behaviour (no file written, `matched_count == 0`); header/settings
102
+ preservation; target version override; `FilterResult` attributes; incomplete
103
+ records; and error conditions (`ValueError`, `FileNotFoundError`).
104
+
105
+ - **`TestCLISplit` and `TestCLIFilter`** in `tests/test_cli.py` — 13 tests each
106
+ covering happy paths, JSON output, warning exit codes, error exit codes,
107
+ exception paths (via `monkeypatch`), and text output formatting.
108
+
109
+ - Three new `TestCLIConvert` tests covering `--format json` exit code,
110
+ JSON output structure (`source_version`, `target_version`, `input`, `output`
111
+ keys), and the `--format xml` invalid-format guard.
112
+
113
+ ---
114
+
115
+ ## [1.1.0] - 2026-04-05
116
+
117
+ ### Added
118
+
119
+ - **`--version` / `-V` CLI flag** — prints the installed package version
120
+ and exits. Reads the version via `importlib.metadata` so the full package
121
+ is not loaded just to print a version string.
122
+
123
+ - **`demo_converter.py`** — runnable example covering V1→V2 conversion,
124
+ V2→V1 (lossy) conversion, and a full V1→V2→V1 roundtrip with sample
125
+ identity verification.
126
+
127
+ - **`demo_diff.py`** — runnable example covering five diff scenarios:
128
+ identical sheets, header change, sample added, index correction, and
129
+ cross-format (V1 vs its V2 conversion) diff.
130
+
131
+ - **`demo_writer.py`** — runnable example covering the fluent
132
+ `SampleSheetWriter` API: building V1 and V2 sheets from scratch,
133
+ correcting a sample index on an existing sheet, and removing a sample
134
+ before submission.
135
+
136
+ - **`demo_index_utils.py`** — runnable example covering
137
+ `normalize_index_lengths` with trim and pad strategies, dual-index
138
+ normalization, and a real-sheet walkthrough.
139
+
140
+ ### Fixed
141
+
142
+ - `SampleSheetFactory.create_parser()` now returns a typed local variable
143
+ instead of `self.parser`, resolving a mypy `return-value` error caused
144
+ by the instance attribute being typed as `SampleSheetV1 | SampleSheetV2
145
+ | None`.
146
+
147
+ - `cli.py` fallback type aliases (`_FormatOption`, `_OutputOption`,
148
+ `_VersionOption`) reduced from `type: ignore[assignment,misc]` to
149
+ `type: ignore[misc]` — the `assignment` suppression was unused under
150
+ current mypy.
151
+
152
+ ### Tests
153
+
154
+ - `TestCLIVersion` — four new tests covering `--version` exit code, `-V`
155
+ short flag, package name in output, version string in output, and
156
+ `PackageNotFoundError` fallback to `"unknown"`.
157
+
158
+ - Five Copilot PR #23 review comments resolved: long test signatures and
159
+ `runner.invoke(...)` calls wrapped to the 100-char line limit.
160
+
161
+ ---
162
+
9
163
  ## [1.0.0] - 2026-04-05
10
164
 
11
165
  ### Added
@@ -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: 0.3.2
12
- date-released: 2026-03-12
11
+ version: 1.1.0
12
+ date-released: 2026-04-05
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"
@@ -28,7 +28,7 @@ Thanks for contributing! This guide explains how to set up a local development e
28
28
  git clone https://github.com/chaitanyakasaraneni/samplesheet-parser.git
29
29
  cd samplesheet-parser
30
30
 
31
- # 2. Create a virtual environment (Python 3.10+)
31
+ # 2. Create a virtual environment (Python 3.12+)
32
32
  python -m venv .venv
33
33
  source .venv/bin/activate # Windows: .venv\Scripts\activate
34
34
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: samplesheet-parser
3
- Version: 1.0.0
3
+ Version: 1.2.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
@@ -39,14 +39,17 @@ Classifier: Typing :: Typed
39
39
  Requires-Python: >=3.12
40
40
  Requires-Dist: loguru>=0.7
41
41
  Provides-Extra: cli
42
- Requires-Dist: typer>=0.9; extra == 'cli'
42
+ Requires-Dist: typer>=0.12; extra == 'cli'
43
43
  Provides-Extra: dev
44
44
  Requires-Dist: black>=24.0; extra == 'dev'
45
+ Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
46
+ Requires-Dist: mkdocs>=1.6; extra == 'dev'
47
+ Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
45
48
  Requires-Dist: mypy>=1.8; extra == 'dev'
46
49
  Requires-Dist: pytest-cov>=4.1; extra == 'dev'
47
50
  Requires-Dist: pytest>=7.4; extra == 'dev'
48
51
  Requires-Dist: ruff>=0.3; extra == 'dev'
49
- Requires-Dist: typer>=0.9; extra == 'dev'
52
+ Requires-Dist: typer>=0.12; extra == 'dev'
50
53
  Description-Content-Type: text/markdown
51
54
 
52
55
  # samplesheet-parser
@@ -56,11 +59,14 @@ Description-Content-Type: text/markdown
56
59
  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.
57
60
 
58
61
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
59
- [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
62
+ [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
60
63
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)
61
64
  [![Tests](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
62
65
  [![codecov](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
63
66
  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18989694.svg)](https://doi.org/10.5281/zenodo.18989694)
67
+ [![Docs](https://readthedocs.org/projects/illumina-samplesheet/badge/)](https://illumina-samplesheet.readthedocs.io)
68
+
69
+ **Docs:** https://illumina-samplesheet.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
64
70
 
65
71
  ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v03.png)
66
72
 
@@ -86,7 +92,7 @@ pip install samplesheet-parser
86
92
  pip install "samplesheet-parser[cli]"
87
93
  ```
88
94
 
89
- Requires Python 3.10+. No mandatory runtime dependencies beyond `loguru`.
95
+ Requires Python 3.12+. No mandatory runtime dependencies beyond `loguru`.
90
96
 
91
97
  ---
92
98
 
@@ -659,7 +665,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local testing guide and PR c
659
665
  title = {samplesheet-parser: Format-agnostic parser for Illumina SampleSheet.csv},
660
666
  year = {2026},
661
667
  url = {https://github.com/chaitanyakasaraneni/samplesheet-parser},
662
- version = {1.0.0}
668
+ version = {1.1.0}
663
669
  }
664
670
  ```
665
671
 
@@ -5,11 +5,14 @@
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.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
8
+ [![Python 3.12+](https://img.shields.io/badge/python-3.12+-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
  [![Tests](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
11
11
  [![codecov](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
12
12
  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18989694.svg)](https://doi.org/10.5281/zenodo.18989694)
13
+ [![Docs](https://readthedocs.org/projects/illumina-samplesheet/badge/)](https://illumina-samplesheet.readthedocs.io)
14
+
15
+ **Docs:** https://illumina-samplesheet.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
13
16
 
14
17
  ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v03.png)
15
18
 
@@ -35,7 +38,7 @@ pip install samplesheet-parser
35
38
  pip install "samplesheet-parser[cli]"
36
39
  ```
37
40
 
38
- Requires Python 3.10+. No mandatory runtime dependencies beyond `loguru`.
41
+ Requires Python 3.12+. No mandatory runtime dependencies beyond `loguru`.
39
42
 
40
43
  ---
41
44
 
@@ -608,7 +611,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local testing guide and PR c
608
611
  title = {samplesheet-parser: Format-agnostic parser for Illumina SampleSheet.csv},
609
612
  year = {2026},
610
613
  url = {https://github.com/chaitanyakasaraneni/samplesheet-parser},
611
- version = {1.0.0}
614
+ version = {1.1.0}
612
615
  }
613
616
  ```
614
617
 
@@ -0,0 +1,215 @@
1
+ # API Reference
2
+
3
+ All public classes are importable directly from the top-level package:
4
+
5
+ ```python
6
+ from samplesheet_parser import (
7
+ SampleSheetFactory,
8
+ SampleSheetV1,
9
+ SampleSheetV2,
10
+ SampleSheetConverter,
11
+ SampleSheetValidator,
12
+ SampleSheetDiff,
13
+ SampleSheetWriter,
14
+ SampleSheetMerger,
15
+ SampleSheetSplitter,
16
+ SampleSheetFilter,
17
+ normalize_index_lengths,
18
+ )
19
+ ```
20
+
21
+ ---
22
+
23
+ ## SampleSheetFactory
24
+
25
+ | Method / attribute | Returns | Description |
26
+ |---|---|---|
27
+ | `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetV1 \| SampleSheetV2` | Auto-detect format and return the appropriate parser |
28
+ | `get_umi_length()` | `int` | UMI length from the current parser |
29
+ | `.version` | `SampleSheetVersion \| None` | Detected format version |
30
+
31
+ ---
32
+
33
+ ## SampleSheetV1 / SampleSheetV2 (shared interface)
34
+
35
+ | Method / attribute | Returns | Description |
36
+ |---|---|---|
37
+ | `parse(do_clean=True)` | `None` | Parse all sections |
38
+ | `samples()` | `list[dict]` | One record per unique sample |
39
+ | `index_type()` | `str` | `"dual"`, `"single"`, or `"none"` |
40
+ | `.adapters` | `list[str]` | Adapter sequences |
41
+ | `.experiment_name` | `str \| None` | Run/experiment name |
42
+
43
+ ### V2-only
44
+
45
+ | Method | Returns | Description |
46
+ |---|---|---|
47
+ | `get_umi_length()` | `int` | UMI length from `OverrideCycles` |
48
+ | `get_read_structure()` | `ReadStructure` | Parsed read structure dataclass |
49
+
50
+ ---
51
+
52
+ ## SampleSheetConverter
53
+
54
+ | Method | Returns | Description |
55
+ |---|---|---|
56
+ | `to_v2(output_path)` | `Path` | Convert IEM V1 → BCLConvert V2 |
57
+ | `to_v1(output_path)` | `Path` | Convert BCLConvert V2 → IEM V1 (lossy) |
58
+ | `.source_version` | `SampleSheetVersion \| None` | Auto-detected format of the input |
59
+
60
+ ---
61
+
62
+ ## SampleSheetValidator
63
+
64
+ | Method | Returns | Description |
65
+ |---|---|---|
66
+ | `validate(sheet, *, min_hamming_distance=3)` | `ValidationResult` | Run all checks; returns structured result |
67
+
68
+ ### ValidationResult
69
+
70
+ | Attribute / method | Type | Description |
71
+ |---|---|---|
72
+ | `is_valid` | `bool` | `False` if any errors present |
73
+ | `errors` | `list[ValidationIssue]` | Structured error records |
74
+ | `warnings` | `list[ValidationIssue]` | Structured warning records |
75
+ | `summary()` | `str` | One-line human-readable summary |
76
+
77
+ ### ValidationIssue
78
+
79
+ | Attribute | Type | Description |
80
+ |---|---|---|
81
+ | `code` | `str` | e.g. `"DUPLICATE_INDEX"` |
82
+ | `message` | `str` | Human-readable description |
83
+ | `context` | `dict` | Relevant sample IDs, lane, etc. |
84
+
85
+ ---
86
+
87
+ ## SampleSheetDiff
88
+
89
+ | Method | Returns | Description |
90
+ |---|---|---|
91
+ | `compare()` | `DiffResult` | Full comparison across header, reads, settings, and samples |
92
+
93
+ ### DiffResult
94
+
95
+ | Attribute / method | Type | Description |
96
+ |---|---|---|
97
+ | `has_changes` | `bool` | `True` if any difference detected |
98
+ | `summary()` | `str` | Human-readable one-paragraph summary |
99
+ | `header_changes` | `list[HeaderChange]` | Header, reads, and settings diffs |
100
+ | `samples_added` | `list[dict]` | Records present in new sheet only |
101
+ | `samples_removed` | `list[dict]` | Records present in old sheet only |
102
+ | `sample_changes` | `list[SampleChange]` | Per-sample field-level diffs |
103
+ | `source_version` | `SampleSheetVersion` | Format of the old sheet |
104
+ | `target_version` | `SampleSheetVersion` | Format of the new sheet |
105
+
106
+ ---
107
+
108
+ ## SampleSheetWriter
109
+
110
+ | Method / attribute | Returns | Description |
111
+ |---|---|---|
112
+ | `SampleSheetWriter(version=)` | — | Instantiate for `SampleSheetVersion.V1` or `.V2` |
113
+ | `from_sheet(sheet, version=)` | `SampleSheetWriter` | Load a parsed sheet for editing; optionally change format |
114
+ | `set_header(*, run_name, platform, ...)` | `self` | Set header fields (fluent) |
115
+ | `set_reads(*, read1, read2, index1, index2)` | `self` | Set read cycle counts (fluent) |
116
+ | `set_adapter(adapter_read1, adapter_read2)` | `self` | Set adapter sequences (fluent) |
117
+ | `set_override_cycles(override)` | `self` | Set `OverrideCycles` — V2 only (fluent) |
118
+ | `set_software_version(version)` | `self` | Set `SoftwareVersion` — V2 only (fluent) |
119
+ | `set_setting(key, value)` | `self` | Set an arbitrary settings key/value (fluent) |
120
+ | `add_sample(sample_id, *, index, ...)` | `self` | Append a sample row (fluent) |
121
+ | `remove_sample(sample_id, *, lane=)` | `self` | Remove sample(s) by ID, optionally scoped to a lane (fluent) |
122
+ | `update_sample(sample_id, *, lane=, **fields)` | `self` | Update fields on an existing sample in-place (fluent) |
123
+ | `clear_samples()` | `self` | Remove all samples while preserving header/reads/settings (fluent) |
124
+ | `write(path, *, validate=True)` | `Path` | Serialise to disk; validates first by default |
125
+ | `to_string()` | `str` | Serialise to string without writing to disk |
126
+ | `.sample_count` | `int` | Number of samples currently in the writer |
127
+ | `.sample_ids` | `list[str]` | Sample IDs currently in the writer |
128
+
129
+ ---
130
+
131
+ ## SampleSheetMerger
132
+
133
+ | Method / attribute | Returns | Description |
134
+ |---|---|---|
135
+ | `SampleSheetMerger(target_version=, min_hamming_distance=3)` | — | Instantiate with target format and optional Hamming threshold |
136
+ | `add(path)` | `self` | Register an input sheet path (fluent) |
137
+ | `merge(output_path, *, validate=True, abort_on_conflicts=True)` | `MergeResult` | Run the merge and write output |
138
+
139
+ ### MergeResult
140
+
141
+ | Attribute / method | Type | Description |
142
+ |---|---|---|
143
+ | `has_conflicts` | `bool` | `True` if any conflict recorded |
144
+ | `sample_count` | `int` | Samples in the merged output |
145
+ | `output_path` | `Path \| None` | Path written; `None` if write was aborted |
146
+ | `source_versions` | `dict[str, str]` | Per-input-file detected version |
147
+ | `conflicts` | `list[MergeConflict]` | Structured conflict records |
148
+ | `warnings` | `list[MergeConflict]` | Structured warning records |
149
+ | `summary()` | `str` | One-line human-readable summary |
150
+
151
+ ---
152
+
153
+ ## SampleSheetSplitter
154
+
155
+ | Method / attribute | Returns | Description |
156
+ |---|---|---|
157
+ | `SampleSheetSplitter(path, *, by="project", target_version=None, unassigned_label="unassigned")` | — | Instantiate with input path and grouping strategy |
158
+ | `split(output_dir, *, prefix="", suffix="_SampleSheet.csv", validate=True)` | `SplitResult` | Parse input and write one file per group |
159
+
160
+ ### SplitResult
161
+
162
+ | Attribute / method | Type | Description |
163
+ |---|---|---|
164
+ | `output_files` | `dict[str, Path]` | Group key → path of the written file |
165
+ | `sample_counts` | `dict[str, int]` | Group key → number of samples written |
166
+ | `warnings` | `list[str]` | Non-fatal issues (incomplete records, unassigned samples) |
167
+ | `source_version` | `str` | `"V1"` or `"V2"` |
168
+ | `summary()` | `str` | One-line human-readable summary |
169
+
170
+ ---
171
+
172
+ ## SampleSheetFilter
173
+
174
+ | Method / attribute | Returns | Description |
175
+ |---|---|---|
176
+ | `SampleSheetFilter(path, *, target_version=None)` | — | Instantiate with input path |
177
+ | `filter(output_path, *, project=None, lane=None, sample_id=None, validate=True)` | `FilterResult` | Write filtered copy to `output_path`; at least one criterion required |
178
+
179
+ `sample_id` supports glob patterns (e.g. `"CTRL_*"`) via `fnmatch.fnmatchcase` — matching is always case-sensitive.
180
+
181
+ ### FilterResult
182
+
183
+ | Attribute / method | Type | Description |
184
+ |---|---|---|
185
+ | `matched_count` | `int` | Samples that passed all filter criteria |
186
+ | `total_count` | `int` | Total samples in the input sheet |
187
+ | `output_path` | `Path \| None` | Path written; `None` when no samples matched |
188
+ | `source_version` | `str` | `"V1"` or `"V2"` |
189
+ | `summary()` | `str` | One-line human-readable summary |
190
+
191
+ ---
192
+
193
+ ## normalize_index_lengths
194
+
195
+ ```python
196
+ normalize_index_lengths(
197
+ samples: list[dict],
198
+ strategy: str, # "trim" or "pad"
199
+ index1_key: str | None = None, # auto-detected if None
200
+ index2_key: str | None = None, # auto-detected if None
201
+ ) -> list[dict]
202
+ ```
203
+
204
+ Normalizes index sequence lengths across a list of sample dicts. See [Index Utilities](guide/index_utils.md) for details.
205
+
206
+ ---
207
+
208
+ ## Enums
209
+
210
+ ```python
211
+ from samplesheet_parser.enums import SampleSheetVersion, InstrumentPlatform, UMILocation
212
+
213
+ SampleSheetVersion.V1 # IEM / bcl2fastq
214
+ SampleSheetVersion.V2 # BCLConvert
215
+ ```
@@ -0,0 +1,5 @@
1
+ # Changelog
2
+
3
+ The full changelog is maintained in the repository:
4
+
5
+ --8<-- "CHANGELOG.md"
@@ -0,0 +1,83 @@
1
+ # CI Integration
2
+
3
+ The CLI exits with meaningful codes (`0` = clean, `1` = issues, `2` = error), making it easy to wire into automated pipelines.
4
+
5
+ ## GitHub Actions
6
+
7
+ Add a validation step to any workflow that touches `SampleSheet.csv`:
8
+
9
+ ```yaml
10
+ # .github/workflows/validate-samplesheet.yml
11
+ name: Validate SampleSheet
12
+
13
+ on:
14
+ push:
15
+ paths:
16
+ - '**/SampleSheet.csv'
17
+ pull_request:
18
+ paths:
19
+ - '**/SampleSheet.csv'
20
+
21
+ jobs:
22
+ validate:
23
+ runs-on: ubuntu-latest
24
+ steps:
25
+ - uses: actions/checkout@v4
26
+
27
+ - uses: actions/setup-python@v5
28
+ with:
29
+ python-version: '3.12'
30
+
31
+ - run: pip install "samplesheet-parser[cli]"
32
+
33
+ - name: Validate SampleSheet
34
+ run: samplesheet validate SampleSheet.csv --format json
35
+ ```
36
+
37
+ ## pre-commit hook
38
+
39
+ Gate commits that touch any `SampleSheet.csv` in the repository:
40
+
41
+ ```yaml
42
+ # .pre-commit-config.yaml
43
+ repos:
44
+ - repo: local
45
+ hooks:
46
+ - id: samplesheet-validate
47
+ name: Validate SampleSheet.csv
48
+ entry: samplesheet validate
49
+ language: python
50
+ additional_dependencies: ["samplesheet-parser[cli]"]
51
+ files: SampleSheet\.csv$
52
+ pass_filenames: true
53
+ ```
54
+
55
+ Install and run once to verify:
56
+
57
+ ```bash
58
+ pip install pre-commit
59
+ pre-commit install
60
+ pre-commit run samplesheet-validate --all-files
61
+ ```
62
+
63
+ ## Stricter Hamming distance in CI
64
+
65
+ If your lab uses longer indexes (10 bp+), raise the minimum Hamming distance threshold to catch borderline cases earlier:
66
+
67
+ ```bash
68
+ samplesheet validate SampleSheet.csv --min-hamming 4
69
+ ```
70
+
71
+ ## Using JSON output in scripts
72
+
73
+ All commands support `--format json` for machine-readable output:
74
+
75
+ ```bash
76
+ result=$(samplesheet validate SampleSheet.csv --format json)
77
+ is_valid=$(echo "$result" | python3 -c "import sys,json; print(json.load(sys.stdin)['is_valid'])")
78
+
79
+ if [ "$is_valid" != "True" ]; then
80
+ echo "SampleSheet validation failed"
81
+ exit 1
82
+ fi
83
+ ```