perps(klear): reject non-canonical dates in margin-report range validation (#409)

[TexasCoding]

Cluster C of the post-review follow-ups — a focused validation fix.

#409

_validate_date_range (Klear margin_reports) parsed with datetime.date.fromisoformat, which on Python 3.11+ leniently accepts non-canonical inputs — "20260501" (basic format) and ISO week dates ("2026-W22-1") — and then forwarded the raw string to a server expecting strict YYYY-MM-DD, so it passed SDK validation but could be rejected (or misinterpreted) downstream.

Fix: after parsing, assert parsed.isoformat() == original and raise a clear error for any non-canonical form.

Verification

• Confirmed "20260501" → 2026-05-01 and "2026-W22-1" → 2026-05-25 both parse (so they reach the new canonical check) but are non-canonical.
• Extended the existing date-range guard test with both cases; mypy --strict + ruff clean; 46 Klear margin tests pass.

🤖 Generated with Claude Code

[claude]

Code Review — PR #417

perps(klear): reject non-canonical dates in margin-report range validation (#409)

---

Overview

This is a focused, surgical fix for a real correctness bug: datetime.date.fromisoformat() on Python 3.11+ silently accepts non-canonical ISO forms like "20260605" (basic format) and "2026-W22-1" (ISO week date), both of which parse successfully but would be forwarded raw to the server in their original non-YYYY-MM-DD form. The fix adds a canonical round-trip check — parsed.isoformat() != raw — immediately after parsing, before the range comparison.

---

Code Quality

Strengths:

• The fix is exactly as minimal as it should be — one guard, one clear error message, no new abstractions.
• The 3-tuple for loop (label, raw, parsed) cleanly handles both fields without duplicating the if-block.
• Error message is excellent: shows the label, the raw input, and the parsed interpretation — gives the caller everything they need to understand the problem.
• Placement is correct: parse → canonical check → range check.

Nit — comment length: The 3-line comment is justified here (explains a genuinely non-obvious Python 3.11 behavior), but per CLAUDE.md convention it could be tightened to one line:

# 3.11+ fromisoformat accepts "20260605" / ISO week dates — reject non-canonical forms before forwarding raw to server.

This is minor; the current comment is fine. Just noting it for consistency with the project's one-line-max guideline.

---

Correctness

The fix is correct. One clarifying note for the record:

• Python 3.7–3.10: fromisoformat only accepted YYYY-MM-DD, so "20260605" would already raise ValueError and be caught by the existing try/except. The bug only materialized on 3.11+.
• The new check is strictly safer across all versions and provides a better error message (the old path would produce a cryptic fromisoformat error rather than the new "must be a canonical YYYY-MM-DD date" message).

No issues.

---

Test Coverage

Good: Both non-canonical forms are tested, one each as start_date and end_date arguments, and both correctly assert not route.called — confirming the server is never hit for invalid inputs.

One minor gap: Neither test exercises the symmetric cases (basic format as end_date, or ISO week as start_date). Given the loop structure these are clearly covered by the implementation, so this is a low-priority nit rather than a meaningful gap. A third case with swapped roles would give extra confidence:

with pytest.raises(ValueError, match="canonical YYYY-MM-DD"):
    auth_klear_client.margin.margin_reports(start_date="2026-05-01", end_date="20260601")

Not a blocker.

---

Security / Performance

• No security concerns — this is input validation made stricter.
• Performance: one string comparison per date field, completely negligible.

---

CLAUDE.md Conventions

All checked:

• Surgical: only _validate_date_range and the existing date-rejection test are touched.
• No speculative changes, no extra abstractions.
• Comment explains the WHY (non-obvious 3.11 platform behavior) — appropriate per project guidelines.
• No pre-existing dead code touched.

---

Verdict

Approve. Clean, correct, minimal fix for a real bug. The comment nit and optional extra test case are both minor. Good work.