Version 0.9.3

[rsgalloway]

This pull request introduces several new features, improvements, and documentation updates focused on explicit stepped frame range support, negative frame handling, and project performance infrastructure. Notably, it adds canonical stepped range formatting (%x), enables parsing and formatting of signed frame numbers, and integrates benchmark tooling with CI workflows and documentation publishing. The documentation and contributor guidelines have been expanded to reflect these changes and to provide clear guidance for performance-sensitive development.

New Features and Syntax Support:

• Adds canonical stepped frame range formatting via %x (e.g., 1-10x2,20-30x5,42) and explicit stepped range parsing for serialized and embedded sequence references, including support for negative frame numbers when PYSEQ_ALLOW_NEGATIVE_FRAMES=1 is set. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13]

Performance and Benchmarking Infrastructure:

• Introduces a comprehensive benchmark workflow (.github/workflows/benchmarks.yml) that runs on pull requests, scheduled intervals, and manual triggers. It compares candidate and baseline performance, enforces regression thresholds, and posts results to pull requests.
• Adds a documentation publishing workflow (.github/workflows/publish-docs.yml) to build and deploy documentation and benchmark reports to GitHub Pages.
• Updates contributor guidelines in CONTRIBUTING.md to emphasize performance, benchmarking policy, and recommended workflows for performance-sensitive changes.

Documentation and Contributor Guidance:

• Expands and clarifies documentation across README.md, docs/formatting.md, docs/examples.md, docs/cli-tools.md, and docs/frame-patterns.md to cover the new stepped range syntax, negative frame support, and usage examples. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13]
• Adds a "Contributing" section and link to the README.md. [1] [2]

Continuous Integration Improvements:

• Restricts the test workflow in .github/workflows/tests.yml to only run on relevant paths for improved CI efficiency.

Changelog:

• Updates CHANGELOG.md to reflect all major new features, syntax changes, and infrastructure improvements in version 0.9.3.

[Copilot]

Pull request overview

This PR packages PySeq v0.9.3, expanding the frame-range syntax (stepped ranges and signed frames) across the core library, CLI tooling, documentation, and adding benchmark + GitHub Pages publishing infrastructure.

Changes:

• Added stepped serialized frame-range parsing/formatting (%x) and signed frame support, refactoring range logic into a new pyseq.frange helper module.
• Updated sequence resolution/uncompression to understand the new range forms, and expanded CLI + unit/regression test coverage (including negative filenames).
• Introduced benchmark scripts, performance regression tests, and GitHub Actions workflows for scheduled benchmarks and Pages publishing.

Reviewed changes

Copilot reviewed 31 out of 32 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
lib/pyseq/frange.py	New shared helpers for parsing/formatting extended (stepped/signed) frame ranges.
lib/pyseq/seq.py	Core sequence logic updates: signed padding behavior, %x formatting, and extended-range uncompression parsing.
lib/pyseq/util.py	Updates to sequence resolution/reference parsing and subset construction for new range syntax.
lib/pyseq/config.py	Expands default frame token regex to match signed frame numbers in filenames.
lib/pyseq/__init__.py	Version bump to 0.9.3.
tests/test_pyseq.py	Adds coverage for stepped ranges, negative frames, and resolve_sequence_reference; moves performance test coverage out.
tests/test_performance.py	New coarse performance regression tests for key hot paths (construction, missing formatting, stepped ranges).
tests/test_lss.py	Adds CLI test asserting %x renders compact stepped ranges.
tests/test_scopy.py	Adds CLI copy test coverage for negative serialized ranges.
tests/test_smove.py	Adds CLI move test coverage for negative serialized ranges.
tests/test_srm.py	Adds CLI remove test coverage for negative serialized ranges.
tests/files/stepA.1001.exr	Adds stepped-range fixture file for discovery/reference tests.
tests/files/stepA.1004.exr	Adds stepped-range fixture file for discovery/reference tests.
tests/files/stepA.1007.exr	Adds stepped-range fixture file for discovery/reference tests.
tests/files/stepA.1010.exr	Adds stepped-range fixture file for discovery/reference tests.
tests/files/negA.-0001.exr	Adds negative-frame fixture file for signed filename support tests.
tests/files/negA.-0002.exr	Adds negative-frame fixture file for signed filename support tests.
tests/files/negA.0000.exr	Adds zero-frame fixture file for signed filename support tests.
tests/files/negA.0001.exr	Adds positive-frame fixture file for signed filename support tests.
scripts/benchmarks_core.py	Adds a core-library benchmark runner producing JSON and/or Markdown summaries.
scripts/benchmarks_cli.py	Adds CLI benchmark runner covering several console tools with smoke/full profiles.
scripts/build_pages_site.py	Generates a Jekyll-friendly markdown tree and integrates benchmark artifacts into Pages output.
.github/workflows/benchmarks.yml	Adds scheduled/manual benchmark workflow with artifact upload and summary output.
.github/workflows/publish-docs.yml	Adds GitHub Pages publishing workflow building docs + benchmark reports.
docs/performance.md	Documents performance strategy, regression tests vs benchmarks, and result formats.
docs/formatting.md	Documents %x and extended serialized range syntax (including signed frames).
docs/examples.md	Adds examples for stepped and signed serialized ranges.
docs/cli-tools.md	Updates CLI usage examples to include stepped serialized range syntax.
docs/README.md	Adds performance guide link.
README.md	Adds README examples and range syntax summary for stepped/signed serialized ranges.
CHANGELOG.md	Adds 0.9.3 release notes.
.gitignore	Ignores additional agent/cache directories.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 31 changed files in this pull request and generated 2 comments.

[github-actions]

Benchmark Comparison

No benchmark exceeded the +3.00% and +0.005s regression thresholds.

pyseq benchmark comparison

Baseline: detached 623e6ae Candidate: detached fcd31df
Baseline lib: /home/runner/work/pyseq/pyseq/baseline/lib Candidate lib: /home/runner/work/pyseq/pyseq/lib
Baseline python: /opt/hostedtoolcache/Python/3.11.15/x64/bin/python Candidate python: /opt/hostedtoolcache/Python/3.11.15/x64/bin/python
Baseline pyseq: /home/runner/work/pyseq/pyseq/baseline/lib/pyseq/__init__.py Candidate pyseq: /home/runner/work/pyseq/pyseq/lib/pyseq/__init__.py
Baseline pyseq.seq: /home/runner/work/pyseq/pyseq/baseline/lib/pyseq/seq.py Candidate pyseq.seq: /home/runner/work/pyseq/pyseq/lib/pyseq/seq.py
Summary: 24 benchmarks median delta -2.92% max regression -0.53%

Benchmark	Baseline Median (s)	Candidate Median (s)	Delta (s)	Delta (%)
get_sequences_dir_contiguous_100	0.001882	0.001849	-0.000034	-1.78%
get_sequences_dir_contiguous_1000	0.018787	0.018298	-0.000490	-2.61%
get_sequences_dir_contiguous_10000	0.205739	0.197070	-0.008669	-4.21%
get_sequences_dir_mixed_100	0.002293	0.002202	-0.000092	-4.00%
get_sequences_dir_mixed_1000	0.018126	0.017576	-0.000550	-3.03%
get_sequences_dir_mixed_10000	0.190242	0.185702	-0.004539	-2.39%
get_sequences_list_contiguous_100	0.001694	0.001651	-0.000042	-2.49%
get_sequences_list_contiguous_1000	0.017198	0.016755	-0.000443	-2.58%
get_sequences_list_contiguous_10000	0.192889	0.180681	-0.012208	-6.33%
get_sequences_list_mixed_100	0.002074	0.001995	-0.000079	-3.80%
get_sequences_list_mixed_1000	0.016648	0.015908	-0.000740	-4.45%
get_sequences_list_mixed_10000	0.173950	0.169983	-0.003967	-2.28%
lss_contiguous_100	0.035412	0.034588	-0.000825	-2.33%
lss_contiguous_1000	0.054078	0.053789	-0.000289	-0.53%
lss_contiguous_10000	0.250151	0.240554	-0.009596	-3.84%
lss_mixed_100	0.035738	0.034414	-0.001324	-3.70%
lss_mixed_1000	0.053622	0.052003	-0.001619	-3.02%
lss_mixed_10000	0.236067	0.226136	-0.009931	-4.21%
resolve_sequence_contiguous_100	0.001795	0.001738	-0.000057	-3.18%
resolve_sequence_contiguous_1000	0.018087	0.017526	-0.000560	-3.10%
resolve_sequence_contiguous_10000	0.192430	0.187366	-0.005064	-2.63%
resolve_sequence_mixed_100	0.001369	0.001345	-0.000024	-1.73%
resolve_sequence_mixed_1000	0.013467	0.013086	-0.000380	-2.83%
resolve_sequence_mixed_10000	0.141645	0.139397	-0.002248	-1.59%

[Copilot]

Pull request overview

Copilot reviewed 44 out of 45 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (2)

tests/test_smove.py:250

• This test enables PYSEQ_ALLOW_NEGATIVE_FRAMES=1 even though it only uses positive embedded ranges ("plate.2-4.rgb" / "beauty.20-22.rgb"). Since negative frames are opt-in, avoid setting the flag here so the default behavior stays covered.
  tests/test_scopy.py:147
• This test enables PYSEQ_ALLOW_NEGATIVE_FRAMES=1 even though it only uses positive embedded ranges ("plate.2-4.rgb" / "beauty.20-22.rgb"). Since negative frames are opt-in, keep the default environment for this test case.

[Copilot]

Pull request overview

Copilot reviewed 52 out of 53 changed files in this pull request and generated 4 comments.