Audit and define the stable public API for 1.0

[Mattsface]

Audit and define the stable public API for 1.0

Parent release issue: #282

Why

Version 1.0.0 is not only a behavior change; it is a stability promise. The project needs an explicit boundary between supported public API and implementation details so future changes can follow semantic versioning intentionally.

Scope

Audit and document:

• Package-root exports from mlbstatsapi
• Mlb constructor parameters and context-manager behavior
• MlbDataAdapter public status and construction behavior
• MlbResult
• Structured exception classes and inheritance
• MlbHttpCompatibilityWarning
• create_retry_policy()
• Session injection and ownership rules
• Supported Python versions
• Documented endpoint methods and return contracts

Required decisions

For each currently exposed symbol, decide whether it is:

Public and stable in 1.x
Public but deprecated
Internal and undocumented
Accidentally exposed and requiring a separate breaking-change decision

Do not remove or rename an exposed symbol silently. Any additional breaking change discovered by this audit must receive its own focused issue with migration guidance.

Deliverables

• A documented package-root public API list
• Tests verifying expected package-root imports
• Clear documentation of constructor and Session ownership guarantees
• A documented Python support policy
• Deprecation decisions, if needed, using warnings before removal where practical
• Confirmation that exception inheritance supports broad and specific catches

Acceptance criteria

• Every package-root export has an intentional status
• Supported public imports are validated from a built wheel
• Public constructor signatures are documented and tested
• Session ownership rules are treated as part of the stable API
• Exception and warning inheritance are documented and tested
• Any proposed removal or rename is split into a separate reviewed issue
• The release notes can accurately state what API stability 1.0 promises

Suggested branch

docs/v1-public-api-contract

Start from and target:

release/1.0.0