feat: job scheduling priority via setting and per-rule resource

[nh13]

Adds optional AWS Batch fair-share scheduling priority support at two levels, mapped to submit_job's schedulingPriorityOverride:

• --aws-batch-scheduling-priority — a workflow-level default applied to every job.
• aws_batch_scheduling_priority resource — a per-rule override that takes precedence over the setting (mirrors the batch_queue / aws_batch_task_timeout per-rule pattern).

The value is coerced to an integer and validated to the AWS Batch [0, 9999] range, with errors naming the source (resource vs setting). When neither is set, schedulingPriorityOverride is omitted entirely — submissions on non-fair-share queues are byte-identical to before. Only meaningful on fair-share queues (those with a scheduling policy attached); AWS ignores it otherwise.

snakemake --executor aws-batch --aws-batch-scheduling-priority 50 ...

rule critical_path:
    resources:
        aws_batch_scheduling_priority=100
    ...

Documented under a new "Scheduling Priority (Fair-Share Queues)" section in docs/further.md.

Testing

New TestSubmitSchedulingPriority covers unset-omits-kwarg, setting-only, resource-overrides-setting, resource-alone, non-numeric (resource + setting), out-of-range (resource + setting), negative (lower bound), and the 0 and 9999 boundaries. Full suite: 72 unit tests pass; black + flake8 clean.

Summary by CodeRabbit

• New Features

  • Added AWS Batch fair-share queue scheduling priority support with configurable workflow-level and per-rule settings, with per-rule priorities taking precedence.

• Documentation

  • Added comprehensive guide for scheduling priority configuration with usage examples and details on feature behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8c65544f-609d-459e-9547-d60efe1f34b7

📥 Commits

Reviewing files that changed from the base of the PR and between f708eac and 9e3df94.

📒 Files selected for processing (4)

• docs/further.md
• snakemake_executor_plugin_aws_batch/__init__.py
• snakemake_executor_plugin_aws_batch/batch_job_builder.py
• tests/test_batch_job_builder.py

---

📝 Walkthrough

Walkthrough

This PR adds AWS Batch scheduling priority support for fair-share queues. The feature introduces optional workflow-level and per-rule scheduling priority configuration with validation, resource-level precedence, and comprehensive test coverage ensuring correct behavior and error handling.

Changes

AWS Batch Scheduling Priority for Fair-Share Queues

Layer / File(s)	Summary
Feature documentation: scheduling priority for fair-share queues docs/further.md	New section documenting schedulingPriorityOverride behavior on fair-share queues, workflow-level --aws-batch-scheduling-priority flag, per-rule aws_batch_scheduling_priority resource, precedence rules, and example configurations.
ExecutorSettings configuration field snakemake_executor_plugin_aws_batch/__init__.py	ExecutorSettings dataclass extended with optional scheduling_priority: Optional[int] field including help text for CLI exposure and workflow-level default behavior.
Scheduling priority submission logic snakemake_executor_plugin_aws_batch/batch_job_builder.py	BatchJobBuilder.submit() implements precedence (per-rule resource overrides workflow setting), validates integer value within [0, 9999], raises WorkflowError on invalid input, and conditionally injects schedulingPriorityOverride into job parameters.
Scheduling priority test coverage tests/test_batch_job_builder.py	Helper functions configure builder with optional priorities; TestSubmitSchedulingPriority verifies omission when unset, forwarding when set, resource precedence, zero priority handling, and error cases (non-numeric values, out-of-range bounds) with appropriate error messages and submit_job non-invocation on failure.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• cademirch

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding job scheduling priority support via both a workflow-level setting and per-rule resource override.
Docstring Coverage	✅ Passed	Docstring coverage is 93.33% which is sufficient. The required threshold is 80.00%.
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.

_{✏️ 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

• X
• Mastodon
• Reddit
• LinkedIn

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

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[nh13]

@cademirch this should be ready for your review if you have time.