fake-useragent

from fake_useragent import UserAgent

from fake_useragent import FakeUserAgent  # Primary class (alias for UserAgent)
from fake_useragent import UserAgent, FakeUserAgentError, UserAgentError  # With exceptions
from fake_useragent import __version__  # Version info
from fake_useragent import get_version  # Version module
from fake_useragent.get_version import __version__  # Alternative version import

from fake_useragent import UserAgent

# Create a UserAgent instance with default settings
ua = UserAgent()

# Get a random user agent string
print(ua.random)
# Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:132.0) Gecko/20100101 Firefox/132.0

# Get user agents from specific browsers
print(ua.chrome)    # Chrome/Chrome Mobile user agent
print(ua.firefox)   # Firefox/Firefox Mobile user agent
print(ua.safari)    # Safari/Mobile Safari user agent
print(ua.edge)      # Edge/Edge Mobile user agent
print(ua.opera)     # Opera/Opera Mobile user agent

# Dictionary-style access
print(ua['Chrome'])  # Same as ua.chrome

# Get user agent with metadata (returns dictionary)
user_agent_data = ua.getRandom
print(user_agent_data['useragent'])  # User agent string
print(user_agent_data['browser'])    # Browser name
print(user_agent_data['os'])         # Operating system

class UserAgent:
    """
    Fake User Agent retriever.
    
    Parameters:
    - browsers (Optional[Iterable[str]]): Filter by browser names. Default includes Chrome, Firefox, Safari, Edge, Opera, and mobile variants
    - os (Optional[Iterable[str]]): Filter by operating systems. Default includes Windows, Linux, Mac OS X, Android, iOS
    - min_version (float): Minimum browser version filter. Default: 0.0
    - min_percentage (float): Minimum usage percentage filter. Default: 0.0
    - platforms (Optional[Iterable[str]]): Filter by platform types (desktop, mobile, tablet). Default: all platforms
    - fallback (str): Fallback user agent string if retrieval fails
    - safe_attrs (Optional[Iterable[str]]): Attributes protected from browser lookup
    """
    def __init__(
        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
    ): ...

@property
def random() -> str:
    """Get a random user agent string from any allowed browser."""

@property  
def chrome() -> str:
    """Get a random Chrome user agent string (includes Chrome Mobile and Chrome Mobile iOS)."""

@property
def googlechrome() -> str:
    """Alias for chrome property."""

@property
def firefox() -> str:
    """Get a random Firefox user agent string (includes Firefox Mobile and Firefox iOS)."""

@property
def ff() -> str:
    """Alias for firefox property."""

@property
def safari() -> str:
    """Get a random Safari user agent string (includes Mobile Safari)."""

@property
def opera() -> str:
    """Get a random Opera user agent string (includes Opera Mobile)."""

@property
def google() -> str:
    """Get a random Google app user agent string."""

@property
def edge() -> str:
    """Get a random Edge user agent string (includes Edge Mobile)."""

@property
def googlechrome() -> str:
    """Alias for chrome property."""

@property
def ff() -> str:
    """Alias for firefox property."""

@property
def getRandom() -> BrowserUserAgentData:
    """Get a random user agent with metadata."""

@property
def getChrome() -> BrowserUserAgentData:
    """Get a Chrome user agent with metadata."""

@property
def getFirefox() -> BrowserUserAgentData:
    """Get a Firefox user agent with metadata (Firefox only, not mobile variants)."""

@property
def getSafari() -> BrowserUserAgentData:
    """Get a Safari user agent with metadata."""

@property
def getOpera() -> BrowserUserAgentData:
    """Get an Opera user agent with metadata."""

@property
def getGoogle() -> BrowserUserAgentData:
    """Get a Google user agent with metadata."""

@property
def getEdge() -> BrowserUserAgentData:
    """Get an Edge user agent with metadata."""

def getBrowser(browsers: Union[str, list[str]]) -> BrowserUserAgentData:
    """
    Get a browser user agent based on filters.
    
    Parameters:
    - browsers: Browser name(s) to get, or "random" for any browser
    
    Returns:
    BrowserUserAgentData: User agent with additional metadata
    """

def __getattr__(attr: Union[str, list[str]]) -> Union[str, Any]:
    """
    Get a user agent string by attribute lookup.
    
    Parameters:
    - attr: Browser name to get, or "random" for any browser
    
    Returns:
    str: User agent string if not a safe_attr, otherwise attribute value
    """

def __getitem__(attr: str) -> Union[str, Any]:
    """
    Get a user agent by key lookup (dictionary-style access).
    
    Parameters:
    - attr: Browser name to get
    
    Returns:
    str: User agent string if not a safe_attr, otherwise attribute value
    """

class BrowserUserAgentData(TypedDict):
    """Schema for browser user agent data returned by getBrowser and get* properties."""
    useragent: str              # The user agent string
    percent: float              # Usage percentage of this user agent
    type: str                   # Device type: "desktop", "mobile", or "tablet"
    device_brand: Union[str, None]  # Device brand name (e.g., "Apple", "Samsung")
    browser: Union[str, None]       # Browser name (e.g., "Chrome", "Firefox")
    browser_version: str            # Full browser version (e.g., "122.0.0.0")
    browser_version_major_minor: float  # Major.minor version (e.g., 122.0)
    os: Union[str, None]           # Operating system name (e.g., "Windows", "Android")
    os_version: Union[str, None]   # OS version (e.g., "10", "14")
    platform: str                  # Platform identifier (e.g., "Win32", "iPhone")

# FakeUserAgent is an alias for UserAgent class
FakeUserAgent = UserAgent

class FakeUserAgentError(Exception):
    """Exception for any problems that are library specific."""

# Common alias
UserAgentError = FakeUserAgentError

__version__: str  # Current package version string

# The get_version module provides version information
import fake_useragent.get_version as get_version
# Access version via: get_version.__version__

from fake_useragent import UserAgent

# Only Chrome and Firefox browsers
ua = UserAgent(browsers=['Chrome', 'Firefox'])
print(ua.random)  # Will only return Chrome or Firefox user agents

# Only mobile browsers
ua = UserAgent(platforms='mobile')
print(ua.random)  # Mobile user agents only

# Only Linux operating systems
ua = UserAgent(os='Linux')
print(ua.random)  # Linux user agents only

# Recent browser versions only (version 120.0 and above)
ua = UserAgent(min_version=120.0)
print(ua.random)  # Modern browser versions only

# Combine multiple filters
ua = UserAgent(
    browsers=['Chrome', 'Firefox'],
    os=['Windows', 'Mac OS X'],
    platforms='desktop',
    min_version=100.0
)
print(ua.random)  # Desktop Chrome/Firefox on Windows/Mac, version 100+

from fake_useragent import UserAgent

ua = UserAgent()

# Get full browser data
browser_data = ua.getRandom
print(f"Browser: {browser_data['browser']}")
print(f"Version: {browser_data['browser_version']}")
print(f"OS: {browser_data['os']} {browser_data['os_version']}")
print(f"Platform: {browser_data['platform']}")
print(f"Device Type: {browser_data['type']}")
print(f"Usage %: {browser_data['percent']}")

# Get specific browser data
chrome_data = ua.getChrome
print(f"Chrome UA: {chrome_data['useragent']}")

from fake_useragent import UserAgent, FakeUserAgentError

try:
    # Custom fallback user agent
    ua = UserAgent(fallback='Custom Browser/1.0')
    
    # This will use fallback if no matching browsers found
    print(ua.unknown_browser)  # Falls back to custom string
    
except FakeUserAgentError as e:
    print(f"Library error: {e}")

from fake_useragent import UserAgent

# Protect specific attributes from being treated as browsers
ua = UserAgent(safe_attrs=['shape', 'custom_attr'])

# These will not be treated as browser lookups
ua.shape  # Returns actual attribute value, not user agent
ua.custom_attr  # Returns actual attribute value, not user agent