ci: separate validation and document HTTP transport

[Mattsface]

Summary

Separates deterministic offline CI from live MLB API validation, removes automatic TestPyPI/PyPI publishing from normal pushes, and documents the HTTP transport features introduced for version 0.8.0.

Why offline and live tests were separated

Live MLB API tests can fail because of service availability, seasonal data changes, or undocumented payload changes. Deterministic offline tests are the normal pull-request gate. Live validation remains available manually and on a weekly schedule.

Offline CI

• Workflow: Offline CI (.github/workflows/build-and-test.yml)
• Python versions: 3.10, 3.11, 3.12
• Offline test command:

poetry run pytest \
  tests/ \
  --ignore=tests/external_tests

• Package build waits for the offline matrix (needs: offline-tests) and does not publish
• Triggers: PRs and pushes to main / release/0.8.0, plus workflow_dispatch

External tests

• Workflow: External MLB API Tests (.github/workflows/external-tests.yml)
• Triggers: workflow_dispatch and weekly cron (0 12 * * 1, Monday 12:00 UTC)
• Python 3.12 only
• Live tests are not a normal PR gate

Publishing workflows removed

Deleted:

• .github/workflows/build-and-test-mlbstatsapi-test.yml (TestPyPI on development pushes)
• .github/workflows/build-and-test-mlbstatsapi-prd.yml (PyPI on main pushes)

Normal pushes and pull requests no longer publish packages. Active workflows do not reference PyPI credentials or pypa/gh-action-pypi-publish.

HTTP transport documentation

Documented in README (HTTP Reliability and Configuration) and docs/http-transport.md:

• Existing synchronous Mlb() usage
• Context manager and explicit close()
• Default timeout (3.05, 30.0) and custom timeouts
• Shared Session model across v1 / v1.1 adapters
• Session injection and ownership (library-created vs caller-injected)
• Injected Sessions remain unmodified (no retry adapter replacement)
• Default retry policy (GET only, max 3 retries, backoff 0.5, Retry-After)
• Structured exception hierarchy (MlbTransportError, MlbTimeoutError, MlbHttpError, MlbDecodeError)
• Existing endpoint-specific 404 not-found behavior (None / [] / {})
• No default response caching
• No async support in 0.8.0

Documentation matches the merged transport code on release/0.8.0. Production Python files were not modified in this PR.

Branch protection recommendation

Select these as required checks:

• Offline tests - Python 3.10
• Offline tests - Python 3.11
• Offline tests - Python 3.12
• Build package (optional but useful)

Do not require External MLB API tests - Python 3.12 as a pull-request check.

Validation results

Offline tests

157 passed in 7.35s

Command: poetry run pytest tests/ --ignore=tests/external_tests

External tests

119 passed, 1 skipped in 13.72s

Command: poetry run pytest tests/external_tests/ -v

Skipped: tests/external_tests/mlb/test_mlb.py::TestMlbDataApi::test_mlb_adapter_500 (existing skip; no MLB API outage or response-change failure observed)

Full local suite

276 passed, 1 skipped in 10.52s

Command: poetry run pytest tests/

Package build

Building python-mlb-statsapi (0.7.2)
Built python_mlb_statsapi-0.7.2.tar.gz
Built python_mlb_statsapi-0.7.2-py3-none-any.whl

Command: poetry build

Safety checks

• No gh-action-pypi-publish / PYPI_API_TOKEN / TEST_PYPI_API_TOKEN in active workflows
• No stale references to deleted publishing workflow filenames
• git diff --check clean
• actionlint not installed; skipped

Safety confirmations

• Production Python files unchanged (mlbstatsapi/ not in diff)
• Package version unchanged (0.7.2)
• Nothing published
• No tag or release created
• No live MLB API outage or response change encountered during validation

Note (out of scope)

While reviewing transport docs against production code, Mlb.__init__ still calls self._logger.setLevel(logging.DEBUG). That is outside this CI/docs PR and was not changed here.