Document and prepare release 0.9.0

[Mattsface]

Document and prepare release 0.9.0

Why

Version 0.9.0 introduces optional behavior and a migration path toward version 1.0.

The difference between compatibility mode, strict mode, Session ownership, retry configuration, and warnings must be documented precisely.

Parent release issue: #265

Scope

Update:

README.md
docs/http-transport.md
docs/releases/0.9.0.md

Update the release validator when needed.

Required documentation

Document:

• Compatibility mode remains the default
• How to enable strict mode
• Which responses raise in strict mode
• Existing 404 behavior
• The public retry-policy API
• How to apply the policy to an injected Session
• Why injected Sessions are not automatically modified
• Richer MlbHttpError attributes
• Compatibility warning behavior
• How to filter the warning
• Versioned User-Agent behavior
• Session ownership and cleanup
• Version 1.0 migration direction

Required examples

Injected Session with the package retry policy

import requests
import mlbstatsapi

session = requests.Session()

adapter = requests.adapters.HTTPAdapter(
    max_retries=mlbstatsapi.create_retry_policy(),
)

session.mount("https://", adapter)
session.mount("http://", adapter)

try:
    with mlbstatsapi.Mlb(session=session) as mlb:
        player = mlb.get_person(664034)
finally:
    session.close()

Strict mode

import mlbstatsapi

with mlbstatsapi.Mlb(strict_http=True) as mlb:
    player = mlb.get_person(664034)

Rich HTTP error handling

try:
    player = mlb.get_person(664034)
except mlbstatsapi.MlbHttpError as exc:
    print(exc.status_code)
    print(exc.reason)
    print(exc.url)
    print(exc.response_data)

Release validation

Validate:

• Offline test suite
• Live MLB API tests
• README examples
• Clean wheel installation
• Public imports
• Strict-mode behavior
• Compatibility behavior
• Public retry-policy usage
• Warning imports
• Package metadata
• User-Agent version
• Source distribution
• Wheel

Suggested branch

docs/v0.9-http-behavior

The branch should start from and target:

release/0.9.0

Dependencies

Depends on:

• Establish the 0.9.0 HTTP behavior contract #266
• Expose the default retry policy for caller-managed Sessions #267
• Add richer context to MlbHttpError #268
• Add optional strict HTTP mode #269
• Add warnings for future strict HTTP behavior #270
• Add a versioned User-Agent #271

Acceptance criteria

• README examples use only public APIs
• Detailed transport documentation matches the implementation
• Release notes clearly distinguish compatibility and strict modes
• Session ownership limitations are prominent
• Version 1.0 migration expectations are clear
• The release validator passes
• The built wheel installs in a clean environment
• Public PyPI installation passes smoke tests
• GitHub release notes are complete

Not included

• New production behavior
• Caching
• Async support
• New endpoints
• Strict mode becoming the default