Source code for ogu_api.resources.search

from __future__ import annotations

import tls_client.response

from ._base import ResourceBase

__all__ = ['SearchResource']




class SearchResource(ResourceBase):
    """Forum-wide search and the lookup form.

    Paths:

    - ``/search.php`` (GET) — search form.
    - ``/search.php`` (POST, ``action=do_search``) — submit search.
    - ``/search.php?action=results&sid={id}`` — paginated results page.
    - ``/lookup.php`` — quick username lookup form.
    """



    async def get_form(self) -> tls_client.response.Response:
        """Fetch the search form page (raw HTML)."""
        return await self._http.get('/search.php')




    async def search(
        self,
        keywords: str,
        *,
        author: str = '',
        forums: list[str] | None = None,
        find_thread_starters_only: bool = False,
        match_username_exactly: bool = False,
        post_or_thread: str = 'thread',
        post_date: str = '',
        post_date_direction: str = 'older',
        sort_by: str = 'lastpost',
        sort_direction: str = 'desc',
        show_results: str = 'threads',
    ) -> tls_client.response.Response:
        """Submit a search query.

        Args:
            keywords: Search keywords.
            author: Filter by post author.
            forums: List of forum ids (``fid``) to scope to.
            find_thread_starters_only: Only match the first post of each
                thread (i.e. thread starters).
            match_username_exactly: Treat ``author`` as an exact match
                instead of substring.
            post_or_thread: ``'thread'`` or ``'post'``.
            post_date: Date filter (e.g. ``'7'`` for last 7 days).
            post_date_direction: ``'older'`` or ``'newer'``.
            sort_by: ``'lastpost'``, ``'subject'``, ``'replies'``, etc.
            sort_direction: ``'asc'`` or ``'desc'``.
            show_results: ``'threads'`` or ``'posts'``.

        Returns:
            Raw POST response — usually a redirect to
            ``/search.php?action=results&sid=...``.
        """
        data: dict[str, str] = {
            'action': 'do_search',
            'keywords': keywords,
            'author': author,
            'matchusername': '1' if match_username_exactly else '',
            'postthread': post_or_thread,
            'findthreadst': '1' if find_thread_starters_only else '0',
            'postdate': post_date,
            'pddir': post_date_direction,
            'sortby': sort_by,
            'sortordr': sort_direction,
            'showresults': show_results,
        }
        if forums:
            for forum_id in forums:
                data.setdefault('forums[]', forum_id)

        return await self._http.post('/search.php', data = data)




    async def get_results(self, search_id: str) -> tls_client.response.Response:
        """Fetch the results page for a previous search by ``sid``."""
        return await self._http.get(f'/search.php?action=results&sid={search_id}')




    async def lookup(
        self,
        *,
        forum_1: str = '',
        forum_5: str = '',
    ) -> tls_client.response.Response:
        """Hit the ``/lookup.php`` quick lookup form.

        Args:
            forum_1: Value for the ``fid1`` field.
            forum_5: Value for the ``fid5`` field.
        """
        return await self._http.get(
            '/lookup.php',
            query = {'fid1': forum_1, 'fid5': forum_5},
        )