chore(simplify): trim comment noise + remove dead state

[justin-layerv]

Summary

• Remove dead _user_agent attribute from both sync/async clients
• Trim ~78 lines of WHAT-not-WHY comments across _utils.py, client.py, async_client.py
• No functional changes — 158 tests passing (unchanged)

Stacks on top of PR #8 (feat/align-api-v2). Result of running /simplify with three parallel review agents (code reuse, quality, efficiency).

What was trimmed

Area	Before	After	Lines saved
_raw_request docstring (×2 clients)	31 lines each	7 lines each	-48
_validate_batch_create_shape._fail comments	14 lines	2 lines	-12
parse_quota plan-default comment	6 lines	1 line	-5
build_list_params type comment	3 lines	0	-3
Spec-validation section banner	3 lines	1 line	-2
cast explanation (×2 clients)	4 lines each	0	-8
Dead _user_agent attribute (×2 clients)	1 line each	0 (inlined)	0 net

What was skipped

• Sync/async duplication — tracked as Refactor: reduce sync/async client duplication (~380 lines each) #20, structural limitation
• Parameter sprawl on list()/list_all() — at threshold (9 params) but not over
• HTTP method Literal type annotation — low risk for a private method, would need both clients updated
• Double getattr in _serialize_value — negligible cost on max 7-field dataclasses

🤖 Generated with Claude Code

[claude]

PR Review: chore(simplify): trim comment noise + remove dead state

Overall: Looks good. This is a clean, safe cleanup PR. The comment trimming is well-judged and the dead code removal is correct.

Code Quality & Best Practices

Thumbs up on the comment philosophy. The trimmed comments were overwhelmingly WHAT-not-WHY — restating the code in English. The replacements are better:

• _raw_request docstring: 24-line essay → 5-line summary that still communicates the key contract (allow_statuses bypasses retries). That's the one thing a caller actually needs to know.
• _fail helper: the old comment explained what ValidationError is and what code= means — both of which are self-evident from reading the constructor call. The new 2-line comment preserves the non-obvious bit: the distinction between "unexpected_response" and "client_validation" codes.
• parse_quota fallback: the old 6-line comment explained the "unknown" default in exhaustive detail. The 1-liner captures the intent.

_user_agent removal is correct. The attribute was only ever read once (to populate _base_headers). Inlining the expression into the dict literal eliminates a dangling instance variable with no loss of functionality. Confirmed no tests or external code references _user_agent.

Potential Issues

None found. The changes are purely subtractive (comments) or mechanical (inlining). No logic changes, no control flow changes.

One minor observation: the section banner comment on line 137 of _utils.py now reads:

# ---- Spec-derived input validation (mirrors openapi.yaml constraints) ----

This is fine — it's a navigational aid, not a WHAT comment. Good call keeping it.

Security

No concerns. The trimmed _fail comment mentioned not leaking raw body content into logs — that property is preserved by the code itself (the _validate_batch_create_shape docstring at line 440-447 still documents the security rationale for not embedding raw bodies in error messages). The code-level safeguard is untouched.

Test Coverage

PR description states 158 tests passing, unchanged. Since there are no functional changes, existing coverage is sufficient. The _user_agent attribute had no direct test coverage before — but it didn't need any, and the inlined form is exercised by any test that constructs a client.

Summary

Clean PR, no functional risk. Approve.