AndroidRemoteController/python/py/Lib/site-packages/fake_useragent/fake.py

"""Fake User Agent retriever."""

import random
from collections.abc import Iterable
from typing import Any, Optional, Union

from fake_useragent.log import logger
from fake_useragent.utils import BrowserUserAgentData, load


def _ensure_iterable(
    *, default: Iterable[str], **kwarg: Optional[Iterable[str]]
) -> list[str]:
    """Ensure the given value is an Iterable and convert it to a list.

    Args:
        default (Iterable[str]): Default iterable to use if value is `None`.
        **kwarg (Optional[Iterable[str]]): A single keyword argument containing the value to check
            and convert.

    Raises:
        ValueError: If more than one keyword argument is provided.
        TypeError: If the value is not None, not a str, and not iterable.

    Returns:
        list[str]: A list containing the items from the iterable.
    """
    if len(kwarg) != 1:
        raise ValueError(
            f"ensure_iterable expects exactly one keyword argument but got {len(kwarg)}."
        )

    param_name, value = next(iter(kwarg.items()))

    if value is None:
        return list(default)
    if isinstance(value, str):
        return [value]

    try:
        return list(value)
    except TypeError as te:
        raise TypeError(
            f"'{param_name}' must be an iterable of str, a single str, or None but got "
            f"{type(value).__name__}."
        ) from te


def _ensure_float(value: Any) -> float:
    """Ensure the given value is a float.

    Args:
        value (Any): The value to check and convert.

    Raises:
        ValueError: If the value is not a float.

    Returns:
        float: The float value.
    """
    try:
        return float(value)
    except ValueError as ve:
        msg = f"Value must be convertible to float but got {value}."
        raise ValueError(msg) from ve


def _is_magic_name(attribute_name: str) -> bool:
    """Judge whether the given attribute name is the name of a magic method(e.g. __iter__).

    Args:
        attribute_name (str): The attribute name to check.

    Returns:
        bool: Whether the given attribute name is magic.
    """
    magic_min_length = 2 * len("__") + 1
    return (
        len(attribute_name) >= magic_min_length
        and attribute_name.isascii()
        and attribute_name.startswith("__")
        and attribute_name.endswith("__")
    )


class FakeUserAgent:
    """Fake User Agent retriever.

    Args:
        browsers (Optional[Iterable[str]], optional): If given, will only ever return user agents
            from these browsers. If None, set to:
            `["Google", "Chrome", "Firefox", "Edge", "Opera"," Safari", "Android", "Yandex Browser", "Samsung Internet", "Opera Mobile",
              "Mobile Safari", "Firefox Mobile", "Firefox iOS", "Chrome Mobile", "Chrome Mobile iOS", "Mobile Safari UI/WKWebView",
              "Edge Mobile", "DuckDuckGo Mobile", "MiuiBrowser", "Whale", "Twitter", "Facebook", "Amazon Silk"]`.
            Defaults to None.
        os (Optional[Iterable[str]], optional): If given, will only ever return user agents from
            these operating systems. If None, set to `["Windows", "Linux", "Ubuntu", "Chrome OS", "Mac OS X", "Android","iOS"]`. Defaults to
            None.
        min_version (float, optional): Will only ever return user agents with versions greater than
            this one. Defaults to 0.0.
        min_percentage (float, optional): Filter user agents based on usage.
            Defaults to 0.0.
        platforms (Optional[Iterable[str]], optional): If given, will only return the user-agents with
            the provided platform type. If None, set to `["desktop", "mobile", "tablet"]`. Defaults to None.
        fallback (str, optional): User agent to use if there are any issues retrieving a user agent.
            Defaults to `"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like
            Gecko) Chrome/122.0.0.0 Safari/537.36 Edg/122.0.0.0"`.
        safe_attrs (Optional[Iterable[str]], optional): `FakeUserAgent` uses a custom `__getattr__`
            to facilitate retrieval of user agents by browser. If you need to prevent some
            attributes from being treated as browsers, pass them here. If None, all attributes will
            be treated as browsers. Defaults to ["shape"] to prevent unintended calls in IDEs like PyCharm.

    Raises:
        TypeError: If `fallback` isn't a `str` or `safe_attrs` contains non-`str` values.
    """

    def __init__(
        self,
        browsers: Optional[Iterable[str]] = None,
        os: Optional[Iterable[str]] = None,
        min_version: float = 0.0,
        min_percentage: float = 0.0,
        platforms: Optional[Iterable[str]] = None,
        fallback: str = (
            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
            "AppleWebKit/537.36 (KHTML, like Gecko) "
            "Chrome/122.0.0.0 Safari/537.36 Edg/122.0.0.0"
        ),
        safe_attrs: Optional[Iterable[str]] = None,
    ):
        self.browsers = _ensure_iterable(
            browsers=browsers,
            default=[
                "Google",
                "Chrome",
                "Firefox",
                "Edge",
                "Opera",
                "Safari",
                "Android",
                "Yandex Browser",
                "Samsung Internet",
                "Opera Mobile",
                "Mobile Safari",
                "Firefox Mobile",
                "Firefox iOS",
                "Chrome Mobile",
                "Chrome Mobile iOS",
                "Mobile Safari UI/WKWebView",
                "Edge Mobile",
                "DuckDuckGo Mobile",
                "MiuiBrowser",
                "Whale",
                "Twitter",
                "Facebook",
                "Amazon Silk",
            ],
        )

        self.os = _ensure_iterable(
            os=os,
            default=[
                "Windows",
                "Linux",
                "Ubuntu",
                "Chrome OS",
                "Mac OS X",
                "Android",
                "iOS",
            ],
        )
        self.min_percentage = _ensure_float(min_percentage)
        self.min_version = _ensure_float(min_version)

        self.platforms = _ensure_iterable(
            platforms=platforms, default=["desktop", "mobile", "tablet"]
        )

        if not isinstance(fallback, str):
            msg = f"fallback must be a str but got {type(fallback).__name__}."
            raise TypeError(msg)
        self.fallback = fallback

        if safe_attrs is None:
            safe_attrs = ["shape"]
        safe_attrs = _ensure_iterable(safe_attrs=safe_attrs, default=set())
        str_safe_attrs = [isinstance(attr, str) for attr in safe_attrs]
        if not all(str_safe_attrs):
            bad_indices = [
                idx for idx, is_str in enumerate(str_safe_attrs) if not is_str
            ]
            msg = f"safe_attrs must be an iterable of str but indices {bad_indices} are not."
            raise TypeError(msg)
        self.safe_attrs = set(safe_attrs)

        # Next, load our local data file into memory (browsers.jsonl)
        self.data_browsers = load()

    def getBrowser(self, browsers: Union[str, list[str]]) -> BrowserUserAgentData:
        """Get a browser user agent based on the filters.

        Args:
            browsers (str): The browser name(s) to get. Special keyword "random" will return a random user-agent string.

        Returns:
            BrowserUserAgentData: The user agent with additional data.
        """
        try:
            if browsers == "random":
                # Filter the browser list based on the browsers array using lambda
                # And based on OS list
                # And percentage is bigger then min percentage
                # And convert the iterator back to a list
                filtered_browsers = self._filter_useragents()
            else:
                # Or when random isn't select, we filter the browsers array based on the 'request' using lamba
                # And based on OS list
                # And percentage is bigger then min percentage
                # And convert the iterator back to a list
                filtered_browsers = self._filter_useragents(browsers_to_filter=browsers)

            # Pick a random browser user-agent from the filtered browsers
            # And return the full dict
            return random.choice(filtered_browsers)  # noqa: S311
        except (KeyError, IndexError):
            logger.warning(
                f"Error occurred during getting browser(s): {browsers}, "
                "but was suppressed with fallback.",
            )
            # Return fallback object
            return {
                "useragent": self.fallback,
                "percent": 100.0,
                "type": "desktop",
                "device_brand": None,
                "browser": "Edge",
                "browser_version": "122.0.0.0",
                "browser_version_major_minor": 122.0,
                "os": "win32",
                "os_version": "10",
                "platform": "Win32",
            }

    def _filter_useragents(
        self, browsers_to_filter: Optional[Union[str, list[str]]] = None
    ) -> list[BrowserUserAgentData]:
        """Filter the user agents based on filters set in the instance, and an optional browser name.

        User agents from the data file are filtered based on the attributes passed upon
        instantiation.

        Args:
            browsers_to_filter (Union[str, None], optional): A specific browser name you want results for in
                this particular call. If None, don't apply extra filters. Defaults to None.

        Returns:
            list[BrowserUserAgentData]: A filtered list of user agents.
        """
        # Filter based on browser, os, typem browser version and percentage (weight).

        filtered_useragents = list(
            filter(
                lambda x: x["browser"] in self.browsers
                and x["os"] in self.os
                and x["type"]
                in self.platforms  # We check platform on type here (I know it's confusing)
                and x["browser_version_major_minor"] >= self.min_version
                and x["percent"] >= self.min_percentage,
                self.data_browsers,
            )
        )

        # Filter based on a specific browser name(s), if set.
        if browsers_to_filter:
            # Ensure browsers_to_filter is always a list.
            if isinstance(browsers_to_filter, str):
                browsers_to_filter = [browsers_to_filter]

            filtered_useragents = list(
                filter(
                    lambda x: x["browser"] in browsers_to_filter, filtered_useragents
                )
            )

        return filtered_useragents

    def __getitem__(self, attr: str) -> Union[str, Any]:
        """Get a user agent by key lookup, as if it were a dictionary (i.e., `ua['random']`).

        Args:
            attr (str): Browser name to get.

        Returns:
            Union[str, Any]: The user agent string if not a `self.safe_attr`, otherwise the
                attribute value.
        """
        return self.__getattr__(attr)

    def __getattr__(self, attr: Union[str, list[str]]) -> Union[str, Any]:
        """Get a user agent string by attribute lookup.

        Args:
            attr (str): Browser name to get. Special keyword "random" will return a user agent from
                any browser allowed by the instance's `self.browsers` filter.

        Returns:
            Union[str, Any]: The user agent string if not a `self.safe_attr`, otherwise the
                attribute value.
        """
        if isinstance(attr, str):
            if _is_magic_name(attr) or attr in self.safe_attrs:
                return super(UserAgent, self).__getattribute__(attr)
        elif isinstance(attr, list):
            for a in attr:
                if a in self.safe_attrs:
                    return super(UserAgent, self).__getattribute__(a)

        return self.getBrowser(attr)["useragent"]

    @property
    def chrome(self) -> str:
        """Get a random Chrome user agent."""
        return self.__getattr__(["Chrome", "Chrome Mobile", "Chrome Mobile iOS"])

    @property
    def googlechrome(self) -> str:
        """Get a random Chrome user agent."""
        return self.chrome

    @property
    def ff(self) -> str:
        """Get a random Firefox user agent."""
        return self.firefox

    @property
    def firefox(self) -> str:
        """Get a random Firefox user agent."""
        return self.__getattr__(["Firefox", "Firefox Mobile", "Firefox iOS"])

    @property
    def safari(self) -> str:
        """Get a random Safari user agent."""
        return self.__getattr__(["Safari", "Mobile Safari"])

    @property
    def opera(self) -> str:
        """Get a random Opera user agent."""
        return self.__getattr__(["Opera", "Opera Mobile"])

    @property
    def google(self) -> str:
        """Get a random Google user agent."""
        return self.__getattr__(["Google"])

    @property
    def edge(self) -> str:
        """Get a random Edge user agent."""
        return self.__getattr__(["Edge", "Edge Mobile"])

    @property
    def random(self) -> str:
        """Get a random user agent."""
        return self.__getattr__("random")

    @property
    def getChrome(self) -> BrowserUserAgentData:
        """Get a random Chrome user agent, with additional data."""
        return self.getBrowser(["Chrome", "Chrome Mobile", "Chrome Mobile iOS"])

    @property
    def getFirefox(self) -> BrowserUserAgentData:
        """Get a random Firefox user agent, with additional data."""
        return self.getBrowser("Firefox")

    @property
    def getSafari(self) -> BrowserUserAgentData:
        """Get a random Safari user agent, with additional data."""
        return self.getBrowser(["Safari", "Mobile Safari"])

    @property
    def getOpera(self) -> BrowserUserAgentData:
        """Get a random Safari user agent, with additional data."""
        return self.getBrowser(["Opera", "Opera Mobile"])

    @property
    def getGoogle(self) -> BrowserUserAgentData:
        """Get a random Google user agent, with additional data."""
        return self.getBrowser(["Google"])

    @property
    def getEdge(self) -> BrowserUserAgentData:
        """Get a random Edge user agent, with additional data."""
        return self.getBrowser(["Edge", "Edge Mobile"])

    @property
    def getRandom(self) -> BrowserUserAgentData:
        """Get a random user agent, with additional data."""
        return self.getBrowser("random")


# common alias
UserAgent = FakeUserAgent