ua-generator

For fine-grained control, use the ua_generator.options.Options class passed to the options parameter in generate().

weighted_versions

Set options.weighted_versions = True to increase the probability of selecting the latest versions.

version_ranges

Use options.version_ranges to restrict versions to specific ranges using VersionRange and Version objects.

latest_versions

• Set options.latest_versions = True to pick only the latest version.
• Pass a dictionary to options.latest_versions to pick one of the latest N versions for specific browsers or platforms (e.g., {'chrome': 3}).

tied_safari_version

Set options.tied_safari_version = True to tie Safari versions to macOS/iOS versions.

import ua_generator
from ua_generator.options import Options
from ua_generator.data.version import Version, VersionRange

# Example: Version Ranges
options = Options()
options.version_ranges = {
    'chrome': VersionRange(125, 129),
    'edge': VersionRange(min_version=120),
    'macos': VersionRange(max_version=Version(10, 15, 7)),
}
ua = ua_generator.generate(browser='chrome', options=options)

# Example: Latest N versions
options = Options()
options.latest_versions = {'chrome': 3, 'firefox': 1}
ua = ua_generator.generate(options=options)

The object returned by generate() contains several attributes for the raw text and structured Client Hint data:

• ua.text: The full user-agent string.
• ua.platform: The selected platform name.
• ua.browser: The selected browser name.
• ua.ch.brands: List of brand strings (e.g., "Not A(Brand";v="99", "Chromium";v="129").
• ua.ch.brands_full_version_list: List of full version brand strings.
• ua.ch.mobile: Mobile indicator ('?0' or '?1').
• ua.ch.platform: The platform name for Client Hints.
• ua.ch.platform_version: The platform version.
• ua.ch.browser_version: The browser major version.
• ua.ch.browser_full_version: The full browser version string.
• ua.ch.bitness: Bit depth (e.g., '64').
• ua.ch.architecture: CPU architecture (e.g., 'x86', 'arm').
• ua.ch.wow64: WOW64 indicator ('?0' or '?1').

import ua_generator

ua = ua_generator.generate(device='desktop', browser=['chrome', 'edge'])
print(ua.text)
print(ua.ch.brands)
print(ua.ch.platform_version)

You can easily pass generated headers to common Python HTTP clients.

Requests:

import requests
import ua_generator

ua = ua_generator.generate(browser=['chrome', 'edge'])
r = requests.get('https://httpbin.org/get', headers=ua.headers.get())

HTTPX:

import httpx
import ua_generator

ua = ua_generator.generate(browser=['chrome', 'edge'])
r = httpx.get('https://httpbin.org/get', headers=ua.headers.get())

urllib:

import urllib.request
import ua_generator

ua = ua_generator.generate(browser=['chrome', 'edge'])
request = urllib.request.Request('https://httpbin.org/get', headers=ua.headers.get())
handler = urllib.request.urlopen(request)
response = handler.read().decode('utf-8')

Selenium: To use with Selenium, use execute_cdp_cmd to set extra headers and override the User Agent and Navigator metadata.

import time
from selenium import webdriver
import ua_generator

ua = ua_generator.generate(browser=['chrome', 'edge'], device=['desktop'])
driver = webdriver.Chrome()
driver.execute_cdp_cmd('Network.setExtraHTTPHeaders', {'headers': ua.headers.get()})
driver.execute_cdp_cmd('Network.setUserAgentOverride', {
    'userAgent': ua.text,
    'userAgentMetadata': ua.navigator.get()
})
driver.get('https://browserleaks.com/client-hints')

Once a UserAgent instance is initialized, it populates several attributes containing the generated data and metadata:

• text: The actual User-Agent string (e.g., "Mozilla/5.0 ..."). Use str(ua) to get this value.
• ch: A ClientHints object containing the generated Client Hints.
• headers: A Headers object containing the HTTP headers associated with the User-Agent.
• navigator: A Navigator object providing simulated navigator properties.
• generator: The underlying Generator instance used to create the data.

To get the raw string for use in requests, you can use the text attribute or simply cast the object to a string.

ua = UserAgent(device='desktop')

print(ua.text)          # The User-Agent string
print(str(ua))          # Also returns the User-Agent string
print(ua.headers)      # The associated HTTP headers
print(ua.ch)            # The Client Hints

The ClientHints class is used to extract and format HTTP Client Hint data (Sec-CH-UA) based on a generated user-agent. It provides access to various browser and device attributes formatted specifically for HTTP headers.

Attributes are accessed via property-like access (e.g., client_hints.platform), which internally uses __getattr__ to return serialized strings or lists compatible with the Client Hints specification.

Available attributes include:

• mobile: Boolean string (e.g., "?1" or "?0")
• platform: The platform name (e.g., "Windows", "macOS", "iOS")
• platform_version: The version of the operating system
• brands: A list of brand/version objects
• brands_full_version_list: A list of brand/version objects with full version numbers
• browser_version: The major version of the browser
• browser_full_version: The full version of the browser
• bitness: The CPU bitness (e.g., "64")
• architecture: The CPU architecture (e.g., "arm", "x86")
• form_factors: A list of device form factors
• model: The device model (primarily for Android)
• wow64: Boolean indicating if the platform is Windows with WOW64 support

from ua_generator import Generator
from ua_generator.client_hints import ClientHints

# Assuming 'gen' is an instance of generator.Generator
gen = Generator()
client_hints = ClientHints(gen)

# Accessing formatted Client Hint values
print(f"Platform: {client_hints.platform}")
print(f"Mobile: {client_hints.mobile}")
print(f"Brands: {client_hints.brands}")

The VersionRange class allows you to define a boundary for version filtering. You can initialize it with min_version and max_version as Version objects or as integers (which are treated as the major component).

Use the filter(versions: List[Version]) method to return a list of versions that fall within the specified range.

Behavioral Notes:

• If a component in the boundary is None, it acts as a wildcard.
• For max_version, omitted components are treated as very large numbers (allowing VersionRange(125, 129) to match any 129.x release).
• For min_version, omitted components are treated as 0.

from ua_generator.data.version import Version, VersionRange

# Define a range from version 120 to 125
vr = VersionRange(min_version=120, max_version=125)

# List of versions to test
versions = [
    Version(119, 0), 
    Version(120, 5), 
    Version(125, 0), 
    Version(126, 0)
]

filtered = vr.filter(versions)
# Result: [Version(120, 5), Version(125, 0)]