Skip to content

Commit 89a8662

Browse files
committed
fix: Expose the capability name as a FormatString, not a str
Review feedback on #373: consistency with the other v1 fields beats consistency with v0 here. openjd-rs#409 made template::AmountRequirement::name and template::AttributeRequirement::name a FormatString. The first pass kept the Python-facing `name` a `str` and parsed on the way in, on the grounds that v0 models these as AmountCapabilityName / AttributeCapabilityName, both subclasses of v0's FormatString, which subclasses str. That argument looks at the wrong neighbour: every other FormatString-typed field on the v1 template types -- `min`, `max`, `anyOf`, `allOf`, `Action.command` -- is an openjd.expr.FormatString and refuses a bare str. `name` now matches them. This deletes more than it adds. parse_capability_name and its doc comment go away, because the FormatString arrives already parsed, and both constructors go back to being infallible. Validation moves to where it belongs: a malformed name is rejected by FormatString's own constructor rather than by a str-typed field that parses behind the caller's back. __repr__ keeps .raw(), matching Action's treatment of its command. This is a breaking change to the v1 Python API, and two pre-existing tests prove it: TestPickle::test_amount_requirement and test_attribute_requirement both passed `name=` a str, and TestStepTemplate::test_host_requirements compared `.name` to one. All three are updated, so this is a behaviour change and not a refactor. Also from review: the spec edit that changed the documented ModelProfile repr to `revision=v2023_09` was wrong -- PyModelProfile::__repr__ still emits the uppercase-V form (rust-bindings/src/model/profile.rs:397), measured as `ModelProfile(revision=V2023_09, extensions=[EXPR])`. Reverted. The two `SpecificationRevision.v2023_09` corrections in the same block stand: that repr is lowercase (profile.rs:63) and `V2023_09` is not an attribute at all. The divergence between the two reprs is pre-existing and left alone here. Verified: 6245 passed / 24 skipped / 3 xfailed, coverage 94.32%. ruff, black, mypy, cargo fmt and clippy clean. Four mutants, each rebuilt and each caught: reverting the pins to 0.9.0 kills 68 cases, formatting the FormatString in both __repr__ sites kills 2, both getters returning a constant kills 12, and both constructors discarding the supplied name kills 10. Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>
1 parent 5ba4be1 commit 89a8662

5 files changed

Lines changed: 101 additions & 87 deletions

File tree

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

Lines changed: 25 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,6 @@ use openjd_model::template::{
3030
};
3131
use openjd_model::types::{EndOfLine, FileType};
3232

33-
use openjd_expr::format_string::FormatString;
34-
3533
use crate::expr::PyFormatString;
3634

3735
// ── Action ──
@@ -965,25 +963,6 @@ impl PyEnvironment {
965963

966964
// ── HostRequirements / AmountRequirement / AttributeRequirement ──
967965

968-
/// Parse a capability `name` into the `FormatString` the template type
969-
/// now holds (openjd-rs#409).
970-
///
971-
/// The Python-facing `name` stays a `str` holding the raw template text,
972-
/// rather than becoming an `openjd.expr.FormatString` like its `min` / `max`
973-
/// / `anyOf` / `allOf` siblings. v0 models these as `AmountCapabilityName` /
974-
/// `AttributeCapabilityName`, both subclasses of v0's `FormatString`, which
975-
/// subclasses `str` — so exposing a `FormatString` pyclass here would make v0
976-
/// and v1 diverge where they agree, and `.raw()` is what openjd-rs#409
977-
/// prescribes for reading these fields. Nothing is lost: the crate's
978-
/// `Deserialize` parses through `FormatString::new` too.
979-
///
980-
/// The capability-name constraints are not applied here. Upstream checks a
981-
/// name whose value it already knows at template validation, and a resolved
982-
/// one at job creation.
983-
fn parse_capability_name(name: &str) -> PyResult<FormatString> {
984-
FormatString::new(name).map_err(crate::expr::errors::expr_err_to_py)
985-
}
986-
987966
#[cfg_attr(feature = "stub-gen", gen_stub_pyclass(module = "openjd._openjd_rs"))]
988967
#[pyclass(
989968
module = "openjd.model._v1.template",
@@ -1000,19 +979,25 @@ pub(crate) struct PyAmountRequirement {
1000979
impl PyAmountRequirement {
1001980
#[new]
1002981
#[pyo3(signature = (*, name, min=None, max=None))]
1003-
fn new(name: &str, min: Option<PyFormatString>, max: Option<PyFormatString>) -> PyResult<Self> {
1004-
Ok(PyAmountRequirement {
982+
fn new(name: PyFormatString, min: Option<PyFormatString>, max: Option<PyFormatString>) -> Self {
983+
PyAmountRequirement {
1005984
inner: AmountRequirement {
1006-
name: parse_capability_name(name)?,
985+
name: name.inner,
1007986
min: min.map(|fs| fs.inner),
1008987
max: max.map(|fs| fs.inner),
1009988
},
1010-
})
989+
}
1011990
}
1012991

992+
/// `@fmtstring` as of openjd-rs#409: a name may carry expressions, and its
993+
/// §3.3.1.1 constraints are checked on the resolved value. Use `.raw()` for
994+
/// the template text. The job-side `AmountRequirement.name` is the resolved
995+
/// `str`.
1013996
#[getter]
1014-
fn name(&self) -> &str {
1015-
self.inner.name.raw()
997+
fn name(&self) -> PyFormatString {
998+
PyFormatString {
999+
inner: self.inner.name.clone(),
1000+
}
10161001
}
10171002

10181003
#[getter]
@@ -1075,22 +1060,28 @@ impl PyAttributeRequirement {
10751060
#[new]
10761061
#[pyo3(signature = (*, name, any_of=None, all_of=None))]
10771062
fn new(
1078-
name: &str,
1063+
name: PyFormatString,
10791064
any_of: Option<Vec<PyFormatString>>,
10801065
all_of: Option<Vec<PyFormatString>>,
1081-
) -> PyResult<Self> {
1082-
Ok(PyAttributeRequirement {
1066+
) -> Self {
1067+
PyAttributeRequirement {
10831068
inner: AttributeRequirement {
1084-
name: parse_capability_name(name)?,
1069+
name: name.inner,
10851070
any_of: any_of.map(|v| v.into_iter().map(|fs| fs.inner).collect()),
10861071
all_of: all_of.map(|v| v.into_iter().map(|fs| fs.inner).collect()),
10871072
},
1088-
})
1073+
}
10891074
}
10901075

1076+
/// `@fmtstring` as of openjd-rs#409: a name may carry expressions, and its
1077+
/// §3.3.2.1 constraints are checked on the resolved value. Use `.raw()` for
1078+
/// the template text. The job-side `AttributeRequirement.name` is the
1079+
/// resolved `str`.
10911080
#[getter]
1092-
fn name(&self) -> &str {
1093-
self.inner.name.raw()
1081+
fn name(&self) -> PyFormatString {
1082+
PyFormatString {
1083+
inner: self.inner.name.clone(),
1084+
}
10941085
}
10951086

10961087
#[getter]

‎specs/python-model-interface.md‎

Lines changed: 13 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -795,10 +795,10 @@ cancel.notify_period_in_seconds # Optional[int]
795795
Job-time host requirements. Distinct from the template-time
796796
``HostRequirements`` / ``AmountRequirement`` / ``AttributeRequirement``
797797
(see `openjd.model._v1.template`): the template-time variants carry
798-
unresolved ``FormatString`` values for ``min`` / ``max`` / ``anyOf`` /
799-
``allOf`` and a raw, possibly-expression-bearing ``name``, while these
800-
job-time variants carry the post-``create_job`` resolved ``str`` name and the
801-
resolved ``f64`` (amounts) and ``str`` (attributes) values.
798+
unresolved ``FormatString`` values for ``name``, ``min`` / ``max`` / ``anyOf``
799+
/ ``allOf``, while these job-time variants carry the post-``create_job``
800+
resolved ``str`` name and the resolved ``f64`` (amounts) and ``str``
801+
(attributes) values.
802802

803803
```python
804804
hr = step.host_requirements # alias: step.hostRequirements
@@ -956,12 +956,12 @@ hr.amounts # Optional[list[AmountRequirement]]
956956
hr.attributes # Optional[list[AttributeRequirement]]
957957

958958
amt = hr.amounts[0]
959-
amt.name # str — raw template text, may hold expressions
959+
amt.name # FormatString — raw, may hold expressions
960960
amt.min # Optional[FormatString]
961961
amt.max # Optional[FormatString]
962962

963963
attr = hr.attributes[0]
964-
attr.name # str — raw template text, may hold expressions
964+
attr.name # FormatString — raw, may hold expressions
965965
attr.any_of # Optional[list[FormatString]] (alias: anyOf)
966966
attr.all_of # Optional[list[FormatString]] (alias: allOf)
967967
```
@@ -980,15 +980,13 @@ when the name's value becomes known:
980980

981981
A name is resolved at job creation, so only symbols available there are in
982982
scope for it: `Task.Param.*` in a name is rejected at decode as an undefined
983-
variable even where the same symbol is valid elsewhere in the step. The
984-
job-time `AmountRequirement.name` / `AttributeRequirement.name` are the
985-
resolved `str`.
983+
variable even where the same symbol is valid elsewhere in the step.
986984

987-
The Python-facing `name` is a `str` holding the raw template text, not an
988-
`openjd.expr.FormatString`, so it mirrors v0 where `AmountCapabilityName` and
989-
`AttributeCapabilityName` subclass v0's `FormatString`, itself a `str`
990-
subclass. Constructing one parses the name, so a malformed format string
991-
raises `ExpressionError`.
985+
`name` is an `openjd.expr.FormatString`, like every other FormatString-typed
986+
field on the template types, so reading the template text needs `.raw()` and
987+
constructing one needs `FormatString(...)` rather than a bare `str`. On 0.9.0
988+
it was a `str` in both directions. The job-side `AmountRequirement.name` /
989+
`AttributeRequirement.name` are still `str`: they hold the resolved name.
992990

993991
### `StepDependency`
994992

@@ -1396,7 +1394,7 @@ from openjd.model._v1.types import ModelExtension, ValidationContext
13961394
template = decode_job_template(template={...}, supported_extensions=["EXPR"])
13971395

13981396
# 2. Read the template's declared profile back out.
1399-
profile = template.profile # ModelProfile(revision=v2023_09, extensions=[EXPR])
1397+
profile = template.profile # ModelProfile(revision=V2023_09, extensions=[EXPR])
14001398
profile.revision # SpecificationRevision.v2023_09
14011399
profile.extensions # [ModelExtension.EXPR]
14021400
profile.has_extension(ModelExtension.EXPR) # True

‎src/openjd/_openjd_rs.pyi‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2772,15 +2772,22 @@ class TemplateAction:
27722772
@typing.final
27732773
class TemplateAmountRequirement:
27742774
@property
2775-
def name(self) -> builtins.str: ...
2775+
def name(self) -> FormatString:
2776+
r"""
2777+
`@fmtstring` as of openjd-rs#409: a name may carry expressions, and its
2778+
§3.3.1.1 constraints are checked on the resolved value. Use `.raw()` for
2779+
the template text. The job-side `AmountRequirement.name` is the resolved
2780+
`str`.
2781+
"""
2782+
27762783
@property
27772784
def min(self) -> typing.Optional[FormatString]: ...
27782785
@property
27792786
def max(self) -> typing.Optional[FormatString]: ...
27802787
def __new__(
27812788
cls,
27822789
*,
2783-
name: builtins.str,
2790+
name: FormatString,
27842791
min: typing.Optional[FormatString] = None,
27852792
max: typing.Optional[FormatString] = None,
27862793
) -> TemplateAmountRequirement: ...
@@ -2790,7 +2797,14 @@ class TemplateAmountRequirement:
27902797
@typing.final
27912798
class TemplateAttributeRequirement:
27922799
@property
2793-
def name(self) -> builtins.str: ...
2800+
def name(self) -> FormatString:
2801+
r"""
2802+
`@fmtstring` as of openjd-rs#409: a name may carry expressions, and its
2803+
§3.3.2.1 constraints are checked on the resolved value. Use `.raw()` for
2804+
the template text. The job-side `AttributeRequirement.name` is the
2805+
resolved `str`.
2806+
"""
2807+
27942808
@property
27952809
def any_of(self) -> typing.Optional[builtins.list[FormatString]]: ...
27962810
@property
@@ -2802,7 +2816,7 @@ class TemplateAttributeRequirement:
28022816
def __new__(
28032817
cls,
28042818
*,
2805-
name: builtins.str,
2819+
name: FormatString,
28062820
any_of: typing.Optional[typing.Sequence[FormatString]] = None,
28072821
all_of: typing.Optional[typing.Sequence[FormatString]] = None,
28082822
) -> TemplateAttributeRequirement: ...

‎test/openjd/model_v1/test_parse.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1000,9 +1000,9 @@ def _template(
10001000
def test_a_parameter_dependent_name_decodes(
10011001
self, host_requirements: dict[str, Any], expected: str
10021002
) -> None:
1003-
"""The name reaches the decoded template as its raw text. ``name`` stays a
1004-
``str`` on the Python side even though the Rust field is a ``FormatString``,
1005-
matching v0 where ``AmountCapabilityName`` subclasses a ``str``."""
1003+
"""The name reaches the decoded template as a ``FormatString`` carrying the raw
1004+
text, matching its ``min`` / ``max`` / ``anyOf`` / ``allOf`` siblings. On 0.9.0
1005+
it was a ``str``."""
10061006
decoded = decode_job_template(
10071007
template=self._template(host_requirements, parameter_definitions=self._PARAMS)
10081008
)
@@ -1012,7 +1012,7 @@ def test_a_parameter_dependent_name_decodes(
10121012
requirements.amounts if "amounts" in host_requirements else requirements.attributes
10131013
)
10141014
assert entries is not None
1015-
assert entries[0].name == expected
1015+
assert entries[0].name.raw() == expected
10161016

10171017
@pytest.mark.parametrize(
10181018
"name,expected_message",
@@ -1131,7 +1131,7 @@ def test_a_name_built_only_from_let_bindings_with_literal_values_is_static(self)
11311131
assert requirements is not None
11321132
amounts = requirements.amounts
11331133
assert amounts is not None
1134-
assert amounts[0].name == "{{ n }}"
1134+
assert amounts[0].name.raw() == "{{ n }}"
11351135

11361136
def test_a_partly_static_name_gets_a_length_lower_bound(self) -> None:
11371137
"""The literal runs of a name give a guaranteed minimum resolved length, so a

‎test/openjd/model_v1/test_template_types.py‎

Lines changed: 40 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -210,15 +210,17 @@ def test_host_requirements(self):
210210
amts = hr.amounts
211211
assert amts is not None and len(amts) == 1
212212
assert isinstance(amts[0], AmountRequirement)
213-
assert amts[0].name == "amount.worker.vcpu"
213+
assert isinstance(amts[0].name, FormatString)
214+
assert amts[0].name.raw() == "amount.worker.vcpu"
214215
assert isinstance(amts[0].min, FormatString)
215216
assert amts[0].min.raw() == "4"
216217
assert amts[0].max.raw() == "8"
217218
# attributes
218219
attrs = hr.attributes
219220
assert attrs is not None and len(attrs) == 2
220221
assert isinstance(attrs[0], AttributeRequirement)
221-
assert attrs[0].name == "attr.worker.os.family"
222+
assert isinstance(attrs[0].name, FormatString)
223+
assert attrs[0].name.raw() == "attr.worker.os.family"
222224
assert attrs[0].any_of[0].raw() == "linux"
223225
assert attrs[0].anyOf[0].raw() == "linux" # camelCase alias
224226
assert attrs[1].all_of[0].raw() == "x86_64"
@@ -417,7 +419,7 @@ def test_step_dependency(self):
417419

418420
def test_amount_requirement(self):
419421
ar = AmountRequirement(
420-
name="amount.worker.vcpu",
422+
name=FormatString("amount.worker.vcpu"),
421423
min=FormatString("4"),
422424
max=FormatString("8"),
423425
)
@@ -428,7 +430,7 @@ def test_amount_requirement(self):
428430

429431
def test_attribute_requirement(self):
430432
ar = AttributeRequirement(
431-
name="attr.worker.os.family",
433+
name=FormatString("attr.worker.os.family"),
432434
any_of=[FormatString("linux")],
433435
)
434436
loaded = pickle.loads(pickle.dumps(ar))
@@ -484,16 +486,16 @@ def test_pickle_uses_template_module_path(self):
484486
assert b"TemplateStepDependency" in data
485487

486488

487-
class TestCapabilityNameIsAFormatStringUnderneath:
489+
class TestCapabilityNameIsAFormatString:
488490
"""``template::AmountRequirement::name`` and
489491
``template::AttributeRequirement::name`` became ``FormatString`` in openjd-model
490-
0.10.0 (openjd-rs#409). The Python-facing ``name`` stays a ``str`` holding the raw
491-
template text, mirroring v0; see ``parse_capability_name`` in
492-
``rust-bindings/src/model/template_types.rs`` for why.
492+
0.10.0 (openjd-rs#409), and the Python-facing ``name`` follows, matching its
493+
``min`` / ``max`` / ``anyOf`` / ``allOf`` siblings and every other
494+
FormatString-typed field on the template types.
493495
494-
One behaviour change falls out of that adaptation rather than out of upstream: the
495-
constructor parses the name, so a malformed format string now raises where 0.9.0
496-
stored the text unexamined.
496+
On 0.9.0 ``name`` was a ``str`` in both directions. The job-side
497+
``AmountRequirement.name`` / ``AttributeRequirement.name`` are still ``str``: they
498+
hold the resolved name.
497499
"""
498500

499501
@pytest.mark.parametrize("cls", [AmountRequirement, AttributeRequirement])
@@ -506,17 +508,27 @@ class TestCapabilityNameIsAFormatStringUnderneath:
506508
pytest.param("prefix.{{Param.Attr}}.suffix", id="interpolated"),
507509
],
508510
)
509-
def test_the_name_round_trips_as_its_raw_text(self, cls: type, name: str) -> None:
510-
assert cls(name=name).name == name
511-
assert isinstance(cls(name=name).name, str)
511+
def test_the_name_is_a_format_string_carrying_the_raw_text(self, cls: type, name: str) -> None:
512+
got = cls(name=FormatString(name)).name
513+
assert isinstance(got, FormatString)
514+
assert got.raw() == name
512515

513516
@pytest.mark.parametrize("cls", [AmountRequirement, AttributeRequirement])
514-
def test_a_malformed_format_string_is_rejected(self, cls: type) -> None:
515-
"""``ExpressionError`` specifically, not merely a ``ValueError`` — the binding
516-
routes the parse failure through ``expr_err_to_py`` so it matches every other
517-
format-string parse error in the package."""
517+
def test_a_plain_str_name_is_refused(self, cls: type) -> None:
518+
"""The reason this is worth pinning: ``name`` used to accept a ``str`` on 0.9.0,
519+
so a caller has to wrap it. Refusing it is what makes the field consistent with
520+
its siblings, which have always refused one."""
521+
with pytest.raises(TypeError) as exc_info:
522+
cls(name="amount.worker.vcpu")
523+
assert "not an instance of 'FormatString'" in str(exc_info.value)
524+
525+
@pytest.mark.parametrize("cls", [AmountRequirement, AttributeRequirement])
526+
def test_a_malformed_name_cannot_be_constructed_at_all(self, cls: type) -> None:
527+
"""Validation now sits in ``FormatString`` rather than in the requirement, so a
528+
malformed name is rejected one step earlier than it would have been by a
529+
``str``-typed field that parsed on the way in."""
518530
with pytest.raises(ExpressionError) as exc_info:
519-
cls(name="{{")
531+
cls(name=FormatString("{{"))
520532
assert "Braces mismatch" in str(exc_info.value)
521533

522534
@pytest.mark.parametrize(
@@ -534,16 +546,15 @@ def test_a_malformed_format_string_is_rejected(self, cls: type) -> None:
534546
),
535547
],
536548
)
537-
def test_repr_still_shows_the_raw_text(self, cls: type, expected: str) -> None:
538-
"""The repr went through ``{:?}`` on a ``String`` before and goes through
539-
``{:?}`` on ``.raw()`` now, so it must be unchanged. A mutation that formatted
540-
the ``FormatString`` itself would print its Debug shape instead."""
541-
assert repr(cls(name="{{Param.Attr}}")) == expected
549+
def test_repr_shows_the_raw_text(self, cls: type, expected: str) -> None:
550+
"""``__repr__`` goes through ``.raw()``, matching ``Action``'s treatment of its
551+
``command``. A mutation that formatted the ``FormatString`` itself would print
552+
its Debug shape instead."""
553+
assert repr(cls(name=FormatString("{{Param.Attr}}"))) == expected
542554

543555
@pytest.mark.parametrize("cls", [AmountRequirement, AttributeRequirement])
544556
def test_pickle_round_trips_a_format_string_name(self, cls: type) -> None:
545-
"""``__reduce__`` passes ``name`` back through the constructor, which now
546-
parses. Pins that a format-string name survives the round trip rather than
547-
raising on reconstruction."""
548-
loaded = pickle.loads(pickle.dumps(cls(name="{{Param.Attr}}")))
549-
assert loaded.name == "{{Param.Attr}}"
557+
"""``__reduce__`` passes ``name`` back through the constructor, so it has to hand
558+
back a ``FormatString`` rather than the raw text."""
559+
loaded = pickle.loads(pickle.dumps(cls(name=FormatString("{{Param.Attr}}"))))
560+
assert loaded.name.raw() == "{{Param.Attr}}"

0 commit comments

Comments
 (0)