Skip to content

Add optional async dependency and packaging support #300

Description

@Mattsface

Parent: #297
Depends on: #298

Goal

Add packaging support for async functionality without changing the dependency footprint for existing synchronous users.

Scope

pip install "python-mlb-statsapi[async]"
  • Preserve normal synchronous installation:
pip install python-mlb-statsapi
  • Define predictable behavior when async functionality is imported without the optional dependency installed
  • Ensure wheel and sdist metadata include the extra correctly

Contract requirements from #298

The selected async HTTP dependency must be capable of supporting the public transport contract without leaking its own API into the stable surface:

  • Async requests and cleanup must be awaitable
  • One library-owned client must support multiple concurrent in-flight requests on the same event loop
  • Caller-requested cancellation must be able to propagate as asyncio.CancelledError
  • Request-level timeout configuration must be possible without mutating caller-injected clients
  • Caller-injected clients must remain caller-owned and must not be silently reconfigured or closed by the library
  • Library-created clients must support the package User-Agent and library-owned lifecycle rules
  • Retry behavior may be implemented by the library; the dependency does not need an urllib3.Retry equivalent
  • Underlying transport-specific exceptions and types must remain implementation details rather than public API commitments

The optional dependency choice should not force changes to the synchronous Mlb or MlbDataAdapter API.

Constraints

  • Existing synchronous users should not receive an unnecessary async HTTP dependency
  • Do not change the existing runtime dependency contract unless required
  • Error messages for a missing async extra should be actionable
  • Do not expose the selected transport library as part of the stable mlbstatsapi public API

Acceptance criteria

  • Normal install works without async dependency
  • [async] extra installs required async dependency
  • Missing-extra behavior is clear and tested
  • Wheel/sdist metadata contains the optional extra correctly
  • Existing sync package imports remain unaffected
  • Selected dependency supports the lifecycle, timeout, cancellation, ownership, and same-event-loop concurrency requirements from Define the v1.1 async API and transport contract #298

Refs #297
Contract: #298

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions