"""Helper for paginating related-object collections on detail pages.

``ListView`` already paginates its single ``object_list`` via ``paginate_by``.
Detail pages and dashboards, by contrast, often render several unbounded
related collections at once (e.g. an award's tranches plus its letters). A
single ``?page=`` cannot drive more than one of them, so each table gets its
own *named* page parameter (``?gl_page=2``) and renders with
``components/pagination.html`` passing ``page_obj`` and ``param`` explicitly.
"""

from __future__ import annotations

from django.core.paginator import Paginator
from django.http import HttpRequest


def paginate_qs(
    request: HttpRequest,
    object_list,
    per_page: int = 25,
    param: str = "page",
):
    """Return a ``Page`` for ``object_list`` driven by ``?<param>=N``.

    ``object_list`` may be a queryset or any sliceable sequence. Invalid or
    out-of-range page numbers clamp to a valid page (``get_page`` semantics),
    so links never 404. Use a distinct ``param`` per table on the same page.
    """
    paginator = Paginator(object_list, per_page)
    return paginator.get_page(request.GET.get(param))


__all__ = ["paginate_qs"]