client.py

# This file was auto-generated by Fern from our API Definition.

import typing

from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.request_options import RequestOptions
from ..types.countries import Countries
from ..types.from_rank import FromRank
from ..types.include_additional_info import IncludeAdditionalInfo
from ..types.is_news_domain import IsNewsDomain
from ..types.lang import Lang
from ..types.news_domain_type import NewsDomainType
from ..types.news_type import NewsType
from ..types.predefined_sources import PredefinedSources
from ..types.source_name import SourceName
from ..types.source_url import SourceUrl
from ..types.sources_response_dto import SourcesResponseDto
from ..types.to_rank import ToRank
from .raw_client import AsyncRawSourcesClient, RawSourcesClient

# this is used as the default value for optional parameters
OMIT = typing.cast(typing.Any, ...)


class SourcesClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawSourcesClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> RawSourcesClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        RawSourcesClient
        """
        return self._raw_client

    def get(
        self,
        *,
        lang: typing.Optional[str] = None,
        countries: typing.Optional[str] = None,
        predefined_sources: typing.Optional[str] = None,
        source_name: typing.Optional[str] = None,
        source_url: typing.Optional[str] = None,
        include_additional_info: typing.Optional[IncludeAdditionalInfo] = None,
        is_news_domain: typing.Optional[IsNewsDomain] = None,
        news_domain_type: typing.Optional[NewsDomainType] = None,
        news_type: typing.Optional[str] = None,
        from_rank: typing.Optional[FromRank] = None,
        to_rank: typing.Optional[ToRank] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SourcesResponseDto:
        """
        Retrieves a list of sources based on specified criteria such as language, country, rank, and more.

        Parameters
        ----------
        lang : typing.Optional[str]
            The language(s) of the search. The only accepted format is the two-letter [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) code. To select multiple languages, use a comma-separated string.

            To learn more, see [Enumerated parameters > Language](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#language-lang-and-not-lang).

        countries : typing.Optional[str]
            The countries where the news publisher is located. The accepted format is the two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. To select multiple countries, use a comma-separated string.

            To learn more, see [Enumerated parameters > Country](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#country-country-and-not-country).

        predefined_sources : typing.Optional[str]
            Predefined top news sources per country.

            Format: start with the word `top`, followed by the number of desired sources, and then the two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

            Multiple countries with the number of top sources can be specified as a comma-separated string.

        source_name : typing.Optional[str]
            Word or phrase to search within the source names. To specify multiple values, use a comma-separated string.

            **Note**: The search doesn't require an exact match and returns sources containing the specified terms in their names. You can use any word or phrase, like `"sport"` or `"new york times"`.

            For example, `"sport"` returns sources such as `"Motorsport"`, `"Dot Esport"`, and `"Tuttosport"`.

        source_url : typing.Optional[str]
            The domain(s) of the news publication to search for.

            **Caution**:  When specifying the `source_url` parameter,
            you can only use `include_additional_info` as an extra parameter.

        include_additional_info : typing.Optional[IncludeAdditionalInfo]

        is_news_domain : typing.Optional[IsNewsDomain]

        news_domain_type : typing.Optional[NewsDomainType]

        news_type : typing.Optional[str]
            Filters results based on the news type. Multiple types can be specified using a comma-separated string.

            For a complete list of available news types, see [Enumerated parameters > News type](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#news-type-news-type).

        from_rank : typing.Optional[FromRank]

        to_rank : typing.Optional[ToRank]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SourcesResponseDto
            A successful response containing a list of news sources that match the specified criteria.

        Examples
        --------
        from newscatcher import NewscatcherApi

        client = NewscatcherApi(
            api_key="YOUR_API_KEY",
        )
        client.sources.get(
            lang="en,es",
            countries="US,CA",
            predefined_sources="top 50 US, top 20 GB",
            source_name="sport,tech",
            source_url="bbc.com",
            include_additional_info=True,
            is_news_domain=True,
            news_type="General News Outlets,Tech News and Updates",
            from_rank=100,
            to_rank=100,
        )
        """
        _response = self._raw_client.get(
            lang=lang,
            countries=countries,
            predefined_sources=predefined_sources,
            source_name=source_name,
            source_url=source_url,
            include_additional_info=include_additional_info,
            is_news_domain=is_news_domain,
            news_domain_type=news_domain_type,
            news_type=news_type,
            from_rank=from_rank,
            to_rank=to_rank,
            request_options=request_options,
        )
        return _response.data

    def post(
        self,
        *,
        lang: typing.Optional[Lang] = OMIT,
        countries: typing.Optional[Countries] = OMIT,
        predefined_sources: typing.Optional[PredefinedSources] = OMIT,
        source_name: typing.Optional[SourceName] = OMIT,
        source_url: typing.Optional[SourceUrl] = OMIT,
        include_additional_info: typing.Optional[IncludeAdditionalInfo] = OMIT,
        is_news_domain: typing.Optional[IsNewsDomain] = OMIT,
        news_domain_type: typing.Optional[NewsDomainType] = OMIT,
        news_type: typing.Optional[NewsType] = OMIT,
        from_rank: typing.Optional[FromRank] = OMIT,
        to_rank: typing.Optional[ToRank] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SourcesResponseDto:
        """
        Retrieves the list of sources available in the database. You can filter the sources by language, country, and more.

        Parameters
        ----------
        lang : typing.Optional[Lang]

        countries : typing.Optional[Countries]

        predefined_sources : typing.Optional[PredefinedSources]

        source_name : typing.Optional[SourceName]

        source_url : typing.Optional[SourceUrl]

        include_additional_info : typing.Optional[IncludeAdditionalInfo]

        is_news_domain : typing.Optional[IsNewsDomain]

        news_domain_type : typing.Optional[NewsDomainType]

        news_type : typing.Optional[NewsType]

        from_rank : typing.Optional[FromRank]

        to_rank : typing.Optional[ToRank]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SourcesResponseDto
            A successful response containing a list of news sources that match the specified criteria.

        Examples
        --------
        from newscatcher import NewscatcherApi

        client = NewscatcherApi(
            api_key="YOUR_API_KEY",
        )
        client.sources.post(
            predefined_sources="top 10 US",
        )
        """
        _response = self._raw_client.post(
            lang=lang,
            countries=countries,
            predefined_sources=predefined_sources,
            source_name=source_name,
            source_url=source_url,
            include_additional_info=include_additional_info,
            is_news_domain=is_news_domain,
            news_domain_type=news_domain_type,
            news_type=news_type,
            from_rank=from_rank,
            to_rank=to_rank,
            request_options=request_options,
        )
        return _response.data


class AsyncSourcesClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawSourcesClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> AsyncRawSourcesClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        AsyncRawSourcesClient
        """
        return self._raw_client

    async def get(
        self,
        *,
        lang: typing.Optional[str] = None,
        countries: typing.Optional[str] = None,
        predefined_sources: typing.Optional[str] = None,
        source_name: typing.Optional[str] = None,
        source_url: typing.Optional[str] = None,
        include_additional_info: typing.Optional[IncludeAdditionalInfo] = None,
        is_news_domain: typing.Optional[IsNewsDomain] = None,
        news_domain_type: typing.Optional[NewsDomainType] = None,
        news_type: typing.Optional[str] = None,
        from_rank: typing.Optional[FromRank] = None,
        to_rank: typing.Optional[ToRank] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SourcesResponseDto:
        """
        Retrieves a list of sources based on specified criteria such as language, country, rank, and more.

        Parameters
        ----------
        lang : typing.Optional[str]
            The language(s) of the search. The only accepted format is the two-letter [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) code. To select multiple languages, use a comma-separated string.

            To learn more, see [Enumerated parameters > Language](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#language-lang-and-not-lang).

        countries : typing.Optional[str]
            The countries where the news publisher is located. The accepted format is the two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. To select multiple countries, use a comma-separated string.

            To learn more, see [Enumerated parameters > Country](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#country-country-and-not-country).

        predefined_sources : typing.Optional[str]
            Predefined top news sources per country.

            Format: start with the word `top`, followed by the number of desired sources, and then the two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

            Multiple countries with the number of top sources can be specified as a comma-separated string.

        source_name : typing.Optional[str]
            Word or phrase to search within the source names. To specify multiple values, use a comma-separated string.

            **Note**: The search doesn't require an exact match and returns sources containing the specified terms in their names. You can use any word or phrase, like `"sport"` or `"new york times"`.

            For example, `"sport"` returns sources such as `"Motorsport"`, `"Dot Esport"`, and `"Tuttosport"`.

        source_url : typing.Optional[str]
            The domain(s) of the news publication to search for.

            **Caution**:  When specifying the `source_url` parameter,
            you can only use `include_additional_info` as an extra parameter.

        include_additional_info : typing.Optional[IncludeAdditionalInfo]

        is_news_domain : typing.Optional[IsNewsDomain]

        news_domain_type : typing.Optional[NewsDomainType]

        news_type : typing.Optional[str]
            Filters results based on the news type. Multiple types can be specified using a comma-separated string.

            For a complete list of available news types, see [Enumerated parameters > News type](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#news-type-news-type).

        from_rank : typing.Optional[FromRank]

        to_rank : typing.Optional[ToRank]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SourcesResponseDto
            A successful response containing a list of news sources that match the specified criteria.

        Examples
        --------
        import asyncio

        from newscatcher import AsyncNewscatcherApi

        client = AsyncNewscatcherApi(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.sources.get(
                lang="en,es",
                countries="US,CA",
                predefined_sources="top 50 US, top 20 GB",
                source_name="sport,tech",
                source_url="bbc.com",
                include_additional_info=True,
                is_news_domain=True,
                news_type="General News Outlets,Tech News and Updates",
                from_rank=100,
                to_rank=100,
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get(
            lang=lang,
            countries=countries,
            predefined_sources=predefined_sources,
            source_name=source_name,
            source_url=source_url,
            include_additional_info=include_additional_info,
            is_news_domain=is_news_domain,
            news_domain_type=news_domain_type,
            news_type=news_type,
            from_rank=from_rank,
            to_rank=to_rank,
            request_options=request_options,
        )
        return _response.data

    async def post(
        self,
        *,
        lang: typing.Optional[Lang] = OMIT,
        countries: typing.Optional[Countries] = OMIT,
        predefined_sources: typing.Optional[PredefinedSources] = OMIT,
        source_name: typing.Optional[SourceName] = OMIT,
        source_url: typing.Optional[SourceUrl] = OMIT,
        include_additional_info: typing.Optional[IncludeAdditionalInfo] = OMIT,
        is_news_domain: typing.Optional[IsNewsDomain] = OMIT,
        news_domain_type: typing.Optional[NewsDomainType] = OMIT,
        news_type: typing.Optional[NewsType] = OMIT,
        from_rank: typing.Optional[FromRank] = OMIT,
        to_rank: typing.Optional[ToRank] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SourcesResponseDto:
        """
        Retrieves the list of sources available in the database. You can filter the sources by language, country, and more.

        Parameters
        ----------
        lang : typing.Optional[Lang]

        countries : typing.Optional[Countries]

        predefined_sources : typing.Optional[PredefinedSources]

        source_name : typing.Optional[SourceName]

        source_url : typing.Optional[SourceUrl]

        include_additional_info : typing.Optional[IncludeAdditionalInfo]

        is_news_domain : typing.Optional[IsNewsDomain]

        news_domain_type : typing.Optional[NewsDomainType]

        news_type : typing.Optional[NewsType]

        from_rank : typing.Optional[FromRank]

        to_rank : typing.Optional[ToRank]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SourcesResponseDto
            A successful response containing a list of news sources that match the specified criteria.

        Examples
        --------
        import asyncio

        from newscatcher import AsyncNewscatcherApi

        client = AsyncNewscatcherApi(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.sources.post(
                predefined_sources="top 10 US",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.post(
            lang=lang,
            countries=countries,
            predefined_sources=predefined_sources,
            source_name=source_name,
            source_url=source_url,
            include_additional_info=include_additional_info,
            is_news_domain=is_news_domain,
            news_domain_type=news_domain_type,
            news_type=news_type,
            from_rank=from_rank,
            to_rank=to_rank,
            request_options=request_options,
        )
        return _response.data