fake-useragent

fake-useragent generates realistic browser user-agent strings drawn from a periodically refreshed, real-world usage database (sourced from user-agents.net and processed via Intoli’s dataset) that ships bundled inside the package itself, so lookups work fully offline with no network calls at runtime. Callers can pull a random user agent across all browsers/platforms, restrict to specific browsers (Chrome, Firefox, Safari, Edge, Opera, and their mobile variants) or operating systems, and filter by minimum browser version.

It’s commonly reached for by scraping scripts, HTTP clients, and test suites that need to vary or spoof the User-Agent header rather than send a single hardcoded string that’s easy to fingerprint and block.

What You Get

• UserAgent() object with per-browser attributes (.chrome, .firefox, .safari, .edge, .opera, .random, and more)
• Dict-style ua['Chrome'] access alongside the attribute API
• browsers, os, platforms, and min_version constructor filters to narrow the returned pool
• getRandom/getBrowser(name)-style accessors returning the full UA metadata dict (percent, device, os, browser version)
• Configurable fallback string returned if a lookup fails, plus safe_attrs to avoid attribute-access collisions
• Bundled, pre-downloaded user-agent database — no network access needed at runtime

Common Use Cases

• Rotating the User-Agent header sent by a web scraper to reduce fingerprinting/blocking
• Generating realistic-looking synthetic traffic for load or integration testing
• Feeding varied user-agent strings into browser-automation or crawler test fixtures
• Simulating requests from specific browser/OS/device combinations during QA

Under The Hood

Architecture: The package is intentionally small — src/fake_useragent/fake.py implements the UserAgent class, which loads a bundled JSONL data file (src/fake_useragent/data/) at init time via utils.py’s loader, builds an in-memory pool filtered by the constructor’s browsers/os/platforms/min_version arguments, and exposes both attribute-style (__getattr__) and dict-style (__getitem__) access over that pool; errors.py defines the FakeUserAgentError raised (and caught into fallback) on lookup misses. Tech Stack: Pure Python 3.9+, zero runtime dependencies — the entire UA corpus is vendored as a JSONL file inside the package rather than fetched at runtime, which is what lets it work offline; pyproject.toml declares the data file as package data per setuptools’ data-files convention. Code Quality: A compact ~500-line src/ tree, tested via tox, linted with ruff and formatted with black, plus CodeQL security scanning wired into GitHub Actions — modest in scope but consistently maintained per its changelog, which documents a data-source migration (v1.5.0, v2.0.0) and dropped/added Python version support across releases. API Design: The dual attribute/dict access pattern (ua.chrome and ua['Chrome']) plus a permissive fallback default make the common case a one-liner (UserAgent().random), while getBrowser()/getRandom progressively expose the richer per-entry metadata dict for callers that need more than just the string.