release: prepare python-mlb-statsapi 0.8.0

[Mattsface]

Summary

Version 0.8.0 is the HTTP reliability release. It modernizes the network layer while preserving the existing synchronous public API and endpoint-specific not-found behavior.

The release branch is currently 12 commits ahead of main.

What changed

HTTP adapter correctness

• Supports the complete successful HTTP range (200 through 299)
• Handles HTTP status codes before attempting to decode error bodies
• Safely handles successful empty responses
• Avoids shared mutable default dictionaries
• Avoids mutating caller-owned response dictionaries
• Preserves existing 404 behavior

Shared Sessions and timeouts

• Uses requests.Session instead of module-level requests.get()
• Shares one Session between the v1 and v1.1 adapters
• Reuses pooled HTTP connections
• Adds an explicit default timeout of (3.05, 30.0)
• Supports custom scalar or connect/read timeout values
• Supports caller-injected Sessions
• Preserves caller ownership of injected Sessions
• Adds close() and context-manager support

Bounded retries

Library-created Sessions retry temporary GET failures for:

• 429
• 500
• 502
• 503
• 504

The policy allows up to three retries after the initial request, uses exponential backoff, and respects Retry-After.

Ordinary client errors such as 400, 401, 403, and 404 are not retried.

Structured exceptions

Adds:

TheMlbStatsApiException
├── MlbTransportError
│   └── MlbTimeoutError
├── MlbHttpError
└── MlbDecodeError

All new exceptions inherit from TheMlbStatsApiException, so existing broad exception handling remains compatible.

Deterministic transport tests

Adds offline coverage for:

• Successful and failed HTTP responses
• Empty and malformed responses
• Session sharing and ownership
• Timeout forwarding
• Retry configuration and attempt counts
• Retryable and non-retryable statuses
• Structured exception inheritance and context
• Context-manager cleanup

Live MLB adapter tests remain separate from deterministic offline tests.

CI and publishing safety

• Runs deterministic offline tests on Python 3.10, 3.11, and 3.12
• Builds the package only after offline tests pass
• Moves live MLB API tests into a separate manual and scheduled workflow
• Removes automatic TestPyPI publishing from development
• Removes automatic PyPI publishing from main
• Uses read-only workflow permissions for validation

Documentation

• Adds the version 0.8.0 release plan
• Adds detailed HTTP transport documentation
• Expands the README with practical examples for:
  • Context-manager usage
  • Shared Sessions
  • Custom timeouts
  • Injected Sessions
  • Session ownership
  • Retry behavior
  • Structured exceptions
  • Backward-compatible exception handling
  • Existing 404 behavior

Compatibility

Version 0.8.0 preserves:

• The synchronous Mlb client
• Existing endpoint method names and signatures
• Existing positional constructor arguments
• Existing endpoint return types
• MlbResult.status_code
• MlbResult.message
• MlbResult.data
• TheMlbStatsApiException
• Endpoint-specific 404 translations such as None, [], and {}

Review focus

Please pay particular attention to:

• Retry boundaries and final-response handling
• Final 429 versus final 5xx behavior
• Session ownership and cleanup
• Injected Sessions remaining unmodified
• Timeout semantics
• Exception inheritance and preserved messages
• CI separation between offline and live tests
• Removal of automatic publishing workflows
• Accuracy and clarity of the README examples

Final release work still required

Before this PR can be marked ready and merged:

• Bump pyproject.toml from 0.7.2 to 0.8.0
• Update the lock file if required by Poetry
• Add final release notes and changelog entry
• Run the complete offline suite
• Run the live MLB API suite
• Build the package
• Install the built wheel in a clean virtual environment
• Run public API smoke tests from the installed wheel
• Confirm package exports and metadata
• Review the complete main...release/0.8.0 diff
• Confirm CI passes
• Mark this PR ready for review

Merge and publishing plan

When the release is fully validated:

1. Merge this PR using a merge commit so the release history remains visible.
2. Tag the exact merge commit as v0.8.0.
3. Create the GitHub release.
4. Publish the validated package to PyPI through an explicitly authorized release action.

Do not merge, tag, or publish as part of the current review.