Skip to content

Commit 0d692a7

Browse files
committed
docs: halve the comment volume on the new range-element code
97 comment lines to 122 of code across the added blocks, with the format function at 32 comment lines around 4 of code. The rationale was correct and in the wrong file: the normalize/quantize/str/format(v, 'f') comparison that justified not carrying a Decimal belongs in the commit message, where it is searchable and does not age when the function is edited. Now 60 comment lines to 123. Nothing true was dropped -- the spec citations, the lookahead's purpose, and the non-numeric fallthrough all still read. Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>
1 parent 3bc3f4b commit 0d692a7

3 files changed

Lines changed: 33 additions & 72 deletions

File tree

‎src/openjd/model/v2023_09/_model.py‎

Lines changed: 17 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1245,42 +1245,27 @@ def _validate_target_runtime_seconds(cls, value: Any, info: ValidationInfo) -> A
12451245
return validate_int_fmtstring_field(value, ge=0, context=context)
12461246

12471247

1248-
# Redundant leading zeros in the integer digits of a numeric string, keeping any
1249-
# sign and always leaving one digit behind: '02.50' -> '2.50', '007' -> '7',
1250-
# '000' -> '0'. The lookahead is what leaves the last digit, and it also declines
1251-
# to touch '0.50', whose single zero is not redundant.
1248+
# '02.50' -> '2.50', '007' -> '7', '000' -> '0'. The lookahead leaves the last
1249+
# digit, so '0.50' keeps the zero that is its integer part.
12521250
_REDUNDANT_LEADING_ZEROS = re.compile(r"^([+-]?)0+(?=[0-9])")
12531251

12541252

12551253
def _normalized_range_element(elem: str, to_int: bool) -> Any:
12561254
"""The value an ``<intstring>``/``<floatstring>`` range element denotes.
12571255
1258-
An ``<intstring>`` becomes the ``int`` it denotes. A ``<floatstring>`` keeps
1259-
its source text, less any redundant leading zeros, because the number of
1260-
fractional digits it was written with is part of what it asks for -- an
1261-
element written ``'2.50'`` is asking for ``2.50`` on the command line, and a
1262-
renderer told ``2.5`` instead has been given a different string. Returns the
1263-
element unchanged when it does not denote a number.
1256+
An ``<intstring>`` becomes an ``int``. A ``<floatstring>`` keeps its text less
1257+
redundant leading zeros, so the decimal places it was written with survive
1258+
(§7.5). Returns the element unchanged when it does not denote a number.
12641259
"""
12651260
try:
12661261
if to_int:
1267-
# int() ignores leading zeros, and an <intstring> has no fractional
1268-
# digits to preserve, so the parsed value carries everything.
1269-
return int(elem)
1270-
# A <floatstring> renders as text, so the parse is only a check that the
1271-
# element denotes a float at all. Deliberately not carried in a Decimal:
1272-
# rendering one requires choosing a notation, and every choice available
1273-
# is either context-sensitive (``normalize`` and ``quantize`` round to
1274-
# ``getcontext().prec``), notation-unstable (``str`` switches to an
1275-
# exponent below 1e-6), or unbounded in the exponent (``format(v, 'f')``
1276-
# expands '1e999999999' to ~10**9 characters). Text needs none of those
1277-
# decisions: it renders as the author wrote it.
1262+
return int(elem) # int() already drops leading zeros
1263+
# Parsed only to check it is a number; the text is what renders. Not a
1264+
# Decimal -- re-rendering one is context-sensitive and unbounded (§7.5).
12781265
float(elem)
12791266
except ValueError:
1280-
# Not a number at all -- e.g. a format string that resolved to
1281-
# non-numeric text. A literal range is already checked against its
1282-
# element type at template parse time, so leave such a value to the
1283-
# existing behaviour rather than adding a rejection path here.
1267+
# A resolved format string can be non-numeric. Literals are checked at
1268+
# template parse time, so carry it through rather than rejecting here.
12841269
return elem
12851270
return _REDUNDANT_LEADING_ZEROS.sub(r"\1", elem)
12861271

@@ -1297,27 +1282,14 @@ class RangeListTaskParameterDefinition(OpenJDModel_v2023_09):
12971282
@field_validator("range", mode="before")
12981283
@classmethod
12991284
def _normalize_numeric_range_elements(cls, value: Any, info: ValidationInfo) -> Any:
1300-
# §3.4.1.1/§3.4.1.2: an <IntRangeList> element is `<integer> |
1301-
# <intstring>` and a <FloatRangeList> element is `<float> |
1302-
# <floatstring>`, where an <intstring>/<floatstring> is "a string whose
1303-
# value is the string representation of" a number (§2.3, §2.4). Leading
1304-
# zeros are not part of the number such an element denotes, and Python
1305-
# was keeping them, which reaches a task command line as `--frame 02`.
1285+
# §7.5: a string-form range element loses redundant leading zeros and
1286+
# keeps its decimal places, so '02' is the value 2 and '02.50' renders
1287+
# `2.50`. Numeric literals carry no such request and are left as parsed;
1288+
# STRING and PATH ranges have no numeric form at all.
13061289
#
1307-
# Trailing zeros are kept. They are the reason the string form exists:
1308-
# a <floatstring> is how a template asks for a fixed number of decimal
1309-
# places, so '2.50' must render `2.50` and not `2.5`. The already-landed
1310-
# EXPR/jobs/expr1.3.4--float-passthrough fixture pins the same rule for
1311-
# a FLOAT parameter default.
1312-
#
1313-
# Applied on the instantiation target so every inbound range path is
1314-
# covered: a literal list, a range-expression expansion, and an RFC 0006
1315-
# typed whole-field resolution all funnel through this model.
1316-
#
1317-
# Numeric elements are left exactly as parsed. A FLOAT range of [1.0]
1318-
# renders 1.0, which openjd-rs also does and the conformance suite pins
1319-
# (base/jobs/3.4--float-parameter). STRING and PATH ranges are text by
1320-
# definition and are never touched.
1290+
# On the instantiation target so all three inbound paths are covered: a
1291+
# literal list, a range-expression expansion, and RFC 0006 whole-field
1292+
# resolution.
13211293
param_type = info.data.get("type")
13221294
if not isinstance(value, list) or param_type not in (
13231295
TaskParameterType.INT,

‎test/openjd/model_v0/test_step_param_space_iter.py‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -613,8 +613,7 @@ def test_int_range_intstring_elements(self) -> None:
613613

614614
def test_float_range_floatstring_elements(self) -> None:
615615
# WHEN a FLOAT range is written with <floatstring> elements
616-
# THEN each task gets the element's own text, less redundant leading
617-
# zeros. The decimal places it was written with are what it asks for.
616+
# THEN each task gets the element's text, less redundant leading zeros
618617
assert self._task_values("FLOAT", ["1.5", "02.50", "3.500"]) == ["1.5", "2.50", "3.500"]
619618

620619
def test_float_range_numeric_literals_keep_their_scale(self) -> None:

‎test/openjd/model_v0/v2023_09/test_parameter_space.py‎

Lines changed: 15 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -441,20 +441,12 @@ def test_list_form_range_is_still_capped(self, model: Any, obj: dict[str, Any])
441441

442442

443443
class TestRangeListElementNormalization:
444-
"""§3.4.1.1/§3.4.1.2: an `<IntRangeList>` element is `<integer> | <intstring>`
445-
and a `<FloatRangeList>` element is `<float> | <floatstring>`. An
446-
`<intstring>`/`<floatstring>` is "a string whose value is the string
447-
representation of" a number (§2.3, §2.4).
448-
449-
Leading zeros are not part of the number, so they go: a range of
450-
`['1', '02', '003']` is the task values 1, 2 and 3, and keeping the text
451-
renders `--frame 02` on a command line.
452-
453-
Trailing zeros stay. They are why the string form exists — a `<floatstring>`
454-
is how a template asks for a fixed number of decimal places, so `'2.50'`
455-
renders `2.50`, and a renderer handed `2.5` has been given a different
456-
string. `EXPR/jobs/expr1.3.4--float-passthrough` pins the same rule for a
457-
FLOAT parameter default.
444+
"""§7.5 on a range element: leading zeros go, decimal places stay.
445+
446+
`['1', '02', '003']` is the task values 1, 2 and 3; keeping the text renders
447+
`--frame 02`. But `'2.50'` renders `2.50`, because the string form is how a
448+
template asks for a fixed number of decimal places —
449+
`EXPR/jobs/expr1.3.4--float-passthrough` pins that for a FLOAT default.
458450
"""
459451

460452
@pytest.mark.parametrize(
@@ -486,8 +478,8 @@ def test_intstring_elements_carry_their_value(self, param_type: str) -> None:
486478
pytest.param("+02.50", "+2.50", id="explicit plus sign is kept"),
487479
pytest.param("007", "7", id="leading zeros on a whole number"),
488480
pytest.param("100", "100", id="a zero that is a significant digit"),
489-
# A single leading zero before the point is not redundant, and the
490-
# last digit of an all-zero integer part is not either.
481+
# Neither the zero before the point nor the last of an all-zero
482+
# integer part is redundant.
491483
pytest.param("0.50", "0.50", id="the necessary leading zero stays"),
492484
pytest.param("000", "0", id="all zeros keeps one"),
493485
pytest.param("0", "0", id="bare zero"),
@@ -525,17 +517,15 @@ def test_floatstring_elements_keep_their_scale(self, element: str, expected: str
525517
),
526518
)
527519
def test_a_huge_exponent_costs_only_its_own_characters(self, element: str) -> None:
528-
# WHEN the instantiation target parses a <floatstring> whose plain-notation
529-
# form would be enormous — 11 characters of template text denoting a
530-
# number that needs ~10**9 digits to write out without an exponent
520+
# WHEN 11 characters of template text denote a number needing ~10**9
521+
# digits in plain notation
531522
model = _parse_model(
532523
model=RangeListTaskParameterDefinition, obj={"type": "FLOAT", "range": [element]}
533524
)
534525

535-
# THEN it renders as its own text. Nothing expands it, so no bound on the
536-
# exponent is needed to keep a template from allocating ~10**9 characters,
537-
# and the value cannot silently exceed TaskParameterStringValueAsJob's
538-
# 1024-character cap and fall through to a numeric member of the union.
526+
# THEN it renders as its own text. Nothing expands it, so no exponent
527+
# bound is needed and the value cannot exceed the field's 1024-character
528+
# cap and fall through to a numeric member of the union.
539529
assert [str(v) for v in model.range] == [element]
540530

541531
def test_floatstring_rendering_ignores_the_decimal_context(self) -> None:
@@ -551,8 +541,8 @@ def test_floatstring_rendering_ignores_the_decimal_context(self) -> None:
551541
model=RangeListTaskParameterDefinition, obj={"type": "FLOAT", "range": [element]}
552542
)
553543

554-
# THEN the value is unrounded: what this library renders is a property of
555-
# the template, not of the host application's decimal context
544+
# THEN it is unrounded: the rendering is a property of the template, not
545+
# of the host application's decimal context
556546
assert [str(v) for v in model.range] == [element]
557547

558548
@pytest.mark.parametrize(

0 commit comments

Comments
 (0)