Release 1.0.0: Make strict HTTP behavior the default

[Mattsface]

Release 1.0.0: Make strict HTTP behavior the default

Why

Version 0.8.0 made the HTTP transport reliable. Version 0.9.0 made HTTP behavior configurable and introduced a warning-backed migration path toward stricter failures.

Version 1.0.0 should complete that migration by making final non-404 HTTP client errors raise by default, while preserving the package's endpoint-specific 404 contract and providing an explicit compatibility opt-out.

A 1.0 release also establishes a stable public API contract. The supported package-root exports, exception hierarchy, constructor behavior, Session ownership rules, and documented endpoint behavior must therefore be audited before publication.

Primary breaking change

The default client:

import mlbstatsapi

mlb = mlbstatsapi.Mlb()

will use strict HTTP handling by default.

Expected default behavior:

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

Legacy compatibility behavior remains explicitly available:

with mlbstatsapi.Mlb(strict_http=False) as mlb:
    ...

In compatibility mode, final non-404 4xx responses continue returning the historical empty result and emitting MlbHttpCompatibilityWarning.

Goals

• Define and test the complete 1.0 HTTP contract before changing implementation
• Make strict HTTP handling the default
• Preserve explicit compatibility mode through strict_http=False
• Preserve endpoint-specific 404 results
• Preserve Session ownership and injected Session configuration
• Audit and document the stable 1.0 public API
• Provide clear migration guidance from 0.9.x
• Update release validation for the new defaults
• Publish tested wheel and source-distribution artifacts

Compatibility requirements

Version 1.0.0 must preserve:

• The synchronous Mlb client
• Existing endpoint method names and documented return types
• Endpoint-specific 404 results such as None, [], and {}
• Existing structured exception classes and inheritance
• Existing timeout configuration
• Existing retry values unless changed through a separately reviewed issue
• Caller ownership of injected Sessions
• Caller-defined headers, adapters, and retry configuration
• Explicit compatibility mode through strict_http=False

The library must not silently reconfigure or close a caller-injected Session.

Planned work

• Define and test the version 1.0 HTTP contract #283
• Make strict HTTP behavior the default in 1.0 #284
• Preserve explicit compatibility mode in 1.0 #285
• Audit and define the stable public API for 1.0 #286
• Document the 1.0 breaking change and migration path #287
• Update release validation and CI for version 1.0 #288
• Prepare and publish release 1.0.0 #289

Recommended implementation order

#283 Define and test the HTTP contract
    ↓
#284 Make strict behavior the default
    +
#285 Preserve explicit compatibility mode
    +
#286 Audit and define the stable public API
    ↓
#287 Document the breaking change and migration path
    +
#288 Update release validation and CI
    ↓
#289 Prepare and publish release 1.0.0

Issues #284, #285, and #286 may proceed in parallel after #283 establishes the contract. Documentation and validator work should follow the finalized implementation and public API decisions.

Branch strategy

feature branch
    ↓
release/1.0.0
    ↓
main
    ↓
v1.0.0

All version 1.0.0 feature branches should start from and target:

release/1.0.0

Out of scope

Version 1.0.0 will not automatically include:

• Async support
• Response caching
• New MLB endpoints
• Global rate limiting
• Strict exceptions for endpoint-specific 404 responses
• Automatic modification of injected Sessions
• A new transport library
• A broad endpoint model redesign
• Unrelated features added only because this is a major release

Any additional breaking change requires its own issue, migration rationale, and focused review.

Definition of done

• The complete 1.0 HTTP contract is covered by deterministic tests
• Mlb() raises MlbHttpError for final non-404 4xx responses
• Mlb(strict_http=False) retains compatibility behavior and warnings
• Existing endpoint-specific 404 behavior remains unchanged
• Structured timeout, transport, HTTP, and decode errors remain distinct
• Session ownership and injected Session preservation remain unchanged
• The supported public API is explicitly documented and validated
• Migration guidance clearly explains the breaking change and opt-out
• Offline tests pass on every supported Python version
• Relevant live MLB API tests pass
• Wheel and source distribution pass release validation and twine check
• A clean public PyPI installation passes smoke tests
• GitHub release v1.0.0 is published