docs(rules): Update script type hint advice by jonasfreimuth · Pull Request #4193 · snakemake/snakemake

jonasfreimuth · 2026-05-13T16:19:41Z

The described mechanism of importing the type via from snakemake.script import snakemake just does not work any more since #4032 adjusted the preamble.

To address #4192.

QC

The PR contains a test case for the changes or the changes are already covered by an existing test case. --> Exclusive docs change.
The documentation (docs/) is updated to reflect the changes or this is not necessary (e.g. if the change does neither modify the language nor the behavior or functionalities of Snakemake).
I, as a human being, have checked each line of code in this pull request

AI-assistance disclosure

I used AI assistance for:

Code generation (e.g., when writing an implementation or fixing a bug)
Test/benchmark generation
Documentation (including examples)
Research and understanding

Summary by CodeRabbit

Documentation
- Updated guidance for external Python scripts to recommend IDE-friendly type annotations using the Snakemake type for improved editor completion and type checking; example snippet updated accordingly.
- Added clarifying inline documentation stating a transitional stub remains for compatibility with prior guidance and is intended to be temporary.

coderabbitai · 2026-05-13T16:19:55Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Documentation and inline comments updated: external-script example now recommends importing the Snakemake type and annotating snakemake: Snakemake; the exported snakemake stub receives clarifying comments; a test case (Snakefile, script, expected output, and test entry) was added to validate the example.

Changes

External script type-hint docs and stub comments

Layer / File(s)	Summary
External script type-hint example `docs/snakefiles/rules.rst`	Replaced the previous TYPE_CHECKING import example with `from snakemake.iocontainers import Snakemake` and a `snakemake: Snakemake` annotation in the external script example.
snakemake stub inline comments `src/snakemake/iocontainers.py`	Inserted documentation comments clarifying the exported `snakemake` stub's purpose and noting compatibility with older documentation guidance.
Test case and assets `tests/test_script_alternative_type_checking/Snakefile`, `tests/test_script_alternative_type_checking/script.py`, `tests/test_script_alternative_type_checking/expected-results/test.txt`, `tests/tests.py`	Added a Snakefile, a script that writes "Hello world!" to the declared output, an expected-results file containing "Hello world!", and a test entry that runs this test scenario.

🎯 3 (Moderate) | ⏱️ ~20 minutes

Misleading line on rulescript type hinting in rule docs #4192 — Matches: this PR updates docs to recommend importing Snakemake for type hints and adds comments to the snakemake stub, addressing the documentation guidance discussed in that issue.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately describes the main change: updating documentation about script type hint advice, which is the primary focus of this PR that corrects guidance on rulescript type hinting.
Description check	✅ Passed	PR description provides clear context about the issue being fixed, explains what changed, and author confirmed QC checklist items.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

jonasfreimuth · 2026-05-13T17:44:37Z

Currently I'm not confident I do actually understand that this is correct.

jonasfreimuth · 2026-05-13T19:19:38Z

Ok, I think I understand the problem now and have addressed it in a reasonably backwards compatible manner. Not sure if the type hint in iocontainers should stay, but for the moment that still enables the previous advice, and why force users to update their scripts yet again?

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/snakemake/iocontainers.py`:
- Line 599: Replace the misspelled word "compatability" in the comment that
currently reads "For compatability with old advice, this should probably" with
the correct spelling "compatibility" so the comment becomes "For compatibility
with old advice, this should probably"; update the single-line comment
containing "compatability" to fix codespell CI failure.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 230a0339-b088-4143-9296-f035b9ddfeff

📥 Commits

Reviewing files that changed from the base of the PR and between 17f22f6 and 0e3175c.

📒 Files selected for processing (2)

docs/snakefiles/rules.rst
src/snakemake/iocontainers.py

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/test_script_alternative_type_checking/script.py`:
- Around line 3-6: Ruff flags the runtime-injected name "snakemake" as
undefined; to fix, add a typing-only import guarded by TYPE_CHECKING so you
don't clobber the runtime value: import TYPE_CHECKING from typing, then inside
"if TYPE_CHECKING:" import the Snakemake type (e.g., "from snakemake import
Snakemake") or alias it, and use that type in annotations for the existing
"snakemake" usage; reference symbols: snakemake, TYPE_CHECKING, Snakemake.

In `@tests/tests.py`:
- Around line 2305-2307: The function name test_script_import_snakemake_obj is
duplicated which overrides the earlier test; rename this second function to a
unique name (e.g., test_script_import_snakemake_obj_alternative) or merge its
behavior into the original, and update any references; locate the duplicate by
searching for test_script_import_snakemake_obj and change the function
definition (and any callers) so both tests run independently while keeping the
run(dpath("test_script_alternative_type_checking")) invocation intact.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 94962088-36e3-4701-8f9b-037feb0d68ef

📥 Commits

Reviewing files that changed from the base of the PR and between 5abf845 and f5ea8d8.

📒 Files selected for processing (4)

tests/test_script_alternative_type_checking/Snakefile
tests/test_script_alternative_type_checking/expected-results/test.txt
tests/test_script_alternative_type_checking/script.py
tests/tests.py

✅ Files skipped from review due to trivial changes (1)

tests/test_script_alternative_type_checking/expected-results/test.txt

jonasfreimuth · 2026-05-17T12:00:51Z

After this comment by CodeRabbit, I decided to scale this back and just update the line in the docs.

The mentioned mechanism just does not work any more since snakemake#4032 adjusted the preamble.

🤖 I have created a release *beep* *boop* --- ## [9.21.1](v9.21.0...v9.21.1) (2026-05-29) ### Bug Fixes * add default json function to benchmarks ([#4128](#4128)) ([41fab22](41fab22)) * do not rerun when checkpoint job missing but downstream file exists ([#4124](#4124)) ([a060b93](a060b93)) * ensure that error logs contain all available details ([#4183](#4183)) ([74a86e9](74a86e9)) * handle missing pss attribute in benchmark on Windows ([#4160](#4160)) ([da52080](da52080)) * implement Resources.setdefault ([#3968](#3968)) ([2413e99](2413e99)) * reporting remote nodes number ([#3978](#3978)) ([8c534f0](8c534f0)) * resolve pathvars before constructing storage queries ([#3969](#3969)) ([bd15237](bd15237)) * storage temp() file cleanup with RemoteProvider ([#4189](#4189)) ([898bad1](898bad1)) * tolerate FileNotFoundError in drop_iocache ([#4153](#4153)) ([#4191](#4191)) ([ce26b28](ce26b28)) ### Documentation * Added guide on debugging workflows ([#4029](#4029)) ([3d052ae](3d052ae)) * **cli:** Remove broken ref bold markup ([#4204](#4204)) ([1200ebf](1200ebf)) * remove duplicated resources attribute in rules.rst ([#4190](#4190)) ([6c8ecdd](6c8ecdd)) * **rules:** Update script type hint advice ([#4193](#4193)) ([6108712](6108712)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

jonasfreimuth requested a review from johanneskoester as a code owner May 13, 2026 16:19

jonasfreimuth marked this pull request as draft May 13, 2026 17:44

jonasfreimuth force-pushed the 4192-misleading-line-on-rulescript-type-hinting-in-rule-docs branch from 17f22f6 to 2cef2fa Compare May 13, 2026 18:47

jonasfreimuth changed the title ~~docs(rules): Fix outdated script type check advice~~ docs(rules): Remove snakemake object import line May 13, 2026

jonasfreimuth changed the title ~~docs(rules): Remove snakemake object import line~~ docs(rules): Correct & simplify rulescript type hinting advice May 13, 2026

jonasfreimuth marked this pull request as ready for review May 13, 2026 19:19

coderabbitai Bot reviewed May 13, 2026

View reviewed changes

Comment thread src/snakemake/iocontainers.py Outdated

jonasfreimuth force-pushed the 4192-misleading-line-on-rulescript-type-hinting-in-rule-docs branch from 0e3175c to 5abf845 Compare May 13, 2026 19:27

coderabbitai Bot reviewed May 17, 2026

View reviewed changes

Comment thread tests/test_script_alternative_type_checking/script.py Outdated

Comment thread tests/tests.py Outdated

jonasfreimuth force-pushed the 4192-misleading-line-on-rulescript-type-hinting-in-rule-docs branch from f5ea8d8 to 23f42f9 Compare May 17, 2026 09:33

jonasfreimuth marked this pull request as draft May 17, 2026 10:45

jonasfreimuth force-pushed the 4192-misleading-line-on-rulescript-type-hinting-in-rule-docs branch from 23f42f9 to e5fb140 Compare May 17, 2026 11:59

jonasfreimuth force-pushed the 4192-misleading-line-on-rulescript-type-hinting-in-rule-docs branch from e5fb140 to 1068a85 Compare May 17, 2026 12:02

jonasfreimuth changed the title ~~docs(rules): Correct & simplify rulescript type hinting advice~~ docs(rules): Update script type hint advice May 17, 2026

docs(rules): Update script type hint advice

414955a

The mentioned mechanism just does not work any more since snakemake#4032 adjusted the preamble.

jonasfreimuth force-pushed the 4192-misleading-line-on-rulescript-type-hinting-in-rule-docs branch from 1068a85 to 414955a Compare May 17, 2026 12:03

jonasfreimuth marked this pull request as ready for review May 17, 2026 12:03

johanneskoester approved these changes May 22, 2026

View reviewed changes

johanneskoester merged commit 6108712 into snakemake:main May 22, 2026
109 of 112 checks passed

snakemake-bot mentioned this pull request May 22, 2026

chore(main): release 9.21.1 #4200

Merged

jonasfreimuth deleted the 4192-misleading-line-on-rulescript-type-hinting-in-rule-docs branch May 26, 2026 14:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(rules): Update script type hint advice#4193

docs(rules): Update script type hint advice#4193
johanneskoester merged 1 commit into
snakemake:mainfrom
TRON-Bioinformatics:4192-misleading-line-on-rulescript-type-hinting-in-rule-docs

jonasfreimuth commented May 13, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 13, 2026 •

edited

Loading

Reviews paused

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

jonasfreimuth commented May 13, 2026

Uh oh!

jonasfreimuth commented May 13, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

jonasfreimuth commented May 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jonasfreimuth commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

QC

AI-assistance disclosure

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

jonasfreimuth commented May 13, 2026

Uh oh!

jonasfreimuth commented May 13, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jonasfreimuth commented May 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jonasfreimuth commented May 13, 2026 •

edited

Loading

coderabbitai Bot commented May 13, 2026 •

edited

Loading