Source code for ogu_api.resources.members

from __future__ import annotations

import tls_client.response

from ._base import ResourceBase

__all__ = ['MembersResource']




class MembersResource(ResourceBase):
    """Member browsing: list, top, team, groups, vouches, awards, rep history.

    All methods return the raw page response — parse the HTML yourself with
    BeautifulSoup or feed it to the parsers in :mod:`ogu_api.resources.users`
    when you only need profile fields.
    """



    async def list(
        self,
        *,
        username: str = '',
        username_match: str = 'contains',
        sort: str = 'username',
        order: str = 'asc',
        page: int | None = None,
        per_page: int | None = None,
    ) -> tls_client.response.Response:
        """Fetch the paginated member list.

        Args:
            username: Filter by username substring (or exact, see ``username_match``).
            username_match: ``'contains'``, ``'begins'``, ``'ends'``, or ``'exact'``.
            sort: Sort key — ``'username'``, ``'regdate'``, ``'lastvisit'``, ``'postnum'``.
            order: ``'asc'`` or ``'desc'``.
            page: 1-indexed pagination page.
            per_page: Members per page.
        """
        return await self._http.get(
            '/memberlist.php',
            query = {
                'username': username,
                'username_match': username_match,
                'sort': sort,
                'order': order,
                'page': page,
                'perpage': per_page,
            },
        )




    async def top(self) -> tls_client.response.Response:
        """Fetch the top-members page (``/top.php``)."""
        return await self._http.get('/top.php')




    async def team(self) -> tls_client.response.Response:
        """Fetch the staff / team page (``/showteam.php``)."""
        return await self._http.get('/showteam.php')




    async def statistics(self) -> tls_client.response.Response:
        """Fetch the forum statistics page (``/statistics.php``)."""
        return await self._http.get('/statistics.php')




    async def groups(self) -> tls_client.response.Response:
        """Fetch the official groups listing (``/groups.php``)."""
        return await self._http.get('/groups.php')




    async def vouches(self, user_id: str | int) -> tls_client.response.Response:
        """Fetch a user's vouches page (``/vouches.php?id={uid}``)."""
        return await self._http.get(f'/vouches.php?id={user_id}')




    async def awards(self) -> tls_client.response.Response:
        """Fetch the awards index (``/awards.php``)."""
        return await self._http.get('/awards.php')




    async def awards_for_user(self, user_id: str | int) -> tls_client.response.Response:
        """Fetch a single user's awards page (``/awards.php?uid={uid}``)."""
        return await self._http.get(f'/awards.php?uid={user_id}')




    async def reputation_history(self, user_id: str | int) -> tls_client.response.Response:
        """Fetch a user's reputation history page (``/reputation.php?uid={uid}``)."""
        return await self._http.get(f'/reputation.php?uid={user_id}')