feat: preserve explicit HTTP compatibility mode (#285)

[Mattsface]

Closes #285

Why compatibility mode remains available

Version 1.0 makes strict HTTP handling the default (#284), but callers who explicitly construct Mlb(strict_http=False) or MlbDataAdapter(strict_http=False) must keep the historical empty-result behavior for final non-404 4xx responses. This preserves an intentional opt-in escape hatch without changing the new default.

Why the warning wording changed

The 0.9 wording said compatibility behavior “may change in version 1.0,” which is no longer accurate once 1.0 ships. The warning now states that:

• the caller explicitly selected compatibility mode with strict_http=False
• the historical empty result was returned
• strict HTTP behavior is the version 1.0 default
• removing strict_http=False or passing strict_http=True raises MlbHttpError

Only the status code and resolved request URL are included from the response. Response bodies, headers, credentials, cookies, and tokens are never included.

Why a fixed stack level was insufficient

COMPATIBILITY_WARNING_STACKLEVEL = 3 correctly pointed at direct adapter.get() callers, but for public Mlb endpoint methods the same fixed depth landed on the internal mlbstatsapi/mlb_api.py frame (for example get_person at line 178) instead of the application call site.

How the external caller frame is selected

A private _compatibility_warning_stacklevel() helper walks inspect.currentframe() parents and returns the first warnings.warn() stack level whose module is outside the mlbstatsapi / mlbstatsapi.* namespace. This works for both direct adapter calls and public Mlb endpoint wrappers without hard-coding endpoint methods or relying on Python 3.12-only warning APIs.

Confirmations

• Warning content excludes response bodies (covered by offline tests)
• Strict mode behavior and 404 empty-result shapes remain unchanged
• Constructor defaults remain strict_http=True after rebasing onto Make strict HTTP behavior the default in 1.0 #284; this PR does not change defaults
• Retries, Sessions, User-Agent, version metadata, README, release notes, and CI were not changed

#285 xfail removed

• Removed XFAIL_PENDING_WARNING_CALL_SITE from tests/http_contract_support.py
• Removed its import/use from tests/test_http_warnings.py
• rg "XFAIL_PENDING_WARNING_CALL_SITE|Pending #285" tests returns no matches

Focused test results (after rebase onto #284)

poetry run pytest \
  tests/test_http_warnings.py \
  tests/test_http_contract.py \
  tests/test_mlb_retries.py \
  tests/test_mlb_session.py \
  -v -rxX

300 passed, 0 failed, 0 xfailed

Caller-location tests:

• test_compatibility_warning_points_to_direct_adapter_caller_line — passed
• test_compatibility_warning_points_to_public_mlb_endpoint_caller_line — passed

Full offline-suite results (after rebase)

poetry run pytest tests/ --ignore=tests/external_tests -v -rxX

433 passed, 0 failed, 0 xfailed

Remaining xfails and their issue numbers

None after rebasing onto merged #284. Previously pending #284 xfails are gone from release/1.0.0.

Rebase status relative to #284

Rebased onto origin/release/1.0.0 after #291 (feat: make strict HTTP behavior the default (#284)) merged. Clean rebase with no conflicts. Production defaults remain:

strict_http: bool = True  # mlb_api.py and mlb_dataadapter.py

Compatibility tests continue to use explicit strict_http=False.

Risk assessment

Low. Changes are confined to compatibility-warning message text and stack-level calculation, plus activating the existing #285 contract test. Public return shapes, exception hierarchy, retry policy, Session ownership, and constructor defaults are unchanged.