Document and prepare release 0.9.0

[Mattsface]

Closes #272
Refs #265

Why

Issues #266 through #271 landed the configurable HTTP behavior for 0.9.0 on release/0.9.0, but the release itself was never prepared. Project metadata still reported 0.8.0, docs/http-transport.md still described 0.8.0 as the current release and predated the strict-mode and warning work, there were no 0.9.0 release notes, offline CI still watched release/0.8.0, and the build job only confirmed that poetry build produced files rather than checking what was inside them.

This branch documents, validates, and packages the already-completed functionality. No production HTTP behavior was changed.

What

Version metadata

• poetry version 0.9.0; poetry version --short reports 0.9.0
• No hardcoded runtime version constant was added. The User-Agent still resolves through importlib.metadata, and the built wheel drives it
• poetry.lock was not touched; Poetry did not need to change it

README

Revised the HTTP section for 0.9.0 while keeping the 0.8.0 transport background (shared Sessions, timeouts, retries, exception hierarchy). New or reworked subsections cover compatibility mode as the default and its strict_http=False equivalence, opt-in strict mode, MlbHttpCompatibilityWarning with a package-specific warnings.filterwarnings("error", ...) example, the public create_retry_policy() on a caller-managed Session, Session ownership and cleanup, the richer MlbHttpError attributes, the versioned User-Agent, unchanged 404 behavior, an at-a-glance behavior table, and links to docs/http-transport.md and docs/releases/0.9.0.md.

Also retagged the installation code fence from python to bash; it holds a shell command and was failing the new example syntax check.

Detailed transport documentation

Audited docs/http-transport.md against the implementation rather than rewriting it:

• Removed stale "introduced in 0.8.0" / "not part of 0.8.0" framing and the stale 0.8.0 statement in the 404 section
• Added a public transport API listing so internal names are clearly out of scope
• Promoted Session ownership to its own section with the library-created vs caller-injected breakdown
• Completed the behavior table with the successful-2xx row and the warning outcomes, and stated explicitly that rows describe the response after retries are exhausted
• Added the exact conditions under which a warning is and is not emitted
• Added the 1.0 migration direction, phrased as a direction rather than a commitment
• Changed the DEFAULT_TIMEOUT snippet from a python fence to a text fence so it does not read as an importable public name
• Documented that the User-Agent resolves to python-mlb-statsapi/0.9.0 for this release

Release notes

Added docs/releases/0.9.0.md, following the organization and tone of docs/releases/0.8.0.md but written from scratch. It is phrased as notes being prepared for publication and does not claim 0.9.0 is on PyPI.

CI

.github/workflows/build-and-test.yml now watches main and release/0.9.0 for both pull requests and pushes. The build job removes stale artifacts, builds, and then runs the release validator. It stays offline apart from dependency and package installation, and no publishing was added.

Release validator

I searched for an existing validator first (validate_release, release_valid, smoke across *.py, *.yml, *.md, *.sh); the only hit was a mention in AGENTS.md, so there was nothing to update. Added scripts/validate_release.py, called from both the README development instructions and CI. It verifies:

• Exactly one 0.9.0 wheel and one 0.9.0 source distribution in dist/
• Wheel metadata Name: python-mlb-statsapi, Version: 0.9.0, Requires-Python: >=3.10
• The sdist contains README.md, pyproject.toml, and mlbstatsapi/
• A clean venv installation of the wheel succeeds
• The public imports, create_retry_policy() returning a fresh urllib3 Retry, MlbHttpCompatibilityWarning being importable and a FutureWarning, both HTTP modes constructing, compatibility mode being the default, the library-created Session sending python-mlb-statsapi/0.9.0, and injected Session headers surviving untouched

The smoke test runs from a temporary directory and asserts mlbstatsapi.__file__ resolves under site-packages, so the repository checkout cannot shadow the installed wheel. It uses venv, tempfile, subprocess, and pathlib with no Unix-only paths, and never contacts the MLB API. The one private access (Mlb._session.headers) is confined to the validator and is what verifies the outgoing library-owned User-Agent.

Added tests/test_release_validation.py (offline) to keep documentation honest: every non-REPL python example in the README, transport document, and release notes must compile; documentation examples must not use _session or import internal modules; release notes must exist for the declared version; the documented User-Agent must match the declared version; and CI must watch the current release branch.

Tests

All commands run from the repository root on Python 3.12.

• poetry check — passes (pre-existing [tool.poetry] deprecation warnings only, unchanged by this PR)
• poetry run pytest tests/ --ignore=tests/external_tests -v — 318 passed (309 before, plus the 9 new documentation-consistency tests)
• poetry run pytest tests/test_http_contract.py -v — 58 passed
• poetry run pytest tests/test_http_warnings.py -v — 53 passed
• poetry run pytest tests/test_mlb_retries.py -v — 29 passed
• poetry run pytest tests/test_mlb_exceptions.py -v — 29 passed
• poetry run pytest tests/test_mlb_session.py -v — 45 passed
• poetry run pytest tests/external_tests/ -v — 119 passed, 1 skipped against the live MLB API. This was actually run; the skip is pre-existing and not caused by this branch
• rm -rf dist && poetry build — succeeded
• python3 scripts/validate_release.py — passed, including the clean-virtual-environment wheel install and public import smoke test
• git diff --check — clean

No warnings were silenced globally to make anything pass.

Manual live example validation (run separately, not in offline CI): executed the new README examples against the live API. Compatibility mode, strict mode, and the injected-Session-with-retry-policy example all returned Ty France for get_person(664034); the injected Session kept its my-baseball-project/1.0 User-Agent; a final 400 raised MlbHttpError in strict mode with method=GET, status_code=400, reason=Bad Request, a populated response_data dictionary, and a 133-character body_excerpt; the same call in compatibility mode raised MlbHttpCompatibilityWarning once promoted with a package-specific filter; and get_person(1) still returned None for a 404.

Build artifacts (not committed; dist/ is gitignored)

• wheel: python_mlb_statsapi-0.9.0-py3-none-any.whl
• source distribution: python_mlb_statsapi-0.9.0.tar.gz

Risk and impact

Minimal.

The only non-documentation production change is the version string in pyproject.toml. No endpoint, model, adapter, retry, warning, or exception behavior was modified, and no dependency versions changed. Documentation and the new validator carry no runtime risk.

The realistic failure mode is documentation drifting from behavior, which the new offline tests now guard against for example syntax, private-API usage, and the documented version. If the validator itself were wrong it would fail the build job rather than ship a bad package.

Notes

• Base branch is release/0.9.0, not main
• No tag was created, nothing was uploaded to PyPI or TestPyPI, no GitHub release was created, and release/0.9.0 was not merged into main
• Parent issue Release 0.9.0: Configurable HTTP behavior #265 remains open; publishing and tagging belong there
• Issues Establish the 0.9.0 HTTP behavior contract #266 through Add a versioned User-Agent #271 were verified present on release/0.9.0 and were not reimplemented. All nine required public imports resolve from the source environment
• Intentionally left out: no production HTTP behavior changes, no new endpoints, async support, caching, rate limiting, strict 404 handling, strict mode as the default, new retry values, new exception fields, or telemetry. I found no implementation defect requiring a behavior change, so stale documentation was corrected to match the implementation in every case

  

[Mattsface]

Looks good