Skip to content

Type collection returns as Sequence[Player], not List[Player] #646

Description

@nanotaboada

Problem

services/player_service.py::retrieve_all_async is annotated -> List[Player],
but result.scalars().all() is typed Sequence[Player] by SQLAlchemy 2.0 —
not necessarily a list. The annotation is inaccurate and over-promises:
callers are told they can .append() or do item assignment on a value that may
not support it.

Proposed Solution

Type collection-returning read operations with collections.abc.Sequence:

from collections.abc import Sequence

async def retrieve_all_async(async_session: AsyncSession) -> Sequence[Player]:
    ...

The only caller (get_all_async in routes/player_route.py) caches the value
and returns it through a list[PlayerResponseModel] response_model, which
FastAPI builds from any iterable — so Sequence is sufficient. This is the
collections.abc principle: annotate with the least specific type that is
actually true.

Suggested Approach

  1. Change the retrieve_all_async return annotation to Sequence[Player].
  2. Best done together with the PEP 585 / 604 sweep (see the idioms typing
    issue) so all the collections.abc imports land at once.
  3. Run uv run flake8 and uv run pytest.

Acceptance Criteria

  • retrieve_all_async returns Sequence[Player]
  • No runtime behaviour change
  • flake8 clean, all tests pass
  • CHANGELOG.md updated

References

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestpriority:lowNice-to-have improvement. Can be deferred without blocking other work.pythonPull requests that update Python codepython:idiomsRefactors toward idiomatic Python (PEP conventions, stdlib idioms)

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions