docs: define the stable 1.0 public API

[Mattsface]

Closes #286

Summary

Defines the supported public API contract for the python-mlb-statsapi 1.x series: package-root symbols, constructor signatures, exception/warning inheritance, Session ownership, Mlb endpoint inventory, and Python support wording. This is primarily documentation and contract testing; no runtime redesign.

Public symbols classified

Symbol	Status
Mlb, MlbDataAdapter, MlbResult, create_retry_policy	Public and stable in 1.x
Exception types (TheMlbStatsApiException, transport/timeout/HTTP/decode)	Public and stable in 1.x
MlbHttpCompatibilityWarning	Public and stable in 1.x
return_splits, get_stat_attributes	Public legacy helpers, stable in 1.x
Submodules (exceptions, warnings, mlb_api, mlb_dataadapter, mlb_module, models)	Accidentally exposed via package namespace / star import; not supported

Legacy helpers and their status

return_splits and get_stat_attributes remain package-root importable and stable in 1.x. They are not preferred for new code and are not deprecated (no replacement/warning/timeline/issue yet).

Whether __all__ was added and why

No. Adding __all__ with only supported symbols would silently remove accidentally exposed submodule names from from mlbstatsapi import *. Promoting those submodules into __all__ would incorrectly freeze accidental exposure. Omission is documented in docs/public-api.md and mlbstatsapi/__init__.py.

Constructor contracts documented

Documented and tested for Mlb, MlbDataAdapter, and MlbResult, including parameter order, defaults, keyword-only strict_http=True, context-manager/close behavior, and Session ownership.

Endpoint-method inventory approach

Explicit MLB_PUBLIC_METHOD_MANIFEST in tests/test_public_api.py (43 public methods: close, __enter__, __exit__, and 40 endpoints). Newly exposed methods require an intentional manifest update.

Exception and warning contracts

Hierarchy and MlbHttpError attributes documented/tested. MlbHttpCompatibilityWarning remains a FutureWarning subclass.

Session ownership contract

Library-created vs caller-injected Session rules documented as stable public API; covered by public API and existing session tests.

Python support wording

• Minimum declared: >=3.10
• CI-validated on this branch: 3.10–3.12
• Newer versions may work but are not claimed as CI-validated

Built-wheel validation results

poetry build
python3 scripts/validate_release.py
→ smoke test passed for python-mlb-statsapi 0.9.0
→ Release validation passed for python-mlb-statsapi 0.9.0

Smoke coverage includes supported package-root imports, constructor signatures, exception/warning inheritance, MlbResult, legacy helpers, and strict_http defaults of True.

Focused test results

poetry run pytest \
  tests/test_public_api.py \
  tests/test_http_contract.py \
  tests/test_http_warnings.py \
  tests/test_mlb_session.py \
  tests/test_release_validation.py \
  -v -rxX
→ 365 passed

Full offline-suite results

After rebase onto current origin/release/1.0.0 (includes #293 migration guide):

poetry run pytest tests/ --ignore=tests/external_tests -v -rxX
→ 521 passed

Follow-up issues recommended

1. Introduce __all__ after deciding how to handle accidental submodule star-import exposure
2. Fix get_venue 400-path returning [] while annotated as Venue | None
3. Fix get_homerun_derby bare None instead of return None on 400–499
4. Align get_game_line_score 400 handling with sibling game helpers
5. Consider Python 3.13+ CI under Update release validation and CI for version 1.0 #288

Rebase status relative to #285 / current release

Rebased cleanly onto current origin/release/1.0.0 after #293 (docs/v1-migration-guide) merged. Branch is 0 behind / 2 ahead. Contains #284 and #285 ancestry. No Pending #285 / XFAIL_PENDING_WARNING_CALL_SITE markers. No rebase conflicts.

Risk assessment

Low. Documentation, contract tests, release-smoke updates for the already-merged strict default, and two unambiguous docstring/annotation fixes (get_game_line_score example typo; get_division_id return annotation List[Division] → List[int]). No HTTP decision logic, Session behavior, exception hierarchy, retry values, or endpoint return models were redesigned. No supported symbol was removed or renamed.

  

[Mattsface]

Cool.