feat(v4): mechanical rename wave - canonical names with 3.9 FutureWarning shims (2(c)-ii PR-A, 32 rows) - #742
Conversation
…th 3.9 FutureWarning shims (2(c)-ii PR-A, 32 ledger rows)
First of the two 2(c)-ii rename-sweep PRs (v4-design section 9 item 4;
mechanical wave). Flips 32 ledger rows planned -> shimmed - M-032,
M-033/M-034, M-035..M-042, M-088/M-089, M-094, M-097..M-113, M-114 - via
the shared sentinel machinery in the new leaf module
diff_diff/_deprecation.py (_NotSupplied sentinel + resolve_renamed_kwarg
+ require_arg + deprecated_field_property; single FutureWarning with the
uniform migration message, both-spellings ValueError, missing-argument
TypeError naming the NEW param).
Renames (old spelling stays through 3.9 as a warning alias; removal in
4.0; the NEW name takes the OLD name's signature position so positional
calls bind identically, and the deprecated path routes to bit-identical
results):
- WooldridgeDiD.fit: cohort= -> first_treat= [M-032].
- ChaisemartinDHaultfoeuille.fit: group= -> unit= [M-033], controls= ->
covariates= [M-034]; twowayfeweights(): group= -> unit= [M-097]; the
removal-bound chaisemartin_dhaultfoeuille() wrapper keeps its own
group param (dies with M-077) but forwards to the canonical name.
- ChaisemartinDHaultfoeuilleResults.groups -> units [M-114]: dataclass
field renamed, read-only FutureWarning alias property under the old
name, __setstate__ migration for 3.8-era pickles, repr n_units= and
summary "Units (post-filter):". to_dict() never serialized the list
(pinned by test); n_groups_dropped_* counters and CS-family cohort
"groups" vocabulary are deliberately untouched.
- HeterogeneousAdoptionDiD.fit + joint_pretrends_test +
joint_homogeneity_test + did_had_pretest_workflow:
outcome_col/dose_col/time_col/unit_col/first_treat_col -> bare
outcome/dose/time/unit/first_treat [M-035..M-039, M-098..M-112];
followers of renamed required params (pre_periods/base_period/
post_periods; dCDH time/treatment) carry required-sentinels with the
restored missing-argument errors pinned.
- RegressionDiscontinuity.fit: outcome_col/running_col/treatment_col ->
outcome/running/takeup [M-040..M-042] (takeup per section 8 rule 7's
non-binary corollary); RegressionDiscontinuityResults.treatment_col ->
takeup [M-094] with alias property, __setstate__, and a dual-key
to_dict window ("takeup" + deprecated "treatment_col" through 3.9).
RDPlot.fit: outcome_col/running_col -> outcome/running [M-088/M-089].
- trim_weights(): weight_col= -> weights= [M-113].
Sentinel-carrying params are transitionally annotated Any (mypy zero-
error gate; the 4.0 removal restores narrow annotations). User-facing
validation/guidance strings across had.py, chaisemartin_dhaultfoeuille.py
and the results modules now name the canonical spellings.
Enforcement kept green in the same diff: docs/v4-deprecations.yaml rows
flipped to shimmed/phase 5 with test_ref
tests/test_v4_rename_mechanical.py (41 behavioral pins: per-surface
old-name warning + canonical-silence + routing parity + both-supplied
rejection + field-trio/pickle/dual-key contracts);
tests/test_naming_guard.py gains the four new rule-1 time-surface
allowlist entries (HAD.fit and the three pretest functions).
Bulk migration to canonical names: ~900 call sites across 30 test files
(AST-guided kwarg rewrite; fit-kwargs dict builders and results-attribute
reads swept by hand; TripleDifference's rule-3 group= and the unmerged
third-party LWDiD surface deliberately untouched), tutorials 16/19/20/
21/22 (re-executed via nbmake), guides llms*.txt (llms-full keeps the
deprecated tail listed inside the CI-pinned HAD signature block),
docs rst (incl. both renamed-field autosummary pages), README's one
catalog line, REGISTRY.md kwarg references, and the two paper reviews
with kwarg mentions. CHANGELOG names the full row inventory.
Overall assessment✅ Looks good — no unmitigated P0 or P1 findings. Executive summary
MethodologySeverity: P3 — Informational Impact: None. Cross-checking the affected Registry entries—dCDH at
No new inline inference, NaN guard, variance, or control-group logic was introduced. Concrete fix: None required. Code QualityNo findings. The shared sentinel resolver consistently handles explicit PerformanceNo findings. The shims add only constant-time argument resolution before existing computations. MaintainabilityNo findings. Deprecation behavior is centralized in Tech DebtNo findings. The aliases have an explicit 4.0 removal lifecycle; no new silent correctness limitation is introduced. SecurityNo findings. No secrets, unsafe deserialization behavior, or security-sensitive changes were identified. Documentation/TestsCanonical-name cleanup is incompleteSeverity: P2 Impact: A public dCDH example still uses deprecated Locations:
Concrete fix: Change the dCDH example to The new rename suite otherwise covers warning counts, positional compatibility, conflicting spellings, routing parity, result aliases, dual-key serialization, and pickle migration. Static parsing and a standard-library shim smoke test passed; the full suite could not be executed because this environment lacks pytest and numerical dependencies. |
…ssages + message-regression pin
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall assessment✅ Looks good — no unmitigated P0 or P1 findings. Executive summary
MethodologySeverity: P3 — Informational Impact: None. Registry and estimator-body review confirms this is an API-only rename. Existing documented methodological deviations are unchanged, and no new inline inference or NaN inconsistency was introduced. Concrete fix: None required. Code QualitySeverity: None Impact: Alias resolution is consistently centralized, including explicit- Concrete fix: None. PerformanceSeverity: None Impact: Each shim adds only constant-time argument resolution. Concrete fix: None. MaintainabilitySeverity: None Impact: Deprecation behavior and warning text are centralized in Concrete fix: None. Tech DebtSeverity: None Impact: Every alias has a recorded 4.0 removal lifecycle in the deprecation ledger. Concrete fix: None. SecuritySeverity: None Impact: No secrets, unsafe deserialization, or security-sensitive behavior was introduced. Concrete fix: None. Documentation/TestsRemaining deprecated terminologySeverity: P2 Impact: Two references still steer readers toward deprecated names:
Both aliases work during 3.9 but emit Concrete fix: Replace those references with The focused pytest suites could not run because pytest and numerical dependencies are unavailable. Static parsing and the standalone deprecation-helper smoke checks passed. |
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall assessment✅ Looks good — no unmitigated P0 or P1 findings. Executive summary
MethodologySeverity: P3 — Informational Impact: None. Canonical parameters are resolved into the existing body-local variables before estimation ( Concrete fix: None required. Code QualitySeverity: P3 — Informational Impact: The shared helper correctly distinguishes omitted arguments from explicit Concrete fix: None. PerformanceSeverity: P3 — Informational Impact: Shims add only constant-time argument resolution. Concrete fix: None. MaintainabilitySeverity: P3 — Informational Impact: Warning behavior and renamed-field aliases are centralized in Concrete fix: None. Tech DebtSeverity: P3 — Informational Impact: Every alias has a recorded 4.0 removal lifecycle in Concrete fix: None. SecuritySeverity: P3 — Informational Impact: No secrets, unsafe deserialization, or security-sensitive changes were found. Concrete fix: None. Documentation/TestsCanonical validation terminologySeverity: P2 — Newly identified Impact: Invalid-period errors from the renamed HAD pretest APIs still describe the canonical Concrete fix: Replace those user-facing labels with The prior |
…ors + regression pin
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall assessment✅ Looks good — no unmitigated P0 or P1 findings. Executive summary
MethodologySeverity: P3 — Informational Code QualitySeverity: P3 — Informational PerformanceSeverity: P3 — Informational MaintainabilitySeverity: P3 — Informational Tech DebtSeverity: P3 — Informational SecuritySeverity: P3 — Informational Documentation/TestsSeverity: P3 — Informational |
… + docstring quote (M-039 canonical name)
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall assessment✅ Looks good — no unmitigated P0 or P1 findings. Executive summary
MethodologySeverity: P3 — Informational Code QualitySeverity: P3 — Informational PerformanceSeverity: P3 — Informational MaintainabilitySeverity: P3 — Informational Tech DebtSeverity: P3 — Informational SecuritySeverity: P3 — Informational Documentation/TestsSeverity: P3 — Informational |
1 participant
Summary
planned→shimmed— [M-032], [M-033]/[M-034], [M-035]..[M-042], [M-088]/[M-089], [M-094], [M-097]..[M-113], [M-114] — introducing the canonical names with 3.9FutureWarningshims (removal in 4.0).diff_diff/_deprecation.py:_NotSuppliedsentinel,resolve_renamed_kwarg(single warning with the uniform migration message; both-spellingsValueError),require_arg(restored missing-argumentTypeErrornaming the NEW param),deprecated_field_property(renamed-results-field alias).WooldridgeDiD.fit(cohort→first_treat);ChaisemartinDHaultfoeuille.fit(group→unit, controls→covariates)+twowayfeweights(group→unit)+ results fieldgroups→units(alias property,__setstate__pickle migration,n_units=/"Units (post-filter):" labels); HAD fit + the three pretest functions (*_col→ bare names, 20 rows);RegressionDiscontinuity.fit(outcome_col/running_col/treatment_col → outcome/running/takeup)+ results fieldtreatment_col→takeup(alias property,__setstate__, dual-keyto_dictwindow through 3.9);RDPlot.fit(2 rows);trim_weights(weight_col→weights).test_ref: tests/test_v4_rename_mechanical.py(41 behavioral pins), naming-guard rule-1 allowlist entries for the four newtimeparams, ~900 test call sites migrated to canonical names (AST-guided), tutorials 16/19/20/21/22 re-validated via nbmake, guides/rst/README/REGISTRY/paper-review kwarg references updated (llms-full keeps the deprecated tail inside the CI-pinned HAD signature block), CHANGELOG names the full row inventory.Methodology references (required if estimator / math changes)
docs/v4-design.md§8 (rule 5 no_colsuffixes, rule 3unitvs reservedgroup, rule 7's non-binary corollary selectingtakeup, rule 9 results-field mirrors, rule 10 public-function completeness).n_groups_dropped_*counters, CS-family cohortgroupsvocabulary, TripleDifference's rule-3group=, and the removal-boundchaisemartin_dhaultfoeuille()wrapper's owngroupparam are deliberately unchanged per the ledger row notes.Validation
tests/test_v4_rename_mechanical.py(41 pins: warning message/count, canonical + positional silence, both-supplied rejection, sentinel-restored missing-arg errors, bit-exact routing parity, field-alias trio, pickle migration, M-094 dual-keyto_dict, dCDHto_dictnon-serialization pin); ~30 test files migrated to canonical names and all their suites re-run green, including under-W error::FutureWarning;tests/test_v4_matrix.py+tests/test_naming_guard.pygreen with the flipped rows.Security / privacy