# trends.py - trend-related endpoints

from mastodon.versions import _DICT_VERSION_HASHTAG, _DICT_VERSION_STATUS, _DICT_VERSION_CARD
from mastodon.utility import api_version

from mastodon.internals import Mastodon as Internals
from mastodon.types import Tag, Status, PreviewCard, NonPaginatableList
from typing import Optional, Union

class Mastodon(Internals):
    ###
    # Reading data: Trends
    ###
    @api_version("2.4.3", "3.5.0", _DICT_VERSION_HASHTAG)
    def trends(self, limit: Optional[int] = None):
        """
        Old alias for :ref:`trending_tags() <trending_tags()>`

        Deprecated. Please use :ref:`trending_tags() <trending_tags()>` instead.
        """
        return self.trending_tags(limit=limit)

    @api_version("3.5.0", "3.5.0", _DICT_VERSION_HASHTAG)
    def trending_tags(self, limit: Optional[int] = None, lang: Optional[str] = None) -> NonPaginatableList[Tag]:
        """
        Fetch trending-hashtag information, if the instance provides such information.

        Specify `limit` to limit how many results are returned (the maximum number
        of results is 10, the endpoint is not paginated).

        Does not require authentication unless locked down by the administrator.

        Important versioning note: This endpoint does not exist for Mastodon versions
        between 2.8.0 (inclusive) and 3.0.0 (exclusive).

        Pass `lang` to override the global locale parameter, which may affect trend ordering.

        The results are sorted by the instances's trending algorithm, descending.
        """
        params = self.__generate_params(locals())
        if "lang" in params:
            del params["lang"]
        if self.verify_minimum_version("3.5.0", cached=True):
            # Starting 3.5.0, old version is deprecated
            return self.__api_request('GET', '/api/v1/trends/tags', params, lang_override=lang)
        else:
            return self.__api_request('GET', '/api/v1/trends', params, lang_override=lang)

    @api_version("3.5.0", "3.5.0", _DICT_VERSION_STATUS)
    def trending_statuses(self, limit: Optional[int] = None, offset: Optional[int] = None, lang: Optional[str] = None) -> NonPaginatableList[Status]:
        """
        Fetch trending-status information, if the instance provides such information.

        Specify `limit` to limit how many results are returned (default 20, the maximum
        number of results is 40).

        Specify `offset` to paginate results. Default 0.

        Pass `lang` to override the global locale parameter, which may affect trend ordering.

        The results are sorted by the instances's trending algorithm, descending.
        """
        params = self.__generate_params(locals())
        if "lang" in params:
            del params["lang"]
        return self.__api_request('GET', '/api/v1/trends/statuses', params, lang_override=lang)

    @api_version("3.5.0", "3.5.0", _DICT_VERSION_CARD)
    def trending_links(self, limit: Optional[int] = None, lang: Optional[str] = None) -> NonPaginatableList[PreviewCard]:
        """
        Fetch trending-link information, if the instance provides such information.

        Specify `limit` to limit how many results are returned (the maximum number
        of results is 10, the endpoint is not paginated).

        The results are sorted by the instances's trending algorithm, descending.
        """
        params = self.__generate_params(locals())
        if "lang" in params:
            del params["lang"]        
        return self.__api_request('GET', '/api/v1/trends/links', params, lang_override=lang)