Skip to content

Commit 99fdecf

Browse files
committed
docs: narrow the override wording and pin the eager validation
Signed-off-by: David Leong <leongdl@amazon.com>
1 parent 6485825 commit 99fdecf

4 files changed

Lines changed: 28 additions & 4 deletions

File tree

‎rust-bindings/src/model/step_param_space.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,9 @@ impl PyStepParameterSpaceIterator {
139139
/// `CHUNK[INT]` parameter and turns adaptive chunking off, so a chunked space
140140
/// can be walked at a caller-chosen granularity. Pass `1` to iterate individual
141141
/// tasks. Ignored when the space has no chunked parameter, matching the
142-
/// pure-Python reference.
142+
/// pure-Python reference — though a non-positive value is still rejected in
143+
/// that case, since validating an argument is cheaper to reason about than
144+
/// silently discarding a bad one.
143145
///
144146
/// Without this, a statically chunked space could only be walked at the
145147
/// template's own chunk size: `chunks_default_task_count` is settable for

‎specs/python-model-interface.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1157,9 +1157,15 @@ non-mutating.
11571157
space can be walked at a granularity the caller picks. Pass `1` to
11581158
iterate individual tasks — a `1-20` range chunked five at a time then
11591159
yields `1-1`, `2-2`, … instead of `1-5`, `6-10`, …. It is ignored when
1160-
the space has no chunked parameter, matching the pure-Python reference.
1160+
the space has no chunked parameter, matching the pure-Python reference,
1161+
although a non-positive value is still rejected in that case.
11611162
Iteration observes it, and `len()` counts the overridden granularity.
11621163

1164+
The rendered form of a chunk depends on `rangeConstraint`, which matters
1165+
because these are strings a consumer parses and may feed back through
1166+
`__contains__`. A single-task chunk is `"1-1"` under `CONTIGUOUS` and a
1167+
bare `"1"` under `NONCONTIGUOUS`.
1168+
11631169
It is currently the only way to change the chunk size of a *static*
11641170
chunked space: the `chunks_default_task_count` setter accepts adaptive
11651171
spaces only, and raises `ValueError` otherwise.

‎src/openjd/_openjd_rs.pyi‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2390,7 +2390,8 @@ class StepParameterSpaceIterator:
23902390
`CHUNK[INT]` parameter and turns adaptive chunking off, so a chunked space
23912391
can be walked at a caller-chosen granularity. Pass `1` to iterate individual
23922392
tasks. Ignored when the space has no chunked parameter, matching the
2393-
pure-Python reference.
2393+
pure-Python reference -- though a non-positive value is still rejected in
2394+
that case.
23942395
23952396
Without this, a statically chunked space could only be walked at the
23962397
template's own chunk size: `chunks_default_task_count` is settable for

‎test/openjd/model_v1/test_step_param_space_iter.py‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -744,7 +744,11 @@ def test_indexing_observes_the_override(self) -> None:
744744
def test_a_contiguous_space_refuses_indexing_with_or_without_the_override(self) -> None:
745745
"""Pre-existing behaviour the override does not change: openjd-model requires
746746
sequential iteration for contiguous chunking, so ``get`` always declines.
747-
Pinned here so a future change to random access is a deliberate one."""
747+
Pinned here so a future change to random access is a deliberate one. Its
748+
counterpart is ``test_known_gaps.py::test_a_contiguous_chunked_space_supports_indexing``,
749+
a strict xfail asserting the opposite: closing that gap fails there as an xpass
750+
*and* here as a hard assertion, so both move together, along with the
751+
limitation noted in ``specs/python-model-interface.md``."""
748752
for override in (None, 1):
749753
it = StepParameterSpaceIterator(
750754
step=self._step(self._STATIC), chunks_task_count_override=override
@@ -778,6 +782,17 @@ def test_override_turns_adaptive_chunking_off(self) -> None:
778782
assert len(overridden) == 10
779783
assert self._frames(overridden) == [f"{n}-{n}" for n in range(1, 11)]
780784

785+
def test_a_non_positive_override_is_rejected_even_when_it_would_be_ignored(self) -> None:
786+
"""The validation runs before the space is inspected, so an unchunked space still
787+
rejects 0 rather than silently discarding it. The reference does not validate at
788+
all; this is the documented divergence, pinned so it stays deliberate."""
789+
space = StepParameterSpace(
790+
taskParameterDefinitions={"Frame": {"type": "INT", "range": [1, 2, 3]}}
791+
)
792+
with pytest.raises(ValueError) as excinfo:
793+
StepParameterSpaceIterator(space=space, chunks_task_count_override=0)
794+
assert str(excinfo.value) == "chunks_task_count_override must be a positive integer."
795+
781796
def test_override_is_ignored_when_the_space_has_no_chunked_parameter(self) -> None:
782797
"""Reference behaviour: the override only applies to a space that chunks."""
783798
space = StepParameterSpace(

0 commit comments

Comments
 (0)