Define and test the version 1.0 HTTP contract

[Mattsface]

Define and test the version 1.0 HTTP contract

Parent release issue: #282

Why

Version 1.0.0 changes the default behavior for final non-404 4xx responses. The expected behavior must be locked down in deterministic tests before implementation changes, so the breaking change is intentional and unrelated transport behavior does not drift.

Scope

Define tests for the default Mlb() client and explicit compatibility mode.

Expected default contract:

Successful 2xx response          Return the normal endpoint result
Endpoint-specific 404            Preserve None, [], or {}
Final non-404 4xx response       Raise MlbHttpError
Final 5xx response               Raise MlbHttpError
Timeout                          Raise MlbTimeoutError
Transport failure                Raise MlbTransportError
Successful invalid JSON          Raise MlbDecodeError

Expected compatibility contract:

mlbstatsapi.Mlb(strict_http=False)

• Final non-404 4xx responses return the historical empty result
• MlbHttpCompatibilityWarning is emitted once at the public call site
• 404 behavior remains endpoint-specific
• Final 5xx responses still raise

Required coverage

• Default constructor behavior
• Explicit strict_http=True
• Explicit strict_http=False
• Representative 400, 401, 403, 404, 409, 429, and 5xx responses
• Final 429 behavior after retry exhaustion
• Successful empty responses
• Successful malformed JSON
• Timeout and transport failures
• Warning category, message, and caller-facing stack location
• Both v1 and v1.1 adapters

Acceptance criteria

• Tests describe the complete 1.0 HTTP contract without depending on the live MLB API
• Tests fail against the 0.9.0 default where the intended 1.0 behavior differs
• Existing endpoint-specific 404 tests remain unchanged or are strengthened
• Retry behavior is not accidentally redefined
• Warning filename and line number point to the public caller when compatibility mode is used
• The contract is reusable by implementation and release-validation tests

Suggested branch

tests/v1-http-contract

Start from and target:

release/1.0.0