From 400cb3c0b8db2142b9f5ae095c79459c825012fb Mon Sep 17 00:00:00 2001 From: Alex Rubinsteyn Date: Tue, 13 Oct 2026 13:42:00 -0400 Subject: [PATCH 1/3] Docs: shorter README and clearer guides Claude-Session: https://claude.ai/code/session_01BgZRucyDFu1jX5rMXBaSnC --- README.md | 14 ++++++++------ docs/guides/progress.md | 43 ++++++++++++++++++++++------------------- docs/index.md | 6 ++++-- 3 files changed, 35 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 7868e91..d49062c 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,9 @@ gtfparse ======== -Parsing tools for GTF (gene transfer format) files. - +Read GTF (gene transfer format) annotations into a pandas DataFrame, with one +row per feature and attribute values such as gene and transcript IDs expanded +into columns. ## Install @@ -15,8 +16,8 @@ Parsing tools for GTF (gene transfer format) files. python -m pip install gtfparse ``` -Python 3.9 or later is required. Version 3 uses pandas and PyArrow; Polars -output is optional and requires `gtfparse[polars]`. +Python 3.9 or later is required. For optional Polars output, install +`gtfparse[polars]`. ## Read an annotation and find genes @@ -62,5 +63,6 @@ it is not the gene ID. The ninth GTF field supplies attributes such as - [Version 3 migration and optional Polars output](docs/guides/migration.md) - [Complete API reference](docs/reference.md) -Build with `python -m pip install -r requirements-docs.txt` and `./docs.sh`. -Run `python scripts/check_docs_examples.py` to verify the printed examples. +To build the documentation locally, run +`python -m pip install -r requirements-docs.txt` and `./docs.sh`. +`python scripts/check_docs_examples.py` checks the printed example output. diff --git a/docs/guides/progress.md b/docs/guides/progress.md index 1e3a3eb..4a20fe7 100644 --- a/docs/guides/progress.md +++ b/docs/guides/progress.md @@ -1,24 +1,10 @@ # Report parsing progress Pass `progress_callback(stage, completed, total)` to `read_gtf` to connect -parsing to your own progress UI. The callback runs synchronously; exceptions -from it stop parsing and propagate to the caller. Without a callback, gtfparse -does not display a progress bar or add a progress-library dependency. +parsing to your own progress UI. Without a callback, gtfparse does not display +a progress bar or add a progress-library dependency. -| Stage | Reports | -| --- | --- | -| `read` | `(0, None)` before loading/filtering the file; `(rows, rows)` after it succeeds | -| `attributes` | `(0, rows)`, then every 10,000 rows, then `(rows, rows)` | -| `convert` | `(0, None)` before output conversion/transforms; `(rows, rows)` after success | - -Counts refer to rows retained after `features` filtering, not bytes or overall -percentages. `None` means the total is unknown: loading and conversion expose -only stage boundaries, so use an indeterminate indicator during those steps. -Attribute expansion is omitted when `expand_attribute_column=False`. A stage -that fails does not emit completion. An empty filtered result is supported; -its attributes stage emits a single `(0, 0)` event. Empty input files raise `gtfparse.ParsingError`. - -For example, with the optional `tqdm` package installed: +This example requires the optional `tqdm` package and your own GTF file: ```python from gtfparse import read_gtf @@ -37,9 +23,26 @@ with tqdm(unit="rows") as bar: df = read_gtf("gene_annotations.gtf", progress_callback=show_progress) ``` +## Stages and counts + +| Stage | Reports | +| --- | --- | +| `read` | `(0, None)` before loading/filtering the file; `(rows, rows)` after it succeeds | +| `attributes` | `(0, rows)`, then every 10,000 rows, then `(rows, rows)` | +| `convert` | `(0, None)` before output conversion/transforms; `(rows, rows)` after success | + +Counts refer to rows retained after `features` filtering, not bytes or overall +percentages. `None` means the total is unknown: loading and conversion expose +only stage boundaries, so use an indeterminate indicator during those steps. +Attribute expansion is omitted when `expand_attribute_column=False`. + +The callback runs synchronously; exceptions from it stop parsing and propagate +to the caller. A stage that fails does not emit completion. An empty filtered +result is supported; its attributes stage emits a single `(0, 0)` event. Empty +input files raise `gtfparse.ParsingError`. + +## Lower-level functions + `parse_gtf` reports the `read` stage, `parse_gtf_and_expand_attributes` reports `read` and `attributes`, `parse_gtf_pandas` reports `read` and `convert`, and `expand_attribute_strings` reports only `attributes` using the same callback. - -Quoted attribute values preserve spaces, semicolons, and apostrophes. Raw -attributes (`expand_attribute_column=False`) retain their original quote marks. diff --git a/docs/index.md b/docs/index.md index e4a7c7a..027e599 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,8 +9,8 @@ attribute values such as gene and transcript IDs expanded into columns. python -m pip install gtfparse ``` -Python 3.9 or later is required. Version 3 uses pandas and PyArrow; Polars -output is optional and requires `gtfparse[polars]`. +Python 3.9 or later is required. For optional Polars output, install +`gtfparse[polars]`. ## Read an annotation and find genes @@ -59,6 +59,8 @@ features = read_gtf("annotations.gtf.gz", features={"gene", "transcript"}) The `features` option filters row types while reading. Compressed inputs are detected from their contents. Attribute expansion does not turn every row into a gene or automatically supply missing parent features. +Quoted attribute values preserve spaces, semicolons, and apostrophes. Raw +attributes (`expand_attribute_column=False`) retain their original quote marks. Continue with [filter and write annotations](guides/annotations.md), then [progress callbacks](guides/progress.md) or [version 3 migration](guides/migration.md). From 48ca7734f922f879f01dbb7807a900223f1265a0 Mon Sep 17 00:00:00 2001 From: Alex Rubinsteyn Date: Tue, 13 Oct 2026 14:34:40 -0400 Subject: [PATCH 2/3] Give the stacked documentation follow-up version 3.0.4 --- gtfparse/__init__.py | 2 +- tasks/todo.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/gtfparse/__init__.py b/gtfparse/__init__.py index 60a9c8c..a2563b7 100644 --- a/gtfparse/__init__.py +++ b/gtfparse/__init__.py @@ -24,7 +24,7 @@ ) from .write_gtf import write_gtf -__version__ = "3.0.3" +__version__ = "3.0.4" __all__ = [ "GENCODE_BIOTYPE_ALIASES", diff --git a/tasks/todo.md b/tasks/todo.md index eb51ead..7886346 100644 --- a/tasks/todo.md +++ b/tasks/todo.md @@ -512,10 +512,12 @@ after the modern stack is verified. Update PR branches without publishing. - [x] Inspect PR heads, current master and version requirements. - [x] Preserve current code while resolving the version conflict. - [x] Run lint, tests and documentation checks on #93. -- [ ] Incorporate #93 in #95 and verify its separate patch bump. +- [x] Incorporate #93 in #95 and verify its separate patch bump. - [ ] Update the PR branches and close superseded #74. ## Review PR #93: lint passed, all 213 tests passed, all three executable documentation examples passed, and the strict MkDocs build passed. +PR #95: merged the refreshed parent; version 3.0.4, lint, 213 tests, and the +strict MkDocs build passed. From 9425d5a022856843d7821cff45089b19fe98083d Mon Sep 17 00:00:00 2001 From: Alex Rubinsteyn Date: Tue, 13 Oct 2026 14:36:27 -0400 Subject: [PATCH 3/3] Record successful documentation stack validation --- tasks/todo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tasks/todo.md b/tasks/todo.md index 7886346..d924720 100644 --- a/tasks/todo.md +++ b/tasks/todo.md @@ -513,7 +513,7 @@ after the modern stack is verified. Update PR branches without publishing. - [x] Preserve current code while resolving the version conflict. - [x] Run lint, tests and documentation checks on #93. - [x] Incorporate #93 in #95 and verify its separate patch bump. -- [ ] Update the PR branches and close superseded #74. +- [x] Update both PR branches. Closing superseded #74 is the final remote step. ## Review